| 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 | - [`HTTPS_PROXY`](#https_proxy) |
| 23 | - [`HTTP_PROXY`](#http_proxy) |
| 24 | - [`NO_PROXY`](#no_proxy) |
| 25 | - [`LIBP2P_TCP_REUSEPORT`](#libp2p_tcp_reuseport) |
| 26 | - [`LIBP2P_TCP_MUX`](#libp2p_tcp_mux) |
| 27 | - [`LIBP2P_MUX_PREFS`](#libp2p_mux_prefs) |
| 28 | - [`LIBP2P_RCMGR`](#libp2p_rcmgr) |
| 29 | - [`LIBP2P_DEBUG_RCMGR`](#libp2p_debug_rcmgr) |
| 30 | - [`LIBP2P_SWARM_FD_LIMIT`](#libp2p_swarm_fd_limit) |
| 31 | - [Tracing](#tracing) |
| 32 | |
| 33 | # Variables |
| 34 | |
| 35 | ## `IPFS_PATH` |
| 36 | |
| 37 | Sets the location of the IPFS repo (where the config, blocks, etc. |
| 38 | are stored). |
| 39 | |
| 40 | Default: ~/.ipfs |
| 41 | |
| 42 | ## `IPFS_LOGGING` |
| 43 | |
| 44 | Specifies the log level for Kubo. |
| 45 | |
| 46 | `IPFS_LOGGING` is a deprecated alias for the `GOLOG_LOG_LEVEL` environment variable. See below. |
| 47 | |
| 48 | ## `IPFS_LOGGING_FMT` |
| 49 | |
| 50 | Specifies the log message format. |
| 51 | |
| 52 | `IPFS_LOGGING_FMT` is a deprecated alias for the `GOLOG_LOG_FMT` environment variable. See below. |
| 53 | |
| 54 | ## `GOLOG_LOG_LEVEL` |
| 55 | |
| 56 | Specifies the log-level, both globally and on a per-subsystem basis. Level can be one of: |
| 57 | |
| 58 | * `debug` |
| 59 | * `info` |
| 60 | * `warn` |
| 61 | * `error` |
| 62 | * `dpanic` |
| 63 | * `panic` |
| 64 | * `fatal` |
| 65 | |
| 66 | Per-subsystem levels can be specified with `subsystem=level`. One global level and one or more per-subsystem levels |
| 67 | can be specified by separating them with commas. |
| 68 | |
| 69 | Default: `error` |
| 70 | |
| 71 | Example: |
| 72 | |
| 73 | ```console |
| 74 | GOLOG_LOG_LEVEL="error,core/server=debug" ipfs daemon |
| 75 | ``` |
| 76 | |
| 77 | Logging can also be configured at runtime, both globally and on a per-subsystem basis, with the `ipfs log` command. |
| 78 | |
| 79 | See [Known logger subsystems](./debug-guide.md#known-logger-subsystems) for subsystem names related to the provide/reprovide pipeline. |
| 80 | |
| 81 | ## `GOLOG_LOG_FMT` |
| 82 | |
| 83 | Specifies the log message format. It supports the following values: |
| 84 | |
| 85 | - `color` -- human readable, colorized (ANSI) output |
| 86 | - `nocolor` -- human readable, plain-text output. |
| 87 | - `json` -- structured JSON. |
| 88 | |
| 89 | For example, to log structured JSON (for easier parsing): |
| 90 | |
| 91 | ```bash |
| 92 | export GOLOG_LOG_FMT="json" |
| 93 | ``` |
| 94 | The logging format defaults to `color` when the output is a terminal, and `nocolor` otherwise. |
| 95 | |
| 96 | ## `GOLOG_FILE` |
| 97 | |
| 98 | Sets the file to which Kubo logs. By default, Kubo logs to standard error. |
| 99 | |
| 100 | ## `GOLOG_OUTPUT` |
| 101 | |
| 102 | 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: |
| 103 | |
| 104 | - `GOLOG_OUTPUT="stderr"` logs only to stderr |
| 105 | - `GOLOG_OUTPUT="stdout"` logs only to stdout |
| 106 | - `GOLOG_OUTPUT="stderr+stdout"` logs to both stderr and stdout |
| 107 | |
| 108 | ## `GOLOG_TRACING_FILE` |
| 109 | |
| 110 | Sets the file to which Kubo sends tracing events. By default, tracing is |
| 111 | disabled. |
| 112 | |
| 113 | This log can be read at runtime (without writing it to a file) using the `ipfs |
| 114 | log tail` command. |
| 115 | |
| 116 | Warning: Enabling tracing will likely affect performance. |
| 117 | |
| 118 | ## `IPFS_FUSE_DEBUG` |
| 119 | |
| 120 | When set to any non-empty value, logs every FUSE operation (open, read, write, lookup, getattr, etc.) to stderr with its arguments and return values. Useful for diagnosing mount issues or inspecting what the kernel requests. |
| 121 | |
| 122 | Default: not set (no debug logging) |
| 123 | |
| 124 | ## `YAMUX_DEBUG` |
| 125 | |
| 126 | If SET, enables debug logging for the yamux stream muxer. |
| 127 | |
| 128 | Default: false |
| 129 | |
| 130 | ## `IPFS_FD_MAX` |
| 131 | |
| 132 | Sets the file descriptor limit for Kubo. If Kubo fails to set the file |
| 133 | descriptor limit, it will log an error. |
| 134 | |
| 135 | Defaults: 2048 |
| 136 | |
| 137 | ## `IPFS_DIST_PATH` |
| 138 | |
| 139 | IPFS Content Path from which Kubo fetches repo migrations (when the daemon |
| 140 | is launched with the `--migrate` flag). |
| 141 | |
| 142 | Default: `/ipfs/<cid>` (the exact path is hardcoded in |
| 143 | `migrations.CurrentIpfsDist`, depends on the IPFS version) |
| 144 | |
| 145 | ## `IPFS_NS_MAP` |
| 146 | |
| 147 | Adds static namesys records for deterministic tests and debugging. |
| 148 | Useful for testing things like DNSLink without real DNS lookup. |
| 149 | |
| 150 | Example: |
| 151 | |
| 152 | ```console |
| 153 | $ IPFS_NS_MAP="dnslink-test1.example.com:/ipfs/bafkreicysg23kiwv34eg2d7qweipxwosdo2py4ldv42nbauguluen5v6am,dnslink-test2.example.com:/ipns/dnslink-test1.example.com" ipfs daemon |
| 154 | ... |
| 155 | $ ipfs resolve -r /ipns/dnslink-test2.example.com |
| 156 | /ipfs/bafkreicysg23kiwv34eg2d7qweipxwosdo2py4ldv42nbauguluen5v6am |
| 157 | ``` |
| 158 | |
| 159 | ## `IPFS_HTTP_ROUTERS` |
| 160 | |
| 161 | Overrides AutoConf and all other HTTP routers when set. |
| 162 | When `Routing.Type=auto`, this environment variable takes precedence over |
| 163 | both AutoConf-provided endpoints and any manually configured delegated routers. |
| 164 | The value should be a space or comma-separated list of HTTP routing endpoint URLs. |
| 165 | |
| 166 | This is useful for: |
| 167 | - Testing and debugging in offline contexts |
| 168 | - Overriding AutoConf endpoints temporarily |
| 169 | - Using custom or private HTTP routing services |
| 170 | |
| 171 | Example: |
| 172 | |
| 173 | ```console |
| 174 | $ ipfs config Routing.Type auto |
| 175 | $ IPFS_HTTP_ROUTERS="http://127.0.0.1:7423" ipfs daemon |
| 176 | ``` |
| 177 | |
| 178 | The above will replace all AutoConf endpoints with a single local one, allowing for |
| 179 | inspection/debug of HTTP requests sent by Kubo via `while true ; do nc -l 7423; done` |
| 180 | or more advanced tools like [mitmproxy](https://docs.mitmproxy.org/stable/#mitmproxy). |
| 181 | |
| 182 | When not set, Kubo uses endpoints from AutoConf (when enabled) or manually configured `Routing.DelegatedRouters`. |
| 183 | |
| 184 | ## `IPFS_HTTP_ROUTERS_FILTER_PROTOCOLS` |
| 185 | |
| 186 | Overrides values passed with `filter-protocols` parameter defined in IPIP-484. |
| 187 | Value is space-separated. |
| 188 | |
| 189 | ```console |
| 190 | $ IPFS_HTTP_ROUTERS_FILTER_PROTOCOLS="unknown transport-bitswap transport-foo" ipfs daemon |
| 191 | ``` |
| 192 | |
| 193 | Default: `config.DefaultHTTPRoutersFilterProtocols` |
| 194 | |
| 195 | ## `IPFS_CONTENT_BLOCKING_DISABLE` |
| 196 | |
| 197 | Disables the content-blocking subsystem. No denylists will be watched and no |
| 198 | content will be blocked. |
| 199 | |
| 200 | ## `IPFS_WAIT_REPO_LOCK` |
| 201 | |
| 202 | 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: |
| 203 | ``` |
| 204 | IPFS_WAIT_REPO_LOCK="15s" |
| 205 | ``` |
| 206 | |
| 207 | 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. |
| 208 | |
| 209 | ## `IPFS_TELEMETRY` |
| 210 | |
| 211 | Controls the behavior of the [telemetry plugin](telemetry.md). Valid values are: |
| 212 | |
| 213 | - `on`: Enables telemetry. |
| 214 | - `off`: Disables telemetry. |
| 215 | - `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. |
| 216 | |
| 217 | The mode can also be set in the config file under `Plugins.Plugins.telemetry.Config.Mode`. |
| 218 | |
| 219 | Example: |
| 220 | |
| 221 | ```bash |
| 222 | export IPFS_TELEMETRY="off" |
| 223 | ``` |
| 224 | |
| 225 | ## `HTTPS_PROXY` |
| 226 | |
| 227 | Proxy for outbound `https://` HTTP requests and `/wss` libp2p WebSocket peer dials. Kubo relies on Go's `http.ProxyFromEnvironment`, which is honored by every HTTP client in the default code paths: |
| 228 | |
| 229 | - `ipfs` CLI talking to a remote daemon over [Kubo RPC](https://docs.ipfs.tech/reference/kubo/rpc/). |
| 230 | - Programmatic [Kubo RPC](https://docs.ipfs.tech/reference/kubo/rpc/) client (`client/rpc`) used by third-party Go applications. |
| 231 | - `ipfs update` downloader fetching release binaries and checksums from GitHub. |
| 232 | - Delegated HTTP routing configured via [`Routing.DelegatedRouters`](config.md#routingdelegatedrouters). |
| 233 | - HTTP block retrieval used by Bitswap against [Trustless Gateways](https://specs.ipfs.tech/http-gateways/trustless-gateway/). |
| 234 | - AutoConf fetch of network bootstrap defaults ([`AutoConf.URL`](config.md#autoconfurl)). |
| 235 | - AutoTLS ACME cert issuance via [`certmagic`](https://github.com/caddyserver/certmagic): both the challenge broker request to `p2p-forge` and the ACME flow to the configured CA (Let's Encrypt by default). |
| 236 | - go-libp2p WebSocket transport for `/wss` outbound peer dials (`gorilla/websocket` `DefaultDialer`). |
| 237 | |
| 238 | Accepted forms: |
| 239 | |
| 240 | - `http://host:port`: plain HTTP proxy; TLS targets tunnel through `CONNECT`. Works for both `https://` and `wss://`. |
| 241 | - `https://host:port`: proxy itself is reached over TLS. Requires Kubo 0.41 or newer. |
| 242 | - Basic auth is supported: `http://user:pass@host:port`. |
| 243 | |
| 244 | Example: |
| 245 | |
| 246 | ```console |
| 247 | HTTPS_PROXY=http://proxy.local:8080 ipfs daemon |
| 248 | ``` |
| 249 | |
| 250 | Scope: |
| 251 | |
| 252 | - Outbound only. Inbound listeners (`/ws`, `/wss`, gateway, RPC) are not affected. |
| 253 | - Direct libp2p transports (TCP, QUIC, WebTransport, WebRTC) do not use a proxy. |
| 254 | |
| 255 | ## `HTTP_PROXY` |
| 256 | |
| 257 | Same as [`HTTPS_PROXY`](#https_proxy), applied to `http://` URLs and `/ws` libp2p WebSocket peer dials. |
| 258 | |
| 259 | ## `NO_PROXY` |
| 260 | |
| 261 | Comma-separated list of host names, domain suffixes (prefixed with a dot), or CIDR blocks that bypass [`HTTP_PROXY`](#http_proxy) and [`HTTPS_PROXY`](#https_proxy). |
| 262 | |
| 263 | Example: |
| 264 | |
| 265 | ```console |
| 266 | NO_PROXY="localhost,127.0.0.1,.internal" HTTPS_PROXY=http://proxy.local:8080 ipfs daemon |
| 267 | ``` |
| 268 | |
| 269 | ## `LIBP2P_TCP_REUSEPORT` |
| 270 | |
| 271 | Kubo tries to reuse the same source port for all connections to improve NAT |
| 272 | traversal. If this is an issue, you can disable it by setting |
| 273 | `LIBP2P_TCP_REUSEPORT` to false. |
| 274 | |
| 275 | Default: `true` |
| 276 | |
| 277 | ## `LIBP2P_TCP_MUX` |
| 278 | |
| 279 | 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). |
| 280 | If this is an issue, you can disable it by setting `LIBP2P_TCP_MUX` to `false` and use separate ports for each TCP transport. |
| 281 | |
| 282 | > [!CAUTION] |
| 283 | > This configuration option may be removed once `libp2p.ShareTCPListener()` becomes default in go-libp2p. |
| 284 | |
| 285 | Default: `true` |
| 286 | |
| 287 | ## `LIBP2P_MUX_PREFS` |
| 288 | |
| 289 | Deprecated: Use the `Swarm.Transports.Multiplexers` config field. |
| 290 | |
| 291 | Tells Kubo which multiplexers to use in which order. |
| 292 | |
| 293 | Default: "/yamux/1.0.0 /mplex/6.7.0" |
| 294 | |
| 295 | ## `LIBP2P_RCMGR` |
| 296 | |
| 297 | Forces [libp2p Network Resource Manager](https://github.com/libp2p/go-libp2p-resource-manager#readme) |
| 298 | to be enabled (`1`) or disabled (`0`). |
| 299 | When set, overrides [`Swarm.ResourceMgr.Enabled`](https://github.com/ipfs/kubo/blob/master/docs/config.md#swarmresourcemgrenabled) from the config. |
| 300 | |
| 301 | Default: use config (not set) |
| 302 | |
| 303 | ## `LIBP2P_DEBUG_RCMGR` |
| 304 | |
| 305 | Enables tracing of [libp2p Network Resource Manager](https://github.com/libp2p/go-libp2p-resource-manager#readme) |
| 306 | and outputs it to `rcmgr.json.gz` |
| 307 | |
| 308 | |
| 309 | Default: disabled (not set) |
| 310 | |
| 311 | ## `LIBP2P_SWARM_FD_LIMIT` |
| 312 | |
| 313 | This variable controls the number of concurrent outbound dials (except dials to relay addresses which have their own limiting logic). |
| 314 | |
| 315 | Reducing it slows down connection ballooning but might affect performance negatively. |
| 316 | |
| 317 | Default: [160](https://github.com/libp2p/go-libp2p/blob/master/p2p/net/swarm/swarm_dial.go#L91) (not set) |
| 318 | |
| 319 | ## `TEST_DHT_STUB` |
| 320 | |
| 321 | Lifts WAN DHT filters so kubo can operate against DHT peers on |
| 322 | loopback, enabling end-to-end provide/findprovs/IPNS testing |
| 323 | without public internet access. Exercises every DHT code path: |
| 324 | dial, protocol negotiation, message serialization, routing table |
| 325 | management. |
| 326 | |
| 327 | Filters removed on the WAN DHT when this variable is set: |
| 328 | |
| 329 | - `AddressFilter`: accepts loopback addresses (default rejects non-public) |
| 330 | - `QueryFilter`: accepts all peers (default rejects non-public) |
| 331 | - `RoutingTableFilter`: accepts all peers (default rejects non-public) |
| 332 | - `RoutingTablePeerDiversityFilter`: disabled (default caps same-IP peers to 3) |
| 333 | |
| 334 | In the CLI test harness, `h.BootstrapWithStubDHT(nodes)` spawns a |
| 335 | mini-DHT on the loopback interface and sets this variable on each |
| 336 | node automatically, allowing the loopback DHT to serve as a WAN |
| 337 | replacement. Tests do not need to set this variable externally. |
| 338 | |
| 339 | Default: disabled (not set) |
| 340 | |
| 341 | # Tracing |
| 342 | |
| 343 | For tracing configuration, please check: https://github.com/ipfs/boxo/blob/main/docs/tracing.md |