Gateway

An IPFS Gateway acts as a bridge between traditional web browsers and IPFS. Through the gateway, users can browse files and websites stored in IPFS as if they were stored in a traditional web server.

More about Gateways and addressing IPFS on the web.

Kubo's Gateway implementation follows IPFS Gateway Specifications and is tested with Gateway Conformance Test Suite.

Table of contents

• Local gateway
• Public gateways
• Gateway recipes
  • Serve only your own content (Gateway.NoFetch=true)
  • Serve any content from the network (Gateway.NoFetch=false)
  • URL-style recipes
    • Subdomain gateway
    • Path gateway
    • DNSLink gateway
    • Hardened DNSLink gateway
• Configuration
• Running in Production
• Directories
• Static Websites
• Filenames
• Downloads
• Response Format
• Content-Types

Local gateway

By default, Kubo nodes run a path gateway at http://127.0.0.1:8080/ and a subdomain gateway at http://localhost:8080/.

Additional listening addresses and gateway behaviors can be set in the config file.

Public gateways

For public gateways available as a public good, see the public utilities page; for a broader community-maintained list, see the public gateway checker.

Treat public gateways as a convenience for casual use; they are provided on a best-effort basis. For anything you depend on, run your own gateway (recipes below) or retrieve content over IPFS directly instead of through someone else's gateway. The guide Replace public gateways with self-hosted IPFS covers the options.

Gateway recipes

Before you pick a URL style (subdomain, path, or DNSLink, in the URL-style recipes below), decide the bigger question: when a visitor asks for content this node does not have, should the gateway go and fetch it from the network, or just answer "not found"?

Serve only your own content (Gateway.NoFetch=true)

The node only shares content it already has. It never downloads missing content from other peers, so anything this node does not have returns 404 Not Found.

This is the safest way to put your own content (a website, a dataset, some files) on a public gateway, and the recommended setup for most people.

$ ipfs config --json Gateway.NoFetch true

• The gateway only serves content already stored on this node: anything you added with ipfs add, pinned, or put in MFS. Anything else returns 404 Not Found right away, without touching the network.
• Because the node never fetches anything for a visitor, no stranger can make it download content you did not choose, so there is little room for abuse.
• Pin the content you serve (ipfs pin add) so garbage collection does not remove it. Unpinned content can be deleted when garbage collection runs, after which it stops resolving and returns 404.
• Pick how URLs map to your content with one of the URL-style recipes below.
• A gateway serves content over HTTP, so it does not need to announce that content to the IPFS network (so other peers can discover it here) for the gateway to work. If the content is already announced by another node (for example, you also pinned it elsewhere), or you want this node to spend its resources on serving instead of announcing, turn announcements off with Provide.Enabled=false. That drops the ongoing announcing work.
• NoFetch does not stop your node from helping other peers find their content. If you want it to act only as a client and not help route for others, set Routing.Type=autoclient.
• To limit this to a single DNSLink website, see the hardened DNSLink recipe below.

Serve any content from the network (Gateway.NoFetch=false)

This is the default, and how a large shared public gateway works. The gateway looks up and downloads any content a visitor asks for, fetching it from the network. Only run it this way if you mean to offer that kind of public service, and set it up carefully first.

• Block and take down abuse. Sooner or later, someone will ask an open gateway to serve illegal or abusive content. Set up content blocking so you can respond to takedown requests: Kubo blocks content listed in IPIP-383 denylists and returns 410 Gone for it. Blocking stops your node from serving the content, but not from helping other peers find it on the network; to stop that too, set Routing.Type=autoclient.
• Do not become free web hosting. Set Gateway.DeserializedResponses=false so the gateway returns only verifiable data, not ready-to-view web pages. People can no longer use it to host random websites, while apps that verify data themselves (like @helia/verified-fetch) keep working.
• Protect your bandwidth. Review Gateway.MaxRangeRequestFileSize, Gateway.MaxConcurrentRequests, and the Running in Production notes on timeouts, reverse proxy, and CDN behavior.
• Speed. Consider Routing.AcceleratedDHTClient=true for faster lookups. Decide whether this gateway should also announce the content it fetches so others can find it: if yes, turn on Provide.DHT.SweepEnabled=true (and raise Provide.DHT.MaxWorkers if announcements are slow); if no, set Provide.Enabled=false.
• Pick how URLs map to content with one of the URL-style recipes below.

URL-style recipes

These decide how a request URL maps to content. They work the same whether or not Gateway.NoFetch is set.

Subdomain gateway

A subdomain gateway serves each content root from its own subdomain (http://{cid}.ipfs.subdomain-gw.example.com), so every root gets its own Origin.

$ ipfs config --json Gateway.PublicGateways '{
    "subdomain-gw.example.com": {
      "UseSubdomains": true,
      "Paths": ["/ipfs", "/ipns"]
    }
  }'

