From 9023bde0bfd8e4bcd74fd66c3ff3cd00d29f873c Mon Sep 17 00:00:00 2001 From: Marcin Rataj Date: Wed, 26 Feb 2025 16:37:59 +0100 Subject: [PATCH 1/4] docs: ipns ttl tips --- docs/concepts/ipns.md | 12 ++++++++++++ 1 file changed, 12 insertions(+) diff --git a/docs/concepts/ipns.md b/docs/concepts/ipns.md index f9964982e..a3c061f3b 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) @@ -173,6 +174,17 @@ Consistency means ensuring that users resolve to the latest published IPNS recor Availability means resolving to a valid IPNS record, at the cost of potentially resolving to an outdated record. +#### IPNS record TTL + +If experience slow IPNS update propagation, TTL is the first thing to check. + +- **As Publisher:** when you publish IPNS Record, the default TTL that controls caching may be set to high value, such as 1h. If you want third-party gateways and nodes to skip cache and look for updates more often, consider lowering this value. + - Kubo: see `--ttl` in `ipfs name publish --help` + - **Note:** If you use IPNS Record behind a DNSLink (`/ipns/example.com` pointing at `/ipns/k51..libp2p-key`), the DNS TXT record at `_dnslink.example.com`) has its own TTL, and it will also impact caching. Make sure both TTLs are the same. +- **As Gateway Operator:** you should have the ability to override publisher-provided TTL and cap caching resolution results at a lower value. + - Kubo: [`Ipns.MaxCacheTTL`](https://github.com/ipfs/kubo/blob/master/docs/config.md#ipnsmaxcachettl) + - Rainbow: [`RAINBOW_IPNS_MAX_CACHE_TTL`](https://github.com/ipfs/rainbow/blob/main/docs/environment-variables.md#rainbow_ipns_max_cache_ttl) + #### IPNS record validity 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. From 0e21b1809cce14b14c44b1006d24e4b5e601324c Mon Sep 17 00:00:00 2001 From: Marcin Rataj Date: Wed, 26 Feb 2025 16:43:26 +0100 Subject: [PATCH 2/4] Update ipns.md --- docs/concepts/ipns.md | 25 ++++++++++++++++--------- 1 file changed, 16 insertions(+), 9 deletions(-) diff --git a/docs/concepts/ipns.md b/docs/concepts/ipns.md index a3c061f3b..699881d45 100644 --- a/docs/concepts/ipns.md +++ b/docs/concepts/ipns.md @@ -174,20 +174,27 @@ Consistency means ensuring that users resolve to the latest published IPNS recor Availability means resolving to a valid IPNS record, at the cost of potentially resolving to an outdated record. +#### IPNS record validity + +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 experience slow IPNS update propagation, TTL is the first thing to check. +If you experience slow IPNS update propagation, the Time-to-Live (TTL) setting is the first thing to check. -- **As Publisher:** when you publish IPNS Record, the default TTL that controls caching may be set to high value, such as 1h. If you want third-party gateways and nodes to skip cache and look for updates more often, consider lowering this value. - - Kubo: see `--ttl` in `ipfs name publish --help` - - **Note:** If you use IPNS Record behind a DNSLink (`/ipns/example.com` pointing at `/ipns/k51..libp2p-key`), the DNS TXT record at `_dnslink.example.com`) has its own TTL, and it will also impact caching. Make sure both TTLs are the same. -- **As Gateway Operator:** you should have the ability to override publisher-provided TTL and cap caching resolution results at a lower value. - - Kubo: [`Ipns.MaxCacheTTL`](https://github.com/ipfs/kubo/blob/master/docs/config.md#ipnsmaxcachettl) - - Rainbow: [`RAINBOW_IPNS_MAX_CACHE_TTL`](https://github.com/ipfs/rainbow/blob/main/docs/environment-variables.md#rainbow_ipns_max_cache_ttl) +##### TTL as a Publisher -#### IPNS record validity +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. -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. +- **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 From e795418aba8298d22caea5636b2dc9e0ae9950ae Mon Sep 17 00:00:00 2001 From: Marcin Rataj Date: Wed, 26 Feb 2025 16:50:41 +0100 Subject: [PATCH 3/4] Update ipns.md --- docs/concepts/ipns.md | 7 ++++--- 1 file changed, 4 insertions(+), 3 deletions(-) diff --git a/docs/concepts/ipns.md b/docs/concepts/ipns.md index 699881d45..fcc5c394c 100644 --- a/docs/concepts/ipns.md +++ b/docs/concepts/ipns.md @@ -198,11 +198,12 @@ You should have the ability to override the TTL provided by the publisher and se #### 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 wil trade 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 From d06e4db977824ce585f29f36190f27021148b43c Mon Sep 17 00:00:00 2001 From: Marcin Rataj Date: Wed, 26 Feb 2025 18:04:25 +0100 Subject: [PATCH 4/4] Update docs/concepts/ipns.md Co-authored-by: Daniel Norman <1992255+2color@users.noreply.github.com> --- docs/concepts/ipns.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/concepts/ipns.md b/docs/concepts/ipns.md index fcc5c394c..17d58f1f9 100644 --- a/docs/concepts/ipns.md +++ b/docs/concepts/ipns.md @@ -203,7 +203,7 @@ The most important thing to consider with IPNS names is **how frequently you int 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://docs.storacha.network/how-to/w3name/)), without compromising the private key. -- **IPNS record TTL:** longer TTL wil trade update propagation speed for better page load performance and resiliency. +- **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