diff --git a/docs/config.md b/docs/config.md index 019b8f54610..7ed0a50561f 100644 --- a/docs/config.md +++ b/docs/config.md @@ -9,26 +9,6 @@ config file at runtime. - [The Kubo config file](#the-kubo-config-file) - [Table of Contents](#table-of-contents) - - [Profiles](#profiles) - - [`server` profile](#server-profile) - - [`randomports` profile](#randomports-profile) - - [`default-datastore` profile](#default-datastore-profile) - - [`local-discovery` profile](#local-discovery-profile) - - [`default-networking` profile](#default-networking-profile) - - [`flatfs` profile](#flatfs-profile) - - [`badgerds` profile](#badgerds-profile) - - [`lowpower` profile](#lowpower-profile) - - [`legacy-cid-v0` profile](#legacy-cid-v0-profile) - - [`test-cid-v1` profile](#test-cid-v1-profile) - - [Types](#types) - - [`flag`](#flag) - - [`priority`](#priority) - - [`strings`](#strings) - - [`duration`](#duration) - - [`optionalInteger`](#optionalinteger) - - [`optionalBytes`](#optionalbytes) - - [`optionalString`](#optionalstring) - - [`optionalDuration`](#optionalduration) - [`Addresses`](#addresses) - [`Addresses.API`](#addressesapi) - [`Addresses.Gateway`](#addressesgateway) @@ -194,196 +174,26 @@ config file at runtime. - [`Version.AgentSuffix`](#versionagentsuffix) - [`Version.SwarmCheckEnabled`](#versionswarmcheckenabled) - [`Version.SwarmCheckPercentThreshold`](#versionswarmcheckpercentthreshold) - -## Profiles - -Configuration profiles allow to tweak configuration quickly. Profiles can be -applied with the `--profile` flag to `ipfs init` or with the `ipfs config profile -apply` command. When a profile is applied a backup of the configuration file -will be created in `$IPFS_PATH`. - -The available configuration profiles are listed below. You can also find them -documented in `ipfs config profile --help`. - -### `server` profile - -Disables local [`Discovery.MDNS`](#discoverymdns) and blocks connections to -IPv4 and IPv6 prefixes that are [private, local only, or unrouteable](https://github.com/ipfs/kubo/blob/b71cf0d15904bdef21fe2eee5f1118a274309a4d/config/profile.go#L24-L43). - -Recommended when running IPFS on machines with public IPv4 addresses -at providers that interpret local IPFS discovery and traffic as netscan abuse ([example](https://github.com/ipfs/kubo/issues/10327)). - -### `randomports` profile - -Use a random port number for the incoming swarm connections. -Used for testing. - -### `default-datastore` profile - -Configures the node to use the default datastore (flatfs). - -Read the "flatfs" profile description for more information on this datastore. - -This profile may only be applied when first initializing the node. - -### `local-discovery` profile - -Enables local [`Discovery.MDNS`](#discoverymdns) (enabled by default). - -Useful to re-enable local discovery after it's disabled by another profile -(e.g., the server profile). - -`test` profile - -Reduces external interference of IPFS daemon, this -is useful when using the daemon in test environments. - -### `default-networking` profile - -Restores default network settings. -Inverse profile of the test profile. - -### `flatfs` profile - -Configures the node to use the flatfs datastore. Flatfs is the default datastore. - -This is the most battle-tested and reliable datastore. -You should use this datastore if: - -- You need a very simple and very reliable datastore, and you trust your - filesystem. This datastore stores each block as a separate file in the - underlying filesystem so it's unlikely to lose data unless there's an issue - with the underlying file system. -- You need to run garbage collection in a way that reclaims free space as soon as possible. -- You want to minimize memory usage. -- You are ok with the default speed of data import, or prefer to use `--nocopy`. - -This profile may only be applied when first initializing the node. - -### `badgerds` profile - -Configures the node to use the legacy badgerv1 datastore. - -> [!CAUTION] -> This is based on very old badger 1.x, which has known bugs and is no longer supported by the upstream team. -> It is provided here only for pre-existing users, allowing them to migrate away to more modern datastore. -> Do not use it for new deployments, unless you really, really know what you are doing. - -Also, be aware that: - -- This datastore will not properly reclaim space when your datastore is - smaller than several gigabytes. If you run IPFS with `--enable-gc`, you plan on storing very little data in - your IPFS node, and disk usage is more critical than performance, consider using - `flatfs`. -- This datastore uses up to several gigabytes of memory. -- Good for medium-size datastores, but may run into performance issues if your dataset is bigger than a terabyte. -- The current implementation is based on old badger 1.x which is no longer supported by the upstream team. - -This profile may only be applied when first initializing the node. - -### `lowpower` profile - -Reduces daemon overhead on the system. Affects node -functionality - performance of content discovery and data -fetching may be degraded. - -> [!CAUTION] -> Local data won't be announced on routing systems like Amino DHT. - -- `Swarm.ConnMgr` set to maintain minimum number of p2p connections at a time. -- Disables [`Reprovider`](#reprovider) service → no CID will be announced on Amino DHT and other routing systems(!) -- Disables [`AutoNAT`](#autonat). - -Use this profile with caution. - -### `legacy-cid-v0` profile - -Makes UnixFS import (`ipfs add`) produce legacy CIDv0 with no raw leaves, sha2-256 and 256 KiB chunks. - -> [!NOTE] -> This profile is provided for legacy users and should not be used for new projects. - -### `test-cid-v1` profile - -Makes UnixFS import (`ipfs add`) produce modern CIDv1 with raw leaves, sha2-256 and 1 MiB chunks. - -> [!NOTE] -> This profile will become the new implicit default, provided for testing purposes. -> Follow [kubo#4143](https://github.com/ipfs/kubo/issues/4143) for more details. - -## Types - -This document refers to the standard JSON types (e.g., `null`, `string`, -`number`, etc.), as well as a few custom types, described below. - -### `flag` - -Flags allow enabling and disabling features. However, unlike simple booleans, -they can also be `null` (or omitted) to indicate that the default value should -be chosen. This makes it easier for Kubo to change the defaults in the -future unless the user _explicitly_ sets the flag to either `true` (enabled) or -`false` (disabled). Flags have three possible states: - -- `null` or missing (apply the default value). -- `true` (enabled) -- `false` (disabled) - -### `priority` - -Priorities allow specifying the priority of a feature/protocol and disabling the -feature/protocol. Priorities can take one of the following values: - -- `null`/missing (apply the default priority, same as with flags) -- `false` (disabled) -- `1 - 2^63` (priority, lower is preferred) - -### `strings` - -Strings is a special type for conveniently specifying a single string, an array -of strings, or null: - -- `null` -- `"a single string"` -- `["an", "array", "of", "strings"]` - -### `duration` - -Duration is a type for describing lengths of time, using the same format go -does (e.g, `"1d2h4m40.01s"`). - -### `optionalInteger` - -Optional integers allow specifying some numerical value which has -an implicit default when missing from the config file: - -- `null`/missing will apply the default value defined in Kubo sources (`.WithDefault(value)`) -- an integer between `-2^63` and `2^63-1` (i.e. `-9223372036854775808` to `9223372036854775807`) - -### `optionalBytes` - -Optional Bytes allow specifying some number of bytes which has -an implicit default when missing from the config file: - -- `null`/missing (apply the default value defined in Kubo sources) -- a string value indicating the number of bytes, including human readable representations: - - [SI sizes](https://en.wikipedia.org/wiki/Metric_prefix#List_of_SI_prefixes) (metric units, powers of 1000), e.g. `1B`, `2kB`, `3MB`, `4GB`, `5TB`, …) - - [IEC sizes](https://en.wikipedia.org/wiki/Binary_prefix#IEC_prefixes) (binary units, powers of 1024), e.g. `1B`, `2KiB`, `3MiB`, `4GiB`, `5TiB`, …) - -### `optionalString` - -Optional strings allow specifying some string value which has -an implicit default when missing from the config file: - -- `null`/missing will apply the default value defined in Kubo sources (`.WithDefault("value")`) -- a string - -### `optionalDuration` - -Optional durations allow specifying some duration value which has -an implicit default when missing from the config file: - -- `null`/missing will apply the default value defined in Kubo sources (`.WithDefault("1h2m3s")`) -- a string with a valid [go duration](#duration) (e.g, `"1d2h4m40.01s"`). + - [Profiles](#profiles) + - [`server` profile](#server-profile) + - [`randomports` profile](#randomports-profile) + - [`default-datastore` profile](#default-datastore-profile) + - [`local-discovery` profile](#local-discovery-profile) + - [`default-networking` profile](#default-networking-profile) + - [`flatfs` profile](#flatfs-profile) + - [`badgerds` profile](#badgerds-profile) + - [`lowpower` profile](#lowpower-profile) + - [`legacy-cid-v0` profile](#legacy-cid-v0-profile) + - [`test-cid-v1` profile](#test-cid-v1-profile) + - [Types](#types) + - [`flag`](#flag) + - [`priority`](#priority) + - [`strings`](#strings) + - [`duration`](#duration) + - [`optionalInteger`](#optionalinteger) + - [`optionalBytes`](#optionalbytes) + - [`optionalString`](#optionalstring) + - [`optionalDuration`](#optionalduration) ## `Addresses` @@ -2513,3 +2323,193 @@ trigger update warning. Default: `5` Type: `optionalInteger` (1-100) + +## Profiles + +Configuration profiles allow to tweak configuration quickly. Profiles can be +applied with the `--profile` flag to `ipfs init` or with the `ipfs config profile +apply` command. When a profile is applied a backup of the configuration file +will be created in `$IPFS_PATH`. + +The available configuration profiles are listed below. You can also find them +documented in `ipfs config profile --help`. + +### `server` profile + +Disables local [`Discovery.MDNS`](#discoverymdns) and blocks connections to +IPv4 and IPv6 prefixes that are [private, local only, or unrouteable](https://github.com/ipfs/kubo/blob/b71cf0d15904bdef21fe2eee5f1118a274309a4d/config/profile.go#L24-L43). + +Recommended when running IPFS on machines with public IPv4 addresses +at providers that interpret local IPFS discovery and traffic as netscan abuse ([example](https://github.com/ipfs/kubo/issues/10327)). + +### `randomports` profile + +Use a random port number for the incoming swarm connections. +Used for testing. + +### `default-datastore` profile + +Configures the node to use the default datastore (flatfs). + +Read the "flatfs" profile description for more information on this datastore. + +This profile may only be applied when first initializing the node. + +### `local-discovery` profile + +Enables local [`Discovery.MDNS`](#discoverymdns) (enabled by default). + +Useful to re-enable local discovery after it's disabled by another profile +(e.g., the server profile). + +`test` profile + +Reduces external interference of IPFS daemon, this +is useful when using the daemon in test environments. + +### `default-networking` profile + +Restores default network settings. +Inverse profile of the test profile. + +### `flatfs` profile + +Configures the node to use the flatfs datastore. Flatfs is the default datastore. + +This is the most battle-tested and reliable datastore. +You should use this datastore if: + +- You need a very simple and very reliable datastore, and you trust your + filesystem. This datastore stores each block as a separate file in the + underlying filesystem so it's unlikely to lose data unless there's an issue + with the underlying file system. +- You need to run garbage collection in a way that reclaims free space as soon as possible. +- You want to minimize memory usage. +- You are ok with the default speed of data import, or prefer to use `--nocopy`. + +This profile may only be applied when first initializing the node. + +### `badgerds` profile + +Configures the node to use the legacy badgerv1 datastore. + +> [!CAUTION] +> This is based on very old badger 1.x, which has known bugs and is no longer supported by the upstream team. +> It is provided here only for pre-existing users, allowing them to migrate away to more modern datastore. +> Do not use it for new deployments, unless you really, really know what you are doing. + +Also, be aware that: + +- This datastore will not properly reclaim space when your datastore is + smaller than several gigabytes. If you run IPFS with `--enable-gc`, you plan on storing very little data in + your IPFS node, and disk usage is more critical than performance, consider using + `flatfs`. +- This datastore uses up to several gigabytes of memory. +- Good for medium-size datastores, but may run into performance issues if your dataset is bigger than a terabyte. +- The current implementation is based on old badger 1.x which is no longer supported by the upstream team. + +This profile may only be applied when first initializing the node. + +### `lowpower` profile + +Reduces daemon overhead on the system. Affects node +functionality - performance of content discovery and data +fetching may be degraded. + +> [!CAUTION] +> Local data won't be announced on routing systems like Amino DHT. + +- `Swarm.ConnMgr` set to maintain minimum number of p2p connections at a time. +- Disables [`Reprovider`](#reprovider) service → no CID will be announced on Amino DHT and other routing systems(!) +- Disables [`AutoNAT`](#autonat). + +Use this profile with caution. + +### `legacy-cid-v0` profile + +Makes UnixFS import (`ipfs add`) produce legacy CIDv0 with no raw leaves, sha2-256 and 256 KiB chunks. + +> [!NOTE] +> This profile is provided for legacy users and should not be used for new projects. + +### `test-cid-v1` profile + +Makes UnixFS import (`ipfs add`) produce modern CIDv1 with raw leaves, sha2-256 and 1 MiB chunks. + +> [!NOTE] +> This profile will become the new implicit default, provided for testing purposes. +> Follow [kubo#4143](https://github.com/ipfs/kubo/issues/4143) for more details. + +## Types + +This document refers to the standard JSON types (e.g., `null`, `string`, +`number`, etc.), as well as a few custom types, described below. + +### `flag` + +Flags allow enabling and disabling features. However, unlike simple booleans, +they can also be `null` (or omitted) to indicate that the default value should +be chosen. This makes it easier for Kubo to change the defaults in the +future unless the user _explicitly_ sets the flag to either `true` (enabled) or +`false` (disabled). Flags have three possible states: + +- `null` or missing (apply the default value). +- `true` (enabled) +- `false` (disabled) + +### `priority` + +Priorities allow specifying the priority of a feature/protocol and disabling the +feature/protocol. Priorities can take one of the following values: + +- `null`/missing (apply the default priority, same as with flags) +- `false` (disabled) +- `1 - 2^63` (priority, lower is preferred) + +### `strings` + +Strings is a special type for conveniently specifying a single string, an array +of strings, or null: + +- `null` +- `"a single string"` +- `["an", "array", "of", "strings"]` + +### `duration` + +Duration is a type for describing lengths of time, using the same format go +does (e.g, `"1d2h4m40.01s"`). + +### `optionalInteger` + +Optional integers allow specifying some numerical value which has +an implicit default when missing from the config file: + +- `null`/missing will apply the default value defined in Kubo sources (`.WithDefault(value)`) +- an integer between `-2^63` and `2^63-1` (i.e. `-9223372036854775808` to `9223372036854775807`) + +### `optionalBytes` + +Optional Bytes allow specifying some number of bytes which has +an implicit default when missing from the config file: + +- `null`/missing (apply the default value defined in Kubo sources) +- a string value indicating the number of bytes, including human readable representations: + - [SI sizes](https://en.wikipedia.org/wiki/Metric_prefix#List_of_SI_prefixes) (metric units, powers of 1000), e.g. `1B`, `2kB`, `3MB`, `4GB`, `5TB`, …) + - [IEC sizes](https://en.wikipedia.org/wiki/Binary_prefix#IEC_prefixes) (binary units, powers of 1024), e.g. `1B`, `2KiB`, `3MiB`, `4GiB`, `5TiB`, …) + +### `optionalString` + +Optional strings allow specifying some string value which has +an implicit default when missing from the config file: + +- `null`/missing will apply the default value defined in Kubo sources (`.WithDefault("value")`) +- a string + +### `optionalDuration` + +Optional durations allow specifying some duration value which has +an implicit default when missing from the config file: + +- `null`/missing will apply the default value defined in Kubo sources (`.WithDefault("1h2m3s")`) +- a string with a valid [go duration](#duration) (e.g, `"1d2h4m40.01s"`).