• Backward-compatible: content paths redirect to subdomains:

  http://subdomain-gw.example.com/ipfs/{cid} → http://{cid}.ipfs.subdomain-gw.example.com

• X-Forwarded-Proto: if you run Kubo behind a reverse proxy that provides TLS, make it add an X-Forwarded-Proto: https header so users are redirected to https://, not http://. It also inlines DNSLink names into a single DNS label, so they work with a wildcard TLS cert (details). The NGINX directive is proxy_set_header X-Forwarded-Proto "https";:

  http://subdomain-gw.example.com/ipfs/{cid} → https://{cid}.ipfs.subdomain-gw.example.com

  http://subdomain-gw.example.com/ipns/your-dnslink.example.org → https://your--dnslink-example-org.ipns.subdomain-gw.example.com

• X-Forwarded-Host: override the gateway host from the request with X-Forwarded-Host: example.net:

  http://subdomain-gw.example.com/ipfs/{cid} → http://{cid}.ipfs.example.net

Path gateway

A path gateway serves content under a path (http://path-gw.example.com/ipfs/{cid}), with no Origin separation between content roots.

$ ipfs config --json Gateway.PublicGateways '{
    "path-gw.example.com": {
      "UseSubdomains": false,
      "Paths": ["/ipfs", "/ipns"]
    }
  }'

DNSLink gateway

A DNSLink gateway resolves the DNSLink name in the Host header of each request. It is on by default (NoDNSLink: false):

ipfs config --json Gateway.NoDNSLink false

Hardened DNSLink gateway

To serve a single DNSLink site and nothing else, combine NoFetch and NoDNSLink. Disable fetching remote data (NoFetch: true) and DNSLink at unknown hostnames (NoDNSLink: true), then enable DNSLink for one hostname whose data is already on the node, without exposing any content-addressing Paths:

$ ipfs config --json Gateway.NoFetch true
$ ipfs config --json Gateway.NoDNSLink true
$ ipfs config --json Gateway.PublicGateways '{
    "dnslink-site.example.com": {
      "NoDNSLink": false,
      "Paths": []
    }
  }'

Configuration

The Gateway.* configuration options are described in the config documentation. See Gateway recipes above for common setups.

Debug

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:

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;
    }
}

Directories

For convenience, the gateway (mostly) acts like a normal web-server when serving a directory:

1. If the path does not end in a /, append a / and redirect. This applies to any directory request and helps avoid serving duplicate content from different paths.^†
2. If the directory contains an index.html file, serve it.
3. Otherwise, dynamically build and serve a listing of the directory contents.

_{^†This redirect is skipped if the query string contains a go-get=1 parameter. See PR#3963 for details}

Static Websites

You can use an IPFS gateway to serve static websites at a custom domain using DNSLink. See Example: IPFS Gateway for instructions.

Filenames

When downloading files, browsers will usually guess a file's filename by looking at the last component of the path. Unfortunately, when linking directly to a file (with no containing directory), the final component is just a CID (bafy.. or Qm...). This isn't exactly user-friendly.

To work around this issue, you can add a filename=some_filename parameter to your query string to explicitly specify the filename. For example:

http://127.0.0.1:8080/ipfs/QmfM2r8seH2GiRaC4esTjeraXEachRt8ZsSeGaWTPLyMoG?filename=hello_world.txt

When you try to save the page above, your browser will use the passed filename instead of a CID.

Downloads

It is possible to skip browser rendering of supported filetypes (plain text, images, audio, video, PDF) and trigger immediate "save as" dialog by appending &download=true:

http://127.0.0.1:8080/ipfs/QmfM2r8seH2GiRaC4esTjeraXEachRt8ZsSeGaWTPLyMoG?filename=hello_world.txt&download=true

Response Format

An explicit response format can be requested using ?format=raw|car|.. URL parameter, or by sending Accept: application/vnd.ipld.{format} HTTP header with one of supported content types.

Content-Types

Majority of resources can be retrieved trustlessly by requesting specific content type via Accept header or ?format=raw|car|ipns-record URL query parameter.

See trustless gateway specification and verifiable retrieval documentation for more details.

application/vnd.ipld.raw

Returns a byte array for a single raw block.

Sending such requests for /ipfs/{cid} allows for efficient fetch of blocks with data encoded in custom format, without the need for deserialization and traversal on the gateway.

This is the equivalent of ipfs block get.

application/vnd.ipld.car

Returns a CAR stream for a DAG or a subset of it.

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 files, entity-bytes enables byte range requests. See IPIP-402 for details.

This is a rough equivalent of ipfs dag export.

application/vnd.ipfs.ipns-record

Only works on /ipns/{ipns-name} content paths that use cryptographically signed IPNS Records.

Returns IPNS Record in Protobuf Serialization Format which can be verified on end client, without trusting gateway.