This IPIP creates conventions for how applications can identify an available IPFS gateway, and how IPFS gateway implementations can signal their own endpoint.
This convention has been implemented and in use since 2022 (Kubo 0.15, ffmpeg), with curl support added in curl 8.4.0 (2023).
Applications wanting to leverage IPFS Gateways are, without a common convention, left to invent their own ways of finding a gateway, including naive approaches such as localhost port scanning.
This IPIP introduces specification that defines how an application wanting to implement IPFS support can find a local or user-preferred gateways.
We introduce two ways of hinting user-preferred gateway URL to cover the majority of runtimes and use cases:
IPFS_GATEWAY environment variablegateway file and filesystem paths to look for itSee: [gateway-detection] for details.
End users can define their preferred gateway once, and benefit from opportunistic support in applications they use.
Application developers save time as they only need to implement support for vendor-agnostic convention to be able to read user preferred gateway.
Kubo (0.15.0 and later)
creates a hint file in $IPFS_PATH/gateway (default being $HOME/.ipfs/gateway, see kubo#8847).
The file contains a single line being the local HTTP gateway URL. For example: http://localhost:8080.
Every time ipfs daemon starts with the gateway enabled, it updates the content of $IPFS_PATH/gateway or creates the file if it doesn't exist.
ipfs-chromium uses IPFS_GATEWAY environment variable
(ipfs-chromium#29).
It can be a single URL, or a whitespace-separated URLs to be used as the initial gateway pool.
Ref. https://blog.ipfs.tech/2023-05-multigateway-chromium-client/
FFMPEG's libavformat tries the -gateway option first, then the IPFS_GATEWAY
environment variable, then the gateway file under $IPFS_PATH or $HOME/.ipfs/
(ffmpeg.git/commit/f889837).
Note that ffmpeg joins $IPFS_PATH and gateway without a path separator, so
file detection via IPFS_PATH works only when the value ends with /.
The initial implementation fell back to a hard-coded public gateway; this was removed in ffmpeg.git/commit/412922c for the reason the Security section of [gateway-detection] codifies.
Ref. https://ffmpeg.org/ffmpeg-protocols.html#ipfs, https://blog.ipfs.tech/2022-08-01-ipfs-and-ffmpeg/
Curl (8.4.0 and later, curl#8805)
will try the IPFS_GATEWAY environment variable first, and then look for
$IPFS_PATH/gateway or $HOME/.ipfs/gateway, if present. The --ipfs-gateway
flag takes precedence over both.
It expects a single URL. Since curl 8.5.0 only the first line of the gateway
file is read; 8.4.0 concatenated all lines.
Python's ipfsspec (0.5.0 and later,
ipfsspec#29) enables ipfs://
support in the fsspec ecosystem. It tries the IPFS_GATEWAY environment
variable first (a single URL), then reads the first line of a gateway file,
checking $IPFS_PATH/gateway, $HOME/.ipfs/gateway,
$XDG_CONFIG_HOME/ipfs/gateway, /etc/ipfs/gateway, and OS-specific paths,
in that order (get_gateway in async_ipfs.py).
When no gateway is found, it raises an error suggesting to run a local node
instead of falling back to a public gateway.
See "Security" section of [gateway-detection].
Detection via browser APIs (e.g., localStorage.getItem('IPFS_GATEWAY')) was
considered but is explicitly out of scope. Any JavaScript running on a page
could overwrite such values and hijack gateway requests. Browser-based detection
requires a separate IPIP with proper security review.
This specification does not mandate health checking of detected gateways. Implementations MAY verify that a gateway is responsive before using it, but the specific approach is left to implementers.
If a daemon crashes without removing the gateway file, it may contain a stale
URL. This specification does not mandate specific handling. Implementations MAY
implement timeout-based health checks or other recovery mechanisms.
Copyright and related rights waived via CC0.
We gratefully acknowledge the following individuals for their valuable contributions, ranging from minor suggestions to major insights, which have shaped and improved this specification.
