diff --git a/docs/config.md b/docs/config.md index b4cb911f4..d8284de2f 100644 --- a/docs/config.md +++ b/docs/config.md @@ -1073,7 +1073,11 @@ Toggle and configure experimental features of Kubo. Experimental features are li Options for the HTTP gateway. -**NOTE:** support for `/api/v0` under the gateway path is now deprecated. It will be removed in future versions: . +> [!IMPORTANT] +> By default, Kubo's gateway is configured for local use at `127.0.0.1` and `localhost`. +> To run a public gateway, configure your domain names in [`Gateway.PublicGateways`](#gatewaypublicgateways). +> For production deployment considerations (reverse proxy, timeouts, rate limiting, CDN), +> see [Running in Production](gateway.md#running-in-production). ### `Gateway.NoFetch` @@ -1268,6 +1272,11 @@ Examples: - `*.example.com` will match requests to `http://foo.example.com/ipfs/*` or `http://{cid}.ipfs.bar.example.com/*`. - `foo-*.example.com` will match requests to `http://foo-bar.example.com/ipfs/*` or `http://{cid}.ipfs.foo-xyz.example.com/*`. +> [!IMPORTANT] +> **Reverse Proxy:** If running behind nginx or another reverse proxy, ensure +> `Host` and `X-Forwarded-*` headers are forwarded correctly. +> See [Reverse Proxy Caveats](gateway.md#reverse-proxy) in gateway documentation. + #### `Gateway.PublicGateways: Paths` An array of paths that should be exposed on the hostname. @@ -1334,6 +1343,9 @@ Default: `false` Type: `bool` +> [!IMPORTANT] +> See [Reverse Proxy Caveats](gateway.md#reverse-proxy) if running behind nginx or another reverse proxy. + #### `Gateway.PublicGateways: NoDNSLink` A boolean to configure whether DNSLink for hostname present in `Host` @@ -1344,6 +1356,9 @@ Default: `false` (DNSLink lookup enabled by default for every defined hostname) Type: `bool` +> [!IMPORTANT] +> See [Reverse Proxy Caveats](gateway.md#reverse-proxy) if running behind nginx or another reverse proxy. + #### `Gateway.PublicGateways: InlineDNSLink` An optional flag to explicitly configure whether subdomain gateway's redirects @@ -1411,6 +1426,9 @@ ipfs config --json Gateway.PublicGateways '{"localhost": null }' Below is a list of the most common gateway setups. +> [!IMPORTANT] +> See [Reverse Proxy Caveats](gateway.md#reverse-proxy) if running behind nginx or another reverse proxy. + - Public [subdomain gateway](https://docs.ipfs.tech/how-to/address-ipfs-on-web/#subdomain-gateway) at `http://{cid}.ipfs.dweb.link` (each content root gets its own Origin) ```console diff --git a/docs/gateway.md b/docs/gateway.md index 3a616a158..d51eab4cc 100644 --- a/docs/gateway.md +++ b/docs/gateway.md @@ -6,7 +6,7 @@ they were stored in a traditional web server. [More about Gateways](https://docs.ipfs.tech/concepts/ipfs-gateway/) and [addressing IPFS on the web](https://docs.ipfs.tech/how-to/address-ipfs-on-web/). -Kubo's Gateway implementation follows [ipfs/specs: Specification for HTTP Gateways](https://github.com/ipfs/specs/tree/main/http-gateways#readme). +Kubo's Gateway implementation follows [IPFS Gateway Specifications](https://specs.ipfs.tech/http-gateways/) and is tested with [Gateway Conformance Test Suite](https://github.com/ipfs/gateway-conformance). ### Local gateway @@ -14,14 +14,21 @@ By default, Kubo nodes run a [path gateway](https://docs.ipfs.tech/how-to/address-ipfs-on-web/#path-gateway) at `http://127.0.0.1:8080/` and a [subdomain gateway](https://docs.ipfs.tech/how-to/address-ipfs-on-web/#subdomain-gateway) at `http://localhost:8080/`. -The path one also implements [trustless gateway spec](https://specs.ipfs.tech/http-gateways/trustless-gateway/) -and supports [trustless responses](https://docs.ipfs.tech/reference/http/gateway/#trustless-verifiable-retrieval) as opt-in via `Accept` header. +> [!CAUTION] +> **For browsing websites, web apps, and dapps in a browser, use the subdomain +> gateway** (`localhost`). Each content root gets its own +> [web origin](https://developer.mozilla.org/en-US/docs/Web/Security/Same-origin_policy), +> isolating localStorage, cookies, and session data between sites. +> +> **For file retrieval, use the path gateway** (`127.0.0.1`). Path gateways are +> suited for downloading files or fetching [verifiable](https://docs.ipfs.tech/reference/http/gateway/#trustless-verifiable-retrieval) +> content, but lack origin isolation (all content shares the same origin). Additional listening addresses and gateway behaviors can be set in the [config](#configuration) file. ### Public gateways -Protocol Labs provides a public gateway at +IPFS Foundation [provides public gateways](https://docs.ipfs.tech/concepts/public-utilities/) at `https://ipfs.io` ([path](https://specs.ipfs.tech/http-gateways/path-gateway/)), `https://dweb.link` ([subdomain](https://docs.ipfs.tech/how-to/address-ipfs-on-web/#subdomain-gateway)), and `https://trustless-gateway.link` ([trustless](https://specs.ipfs.tech/http-gateways/trustless-gateway/) only). @@ -41,6 +48,80 @@ The gateway's log level can be changed with this command: > ipfs log level core/server debug ``` +## Running in Production + +When deploying Kubo's gateway in production, be aware of these important considerations: + + +> [!IMPORTANT] +> **Reverse Proxy:** When running Kubo behind a reverse proxy (such as nginx), +> the original `Host` header **must** be forwarded to Kubo for +> [`Gateway.PublicGateways`](config.md#gatewaypublicgateways) to work. +> Kubo uses the `Host` header to match configured hostnames and detect +> subdomain gateway patterns like `{cid}.ipfs.example.org` or DNSLink hostnames. +> +> If the `Host` header is not forwarded correctly, Kubo will not recognize +> the configured gateway hostnames and requests may be handled incorrectly. +> +> If `X-Forwarded-Proto` is not set, redirects over HTTPS will use wrong protocol +> and DNSLink names will not be inlined for subdomain gateways. +> +> Example: minimal nginx configuration for `example.org` +> +> ```nginx +> server { +> listen 80; +> listen [::]:80; +> +> # IMPORTANT: Include wildcard to match subdomain gateway requests. +> # The dot prefix matches both apex domain and all subdomains. +> server_name .example.org; +> +> location / { +> proxy_pass http://127.0.0.1:8080; +> +> # IMPORTANT: Forward the original Host header to Kubo. +> # Without this, PublicGateways configuration will not work. +> proxy_set_header Host $host; +> +> # IMPORTANT: X-Forwarded-Proto is required for correct behavior: +> # - Redirects will use https:// URLs when set to "https" +> # - DNSLink names will be inlined for subdomain gateways +> # (e.g., /ipns/en.wikipedia-on-ipfs.org → en-wikipedia--on--ipfs-org.ipns.example.org) +> proxy_set_header X-Forwarded-Proto $scheme; +> proxy_set_header X-Forwarded-Host $host; +> } +> } +> ``` +> +> Common mistakes to avoid: +> +> - **Missing wildcard in `server_name`:** Using only `server_name example.org;` +> will not match subdomain requests like `{cid}.ipfs.example.org`. Always +> include `*.example.org` or use the dot prefix `.example.org`. +> +> - **Wrong `Host` header value:** Using `proxy_set_header Host $proxy_host;` +> sends the backend's hostname (e.g., `127.0.0.1:8080`) instead of the +> original `Host` header. Always use `$host` or `$http_host`. +> +> - **Missing `Host` header entirely:** If `proxy_set_header Host` is not +> specified, nginx defaults to `$proxy_host`, which breaks gateway routing. + +> [!IMPORTANT] +> **Timeouts:** Configure [`Gateway.RetrievalTimeout`](config.md#gatewayretrievaltimeout) +> based on your expected content retrieval times. + +> [!IMPORTANT] +> **Rate Limiting:** Use [`Gateway.MaxConcurrentRequests`](config.md#gatewaymaxconcurrentrequests) +> to protect against traffic spikes. + +> [!IMPORTANT] +> **CDN/Cloudflare:** If using Cloudflare or other CDNs with +> [deserialized responses](config.md#gatewaydeserializedresponses) enabled, review +> [`Gateway.MaxRangeRequestFileSize`](config.md#gatewaymaxrangerequestfilesize) to avoid +> excess bandwidth billing from range request bugs. Cloudflare users may need additional +> protection via [Cloudflare Snippets](https://github.com/ipfs/boxo/issues/856#issuecomment-3523944976). + ## Directories For convenience, the gateway (mostly) acts like a normal web-server when serving @@ -53,7 +134,7 @@ a directory: 2. Dynamically build and serve a listing of the contents of the directory. †This redirect is skipped if the query string contains a -`go-get=1` parameter. See [PR#3964](https://github.com/ipfs/kubo/pull/3963) +`go-get=1` parameter. See [PR#3963](https://github.com/ipfs/kubo/pull/3963) for details ## Static Websites @@ -107,10 +188,12 @@ This is equivalent of `ipfs block get`. ### `application/vnd.ipld.car` -Returns a [CAR](https://ipld.io/specs/transport/car/) stream for specific DAG and selector. +Returns a [CAR](https://ipld.io/specs/transport/car/) stream for a DAG or a subset of it. -Right now only 'full DAG' implicit selector is implemented. -Support for user-provided IPLD selectors is tracked in https://github.com/ipfs/kubo/issues/8769. +The `dag-scope` parameter controls which blocks are included: `all` (default, entire DAG), +`entity` (logical unit like a file), or `block` (single block). For [UnixFS](https://specs.ipfs.tech/unixfs/) files, +`entity-bytes` enables byte range requests. See [IPIP-402](https://specs.ipfs.tech/ipips/ipip-0402/) +for details. This is a rough equivalent of `ipfs dag export`.