diff --git a/docs/concepts/ipns.md b/docs/concepts/ipns.md index f9964982e..17d58f1f9 100644 --- a/docs/concepts/ipns.md +++ b/docs/concepts/ipns.md @@ -18,6 +18,7 @@ description: Learn about mutability in IPFS, InterPlanetary Name System (IPNS), - [Publishing IPNS records over PubSub lifecycle](#publishing-ipns-records-over-pubsub-lifecycle) - [Tradeoffs between consistency vs. availability](#tradeoffs-between-consistency-vs-availability) - [IPNS record validity](#ipns-record-validity) + - [IPNS record TTL](#ipns-record-ttl) - [Practical considerations](#practical-considerations) - [IPNS in practice](#ipns-in-practice) - [Resolving IPNS names using IPFS gateways](#resolving-ipns-names-using-ipfs-gateways) @@ -177,13 +178,32 @@ Availability means resolving to a valid IPNS record, at the cost of potentially When setting the `validity` (referred to as [`lifetime` by Kubo](https://github.com/ipfs/kubo/blob/master/docs/config.md#ipnsrecordlifetime)) field of an IPNS record, you typically need to choose whether you favor **consistency** (short validity period, e.g. 48 hours) or **availability** (long validity period, e.g. 1 month), due to the inherent trade-off between the two. +#### IPNS record TTL + +If you experience slow IPNS update propagation, the Time-to-Live (TTL) setting is the first thing to check. + +##### TTL as a Publisher + +When you publish an IPNS Record, the default TTL, which controls caching, might be set to a high value, such as one hour. If you want third-party gateways and nodes to bypass the cache and check for updates more frequently, consider lowering this value. + +- **Kubo**: Refer to the `--ttl` option in [`ipfs name publish --help`](https://docs.ipfs.tech/reference/kubo/cli/#ipfs-name-publish) for details on adjusting this setting. +- **Note**: If your IPNS Record is used behind a DNSLink (e.g., `/ipns/example.com` pointing to `/ipns/k51..libp2p-key`), the DNS TXT record at `_dnslink.example.com` has its own TTL. This DNS TTL also affects caching. Ensure that both TTL values are aligned for consistent behavior. + +##### TTL as a Gateway Operator + +You should have the ability to override the TTL provided by the publisher and set a lower cap on how long resolution results are cached. + +- **Kubo**: Configure this using the [`Ipns.MaxCacheTTL`](https://github.com/ipfs/kubo/blob/master/docs/config.md#ipnsmaxcachettl) setting. +- **Rainbow**: Adjust this with the [`RAINBOW_IPNS_MAX_CACHE_TTL`](https://github.com/ipfs/rainbow/blob/main/docs/environment-variables.md#rainbow_ipns_max_cache_ttl) environment variable. + #### Practical considerations -One of the most important things to consider with IPNS names is **how frequently you intend on updating the name**. +The most important thing to consider with IPNS names is **how frequently you intend on updating the name** and **how long a valid record should be cached before checking for an update**. -Practically, two levers within your control determine where your IPNS name is on the spectrum between consistency and availability: +Practically, levers within your control determine where your IPNS name is on the spectrum between consistency and availability: -- **IPNS record validity:** longer validity will veer towards availability. Moreover, longer validity will reduce the dependence on the key holder (which for most purposes is stored on a single machine and rare shared) since the record can continue to persist without requiring the private key holder to sign a new record. Another benefit of a longer validity is that the transport can be delegated to other nodes or services (such as [w3name](https://staging.web3.storage/docs/how-tos/w3name/)), without compromising the private key. +- **IPNS record validity:** longer validity will veer towards availability. Moreover, longer validity will reduce the dependence on the key holder (which for most purposes is stored on a single machine and rare shared) since the record can continue to persist without requiring the private key holder to sign a new record. Another benefit of a longer validity is that the transport can be delegated to other nodes or services (such as [w3name](https://docs.storacha.network/how-to/w3name/)), without compromising the private key. +- **IPNS record TTL:** longer TTL trades update propagation speed for better page load performance and resiliency. - **Transport mechanism:** the DHT veers towards consistency while PubSub veers towards availability. However, with Kubo, IPNS names are always published to the DHT, while PubSub is opt-in. For most purposes, enabling PubSub is a net gain unless you hit the upper limit of connections as a result of too many PubSub subscriptions. ## IPNS in practice