environment-variables.md
1 # Kubo environment variables 2 3 - [Variables](#variables) 4 - [`IPFS_PATH`](#ipfs_path) 5 - [`IPFS_LOGGING`](#ipfs_logging) 6 - [`IPFS_LOGGING_FMT`](#ipfs_logging_fmt) 7 - [`GOLOG_LOG_LEVEL`](#golog_log_level) 8 - [`GOLOG_LOG_FMT`](#golog_log_fmt) 9 - [`GOLOG_FILE`](#golog_file) 10 - [`GOLOG_OUTPUT`](#golog_output) 11 - [`GOLOG_TRACING_FILE`](#golog_tracing_file) 12 - [`IPFS_FUSE_DEBUG`](#ipfs_fuse_debug) 13 - [`YAMUX_DEBUG`](#yamux_debug) 14 - [`IPFS_FD_MAX`](#ipfs_fd_max) 15 - [`IPFS_DIST_PATH`](#ipfs_dist_path) 16 - [`IPFS_NS_MAP`](#ipfs_ns_map) 17 - [`IPFS_HTTP_ROUTERS`](#ipfs_http_routers) 18 - [`IPFS_HTTP_ROUTERS_FILTER_PROTOCOLS`](#ipfs_http_routers_filter_protocols) 19 - [`IPFS_CONTENT_BLOCKING_DISABLE`](#ipfs_content_blocking_disable) 20 - [`IPFS_WAIT_REPO_LOCK`](#ipfs_wait_repo_lock) 21 - [`IPFS_TELEMETRY`](#ipfs_telemetry) 22 - [`LIBP2P_TCP_REUSEPORT`](#libp2p_tcp_reuseport) 23 - [`LIBP2P_TCP_MUX`](#libp2p_tcp_mux) 24 - [`LIBP2P_MUX_PREFS`](#libp2p_mux_prefs) 25 - [`LIBP2P_RCMGR`](#libp2p_rcmgr) 26 - [`LIBP2P_DEBUG_RCMGR`](#libp2p_debug_rcmgr) 27 - [`LIBP2P_SWARM_FD_LIMIT`](#libp2p_swarm_fd_limit) 28 - [Tracing](#tracing) 29 30 # Variables 31 32 ## `IPFS_PATH` 33 34 Sets the location of the IPFS repo (where the config, blocks, etc. 35 are stored). 36 37 Default: ~/.ipfs 38 39 ## `IPFS_LOGGING` 40 41 Specifies the log level for Kubo. 42 43 `IPFS_LOGGING` is a deprecated alias for the `GOLOG_LOG_LEVEL` environment variable. See below. 44 45 ## `IPFS_LOGGING_FMT` 46 47 Specifies the log message format. 48 49 `IPFS_LOGGING_FMT` is a deprecated alias for the `GOLOG_LOG_FMT` environment variable. See below. 50 51 ## `GOLOG_LOG_LEVEL` 52 53 Specifies the log-level, both globally and on a per-subsystem basis. Level can be one of: 54 55 * `debug` 56 * `info` 57 * `warn` 58 * `error` 59 * `dpanic` 60 * `panic` 61 * `fatal` 62 63 Per-subsystem levels can be specified with `subsystem=level`. One global level and one or more per-subsystem levels 64 can be specified by separating them with commas. 65 66 Default: `error` 67 68 Example: 69 70 ```console 71 GOLOG_LOG_LEVEL="error,core/server=debug" ipfs daemon 72 ``` 73 74 Logging can also be configured at runtime, both globally and on a per-subsystem basis, with the `ipfs log` command. 75 76 ## `GOLOG_LOG_FMT` 77 78 Specifies the log message format. It supports the following values: 79 80 - `color` -- human readable, colorized (ANSI) output 81 - `nocolor` -- human readable, plain-text output. 82 - `json` -- structured JSON. 83 84 For example, to log structured JSON (for easier parsing): 85 86 ```bash 87 export GOLOG_LOG_FMT="json" 88 ``` 89 The logging format defaults to `color` when the output is a terminal, and `nocolor` otherwise. 90 91 ## `GOLOG_FILE` 92 93 Sets the file to which Kubo logs. By default, Kubo logs to standard error. 94 95 ## `GOLOG_OUTPUT` 96 97 When stderr and/or stdout options are configured or specified by the `GOLOG_OUTPUT` environ variable, log only to the output(s) specified. For example: 98 99 - `GOLOG_OUTPUT="stderr"` logs only to stderr 100 - `GOLOG_OUTPUT="stdout"` logs only to stdout 101 - `GOLOG_OUTPUT="stderr+stdout"` logs to both stderr and stdout 102 103 ## `GOLOG_TRACING_FILE` 104 105 Sets the file to which Kubo sends tracing events. By default, tracing is 106 disabled. 107 108 This log can be read at runtime (without writing it to a file) using the `ipfs 109 log tail` command. 110 111 Warning: Enabling tracing will likely affect performance. 112 113 ## `IPFS_FUSE_DEBUG` 114 115 If SET, enables fuse debug logging. 116 117 Default: false 118 119 ## `YAMUX_DEBUG` 120 121 If SET, enables debug logging for the yamux stream muxer. 122 123 Default: false 124 125 ## `IPFS_FD_MAX` 126 127 Sets the file descriptor limit for Kubo. If Kubo fails to set the file 128 descriptor limit, it will log an error. 129 130 Defaults: 2048 131 132 ## `IPFS_DIST_PATH` 133 134 IPFS Content Path from which Kubo fetches repo migrations (when the daemon 135 is launched with the `--migrate` flag). 136 137 Default: `/ipfs/<cid>` (the exact path is hardcoded in 138 `migrations.CurrentIpfsDist`, depends on the IPFS version) 139 140 ## `IPFS_NS_MAP` 141 142 Adds static namesys records for deterministic tests and debugging. 143 Useful for testing things like DNSLink without real DNS lookup. 144 145 Example: 146 147 ```console 148 $ IPFS_NS_MAP="dnslink-test1.example.com:/ipfs/bafkreicysg23kiwv34eg2d7qweipxwosdo2py4ldv42nbauguluen5v6am,dnslink-test2.example.com:/ipns/dnslink-test1.example.com" ipfs daemon 149 ... 150 $ ipfs resolve -r /ipns/dnslink-test2.example.com 151 /ipfs/bafkreicysg23kiwv34eg2d7qweipxwosdo2py4ldv42nbauguluen5v6am 152 ``` 153 154 ## `IPFS_HTTP_ROUTERS` 155 156 Overrides AutoConf and all other HTTP routers when set. 157 When `Routing.Type=auto`, this environment variable takes precedence over 158 both AutoConf-provided endpoints and any manually configured delegated routers. 159 The value should be a space or comma-separated list of HTTP routing endpoint URLs. 160 161 This is useful for: 162 - Testing and debugging in offline contexts 163 - Overriding AutoConf endpoints temporarily 164 - Using custom or private HTTP routing services 165 166 Example: 167 168 ```console 169 $ ipfs config Routing.Type auto 170 $ IPFS_HTTP_ROUTERS="http://127.0.0.1:7423" ipfs daemon 171 ``` 172 173 The above will replace all AutoConf endpoints with a single local one, allowing for 174 inspection/debug of HTTP requests sent by Kubo via `while true ; do nc -l 7423; done` 175 or more advanced tools like [mitmproxy](https://docs.mitmproxy.org/stable/#mitmproxy). 176 177 When not set, Kubo uses endpoints from AutoConf (when enabled) or manually configured `Routing.DelegatedRouters`. 178 179 ## `IPFS_HTTP_ROUTERS_FILTER_PROTOCOLS` 180 181 Overrides values passed with `filter-protocols` parameter defined in IPIP-484. 182 Value is space-separated. 183 184 ```console 185 $ IPFS_HTTP_ROUTERS_FILTER_PROTOCOLS="unknown transport-bitswap transport-foo" ipfs daemon 186 ``` 187 188 Default: `config.DefaultHTTPRoutersFilterProtocols` 189 190 ## `IPFS_CONTENT_BLOCKING_DISABLE` 191 192 Disables the content-blocking subsystem. No denylists will be watched and no 193 content will be blocked. 194 195 ## `IPFS_WAIT_REPO_LOCK` 196 197 Specifies the amount of time to wait for the repo lock. Set the value of this variable to a string that can be [parsed](https://pkg.go.dev/time@go1.24.3#ParseDuration) as a golang `time.Duration`. For example: 198 ``` 199 IPFS_WAIT_REPO_LOCK="15s" 200 ``` 201 202 If the lock cannot be acquired because someone else has the lock, and `IPFS_WAIT_REPO_LOCK` is set to a valid value, then acquiring the lock is retried every second until the lock is acquired or the specified wait time has elapsed. 203 204 ## `IPFS_TELEMETRY` 205 206 Controls the behavior of the [telemetry plugin](telemetry.md). Valid values are: 207 208 - `on`: Enables telemetry. 209 - `off`: Disables telemetry. 210 - `auto`: Like `on`, but logs an informative message about telemetry and gives user 15 minutes to opt-out before first collection. Used automatically on first run and when `IPFS_TELEMETRY` is not set. 211 212 The mode can also be set in the config file under `Plugins.Plugins.telemetry.Config.Mode`. 213 214 Example: 215 216 ```bash 217 export IPFS_TELEMETRY="off" 218 ``` 219 220 ## `LIBP2P_TCP_REUSEPORT` 221 222 Kubo tries to reuse the same source port for all connections to improve NAT 223 traversal. If this is an issue, you can disable it by setting 224 `LIBP2P_TCP_REUSEPORT` to false. 225 226 Default: `true` 227 228 ## `LIBP2P_TCP_MUX` 229 230 By default Kubo tries to reuse the same listener port for raw TCP and WebSockets transports via experimental `libp2p.ShareTCPListener()` feature introduced in [go-libp2p#2984](https://github.com/libp2p/go-libp2p/pull/2984). 231 If this is an issue, you can disable it by setting `LIBP2P_TCP_MUX` to `false` and use separate ports for each TCP transport. 232 233 > [!CAUTION] 234 > This configuration option may be removed once `libp2p.ShareTCPListener()` becomes default in go-libp2p. 235 236 Default: `true` 237 238 ## `LIBP2P_MUX_PREFS` 239 240 Deprecated: Use the `Swarm.Transports.Multiplexers` config field. 241 242 Tells Kubo which multiplexers to use in which order. 243 244 Default: "/yamux/1.0.0 /mplex/6.7.0" 245 246 ## `LIBP2P_RCMGR` 247 248 Forces [libp2p Network Resource Manager](https://github.com/libp2p/go-libp2p-resource-manager#readme) 249 to be enabled (`1`) or disabled (`0`). 250 When set, overrides [`Swarm.ResourceMgr.Enabled`](https://github.com/ipfs/kubo/blob/master/docs/config.md#swarmresourcemgrenabled) from the config. 251 252 Default: use config (not set) 253 254 ## `LIBP2P_DEBUG_RCMGR` 255 256 Enables tracing of [libp2p Network Resource Manager](https://github.com/libp2p/go-libp2p-resource-manager#readme) 257 and outputs it to `rcmgr.json.gz` 258 259 260 Default: disabled (not set) 261 262 ## `LIBP2P_SWARM_FD_LIMIT` 263 264 This variable controls the number of concurrent outbound dials (except dials to relay addresses which have their own limiting logic). 265 266 Reducing it slows down connection ballooning but might affect performance negatively. 267 268 Default: [160](https://github.com/libp2p/go-libp2p/blob/master/p2p/net/swarm/swarm_dial.go#L91) (not set) 269 270 # Tracing 271 272 For tracing configuration, please check: https://github.com/ipfs/boxo/blob/main/docs/tracing.md