You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
An _IPFS gateway_ is a web-based service that gets contentfrom an IPFS network (private, or the public swarm backed by Amino DHT), and makes it available via HTTP, allowing IPFS-incompatible browsers, tools and software to benefit from [content-addressing](https://docs.ipfs.tech/concepts/content-addressing/). For example, some browsers or tools like [Curl](https://curl.haxx.se/) or [Wget](https://www.gnu.org/software/wget/) don't support IPFS natively and cannot access to IPFS content using canonical addressing like `ipfs://{CID}/{optional path to resource}`. While tools like [IPFS Companion](https://github.com/ipfs-shipyard/ipfs-companion) add browser support for native IPFS URLs, this is not always an option. As such, there are multiple gateway types and <VueCustomTooltiplabel="A way to address data by its hash rather than its location (IPs)."underlinedmultiline>gateway providers</VueCustomTooltip> available so that applications of all kinds can interface with IPFS using HTTP.
12
+
An _IPFS gateway_ is a standardized HTTP API for getting content-addressed data from IPFS nodes and CID providers (private, or the public IPFS Mainnet). It allows using HTTP semantics for interaction with IPFS. For example, some browsers or tools like [Curl](https://curl.haxx.se/) or [Wget](https://www.gnu.org/software/wget/) don't support IPFS natively and cannot access to IPFS content using canonical addressing like `ipfs://{CID}/{optional path to resource}`. While tools like [IPFS Companion](https://github.com/ipfs-shipyard/ipfs-companion) add browser support for native IPFS URLs, this is not always an option. As such, IPFS gateways enable a broad range of applications to interface with IPFS using HTTP.
This section uses the _default_ gateway request lifecycle of [IPFS Kubo](https://github.com/ipfs/kubo) to introduce the basic concepts in the lifecycle. However, some gateways only serve content that they have and/or want to provide. For example, a Kubo gateway with `NoFetch` enabled will not attempt to retrieve content from the network.
27
-
:::
28
-
29
-
When a client request for a CID reaches an IPFS gateway, the gateway first checks whether the CID is cached locally. At this point, one of the following occurs:
30
+
-[Learning more](#learning-more)
30
31
31
-
-**If the CID is cached locally**, the gateway responds with the content referred to by the CID, and the lifecycle is complete.
32
-
33
-
-**If the CID is not in the local cache**, the gateway will attempt to retrieve it from the network.
34
-
35
-
The CID retrieval process is composed of two parts, content discovery / routing and content retrieval:
32
+
## Gateway providers
36
33
37
-
1. In the **content discovery / routing** step, the gateway will determine <VueCustomTooltiplabel="An IPFS network peer that can provide data specified by a particular CID upon request."underlinedmultiline>provider</VueCustomTooltip> location; that is, _where_ the data specified by the CID can be found:
34
+
Regardless of who deploys a gateway and where, any IPFS gateway resolves access to any requested IPFS [content identifier](content-addressing.md).
38
35
39
-
- Asking peers that it is directly connected to if they have the data specified by the CID.
40
-
- Query the DHT for the IDs and network addresses of peers that have the data specified by the CID.
36
+
### Your local gateway
41
37
42
-
2. Next, the gateway performs **content retrieval**, which can be broken into the following steps:
38
+
Your machine may host a gateway as a local service; e.g., at `localhost:8080`. You have a local gateway service if you installed [IPFS Desktop](https://github.com/ipfs-shipyard/ipfs-desktop#ipfs-desktop) or another form of IPFS node.
43
39
44
-
1. The gateway connects to the provider.
45
-
1. The gateway fetches the CIDs content.
46
-
1. The gateway streams the content to the client.
40
+
### Public gateways
47
41
48
-
:::callout
49
-
- Learn more about content discovery, routing, retrieval and the subsystems involved in each part of the process in [How IPFS works](./how-ipfs-works.md).
50
-
- Dive into the technical specifications for gateways in the [IPFS HTTP Gateways specification](https://specs.ipfs.tech/http-gateways/) page.
51
-
:::
42
+
Public ([recursive](#recursive-vs-non-recursive-gateways)) gateways are provided by the IPFS various other organizations, including the [IPFS Foundation](./public-utilities.md#public-ipfs-gateways) as a public utility.
52
43
53
-
## Gateway providers
54
-
55
-
Regardless of who deploys a gateway and where, any IPFS gateway resolves access to any requested IPFS [content identifier](content-addressing.md). Therefore, for best performance, when you need the service of a gateway, you should use the one closest to you.
44
+
For a list of public gateways, see the [IPFS Gateways Checker](https://ipfs.fyi/gateways).
56
45
57
-
### Your local gateway
46
+
##Gateway types
58
47
59
-
Your machine may host a gateway as a local service; e.g., at `localhost:8080`. You have a local gateway service if you installed [IPFS Desktop](https://github.com/ipfs-shipyard/ipfs-desktop#ipfs-desktop) or another form of IPFS node.
48
+
There are multiple gateway types, each with specific use case, security, performance, and functional implications.
60
49
61
-
### Private gateways
50
+
-[Recursive vs. non-recursive gateways](#recursive-vs-non-recursive-gateways)
51
+
-[Trusted vs. trustless gateways](#trusted-vs-trustless-gateways)
_Private gateways_ are configured to limit access to requests from specific domains or parts of the public internet.
55
+
### Recursive vs. non-recursive gateways
64
56
65
-
They are frequently, but not exclusively, used behind firewalls. Running [IPFS Desktop](https://github.com/ipfs-shipyard/ipfs-desktop#ipfs-desktop) or another form of IPFS node triggers connection attempts to other IPFS peers. Private network administrators may treat such connection attempts as potential security vulnerabilities. Private IPFS gateway servers located inside the private network and running a trusted code base provide an alternative architecture for read/write access to externally-hosted IPFS content.
57
+
Recursive gateways are gateways that will attempt to retrieve content from other peers on the network if they do not have it locally.
66
58
67
-
### Public gateways
59
+
Non-recursive gateways are gateways that only serve content that they have themselves. For example, [Kubo](https://github.com/ipfs/kubo) can be configured to act as a non-recursive gateway by setting the [`NoFetch`](https://github.com/ipfs/kubo/blob/master/docs/config.md#gatewaynofetch) option.
68
60
69
-
For more information about public gateways, see the [Public IPFS Gateways](./public-utilities.md#public-ipfs-gateways)
61
+
In general, recursive gateways are more powerful for end-users because they abstract away all details of the peer-to-peer network. However, they are much more resource-intensive for operators and prone to abuse.
70
62
71
-
## Gateway types
63
+
Non-recursive gateways are becoming a popular way to provide IPFS content to the network (as an alternative or in addition to Bitswap). Non-recursive provider records can only be announced to the [IPNI](../concepts/ipni/), but not the [DHT](../concepts/dht.md).
72
64
73
-
There are multiple gateway types, each with specific use case, security, performance, and functional implications.
See [Trusted vs. Trustless Gateways](../reference/http/gateway/#trusted-vs-trustless) for more information.
79
68
80
69
### Read-only gateways
81
70
82
71
_Read-only gateways_ are the simplest kind of gateway. This gateway type provides a way to fetch IPFS content using the HTTP GET method.
83
72
84
-
###Authenticated gateways
73
+
## Authenticated gateways
85
74
86
75
If a gateway provider wants to limit access to requests with authentication, they may need to configure a reverse proxy, develop an IPFS plugin, or set a cache-layer above IPFS.
87
76
88
77
Configuring a reverse proxy is the most popular way for providers handling authentication. Reverse proxy can also keep the original IPFS API calls which makes gateway adaptable to all IPFS SDK and toolkits.
89
78
90
79
91
80
92
-
Providers can design their own centralized authentication service like [Infura IPFS Auth](https://docs.infura.io/networks/ipfs/how-to/authenticate-requests), or a decentralized authentication service like [IPFS W3Auth](https://wiki.crust.network/docs/en/buildIPFSWeb3AuthGW)).
81
+
## Gateway request lifecycle
82
+
83
+
:::callout
84
+
This section uses the _default_ recursive gateway request lifecycle of [IPFS Kubo](https://github.com/ipfs/kubo) to introduce the basic concepts in the lifecycle. However, non-recursive gateways only serve content that they have and/or want to provide. For example, a Kubo gateway with `NoFetch` enabled will **not** attempt to retrieve content from the network.
85
+
:::
86
+
87
+
When a client request for a CID reaches an IPFS gateway, the gateway first checks whether the CID is cached locally. At this point, one of the following occurs:
88
+
89
+
-**If the CID is cached locally**, the gateway responds with the content referred to by the CID, and the lifecycle is complete.
90
+
91
+
-**If the CID is not in the local cache**, the gateway will attempt to retrieve it from the network.
92
+
93
+
The CID retrieval process is composed of two parts, content discovery / routing and content retrieval:
94
+
95
+
1. In the **content discovery / routing** step, the gateway will determine <VueCustomTooltiplabel="An IPFS network peer that can provide data specified by a particular CID upon request."underlinedmultiline>provider</VueCustomTooltip> location; that is, _where_ the data specified by the CID can be found:
96
+
97
+
- Asking peers that it is directly connected to if they have the data specified by the CID.
98
+
- Query the DHT for the IDs and network addresses of peers that have the data specified by the CID.
99
+
100
+
2. Next, the gateway performs **content retrieval**, which can be broken into the following steps:
101
+
102
+
1. The gateway connects to the provider.
103
+
1. The gateway fetches the CIDs content.
104
+
1. The gateway streams the content to the client.
105
+
106
+
:::callout
107
+
- Learn more about content discovery, routing, retrieval and the subsystems involved in each part of the process in [How IPFS works](./how-ipfs-works.md).
108
+
- Dive into the technical specifications for gateways in the [IPFS HTTP Gateways specification](https://specs.ipfs.tech/http-gateways/) page.
109
+
:::
93
110
94
-
###Resolution style
111
+
## Resolution styles
95
112
96
-
Three resolution styles exist:
113
+
Gateways typically support three resolution styles:
97
114
98
115
-[Path](#path)
99
116
-[Subdomain](#subdomain)
100
117
-[DNSLink](#dnslink)
101
118
102
-
####Path
119
+
### Path
103
120
104
121
The examples discussed above employed path resolution:
105
122
@@ -115,17 +132,17 @@ This type of gateway does not provide origin isolation and should not be used fo
115
132
Learn more at [Address IPFS on the web: Path Gateway](../how-to/address-ipfs-on-web.md#path-gateway) and [Path Gateway Specification](https://specs.ipfs.tech/http-gateways/path-gateway/).
116
133
:::
117
134
118
-
####Subdomain
135
+
### Subdomain
119
136
120
-
Subdomain resolution style maintains compliance with the [single-origin policy](https://en.wikipedia.org/wiki/Same-origin_policy). The canonical form of access, `https://{CID}.ipfs.{gatewayURL}/{optional path to resource}`, causes the browser to interpret each returned file as being from a different origin.
137
+
Subdomain resolution style ensures compliance with the [single-origin policy](https://en.wikipedia.org/wiki/Same-origin_policy). The canonical form of access, `https://{CID}.ipfs.{gatewayURL}/{optional path to resource}`, ensures origin isolation per CID.
121
138
122
139
::: callout
123
-
This type of gateway does provide origin isolation and should be used for hosting web apps.
140
+
Subdomain gateways provide origin isolation and should be used for hosting web apps.
124
141
125
142
Learn more at [Address IPFS on the web: Subdomain Gateway](../how-to/address-ipfs-on-web.md#subdomain-gateway) and [Subdomain Gateway Specification](https://specs.ipfs.tech/http-gateways/subdomain-gateway/).
126
143
:::
127
144
128
-
#### DNSlink
145
+
###DNSLink
129
146
130
147
Whenever the content of data within IPFS changes, IPFS creates a new CID based on the content of that data. Many applications require access to the latest version of a file or website but will not know the exact CID for that latest version. The [InterPlanetary Name Service (IPNS)](ipns.md) allows a version-independent IPNS identifier to resolve into the current version's IPFS CID.
131
148
@@ -141,7 +158,7 @@ DNSLink resolution occurs when the gateway recognizes an IPNS identifier contain
2. The gateway searches the DNS TXT records of the requested domain `{example.com}` for a string of the form `dnslink=/ipfs/{CID}` or `_dnslink=/ipfs/{CID}`. If found, the gateway uses the specified CID to serve up `ipfs://{CID}/{optional path}`. As with path resolution, this form of DNSLink resolution violates the single-origin policy. The domain operator may ensure single-origin policy compliance — and the delivery of the current version of content — by adding an `Alias` record in the DNS that refers to a suitable IPFS gateway; e.g., `gateway.ipfs.io`.
161
+
2. The gateway searches the DNS TXT records of the requested domain `{_dnslink.example.com}` for a string of the form `dnslink=/ipfs/{CID}`. If found, the gateway uses the specified CID to serve up `ipfs://{CID}/{optional path}`. As with path resolution, this form of DNSLink resolution violates the single-origin policy. The domain operator may ensure single-origin policy compliance — and the delivery of the current version of content — by adding an `Alias` record in the DNS that refers to a suitable IPFS gateway; e.g., `gateway.ipfs.io`.
145
162
3. The `Alias` record redirects any access to that `example.com` to the specified gateway. Hence the browser's request to `https://{example.com}/{optional path to resource}` redirects to the gateway specified in the `Alias`.
146
163
4. The gateway employs DNSLink resolution to return the current content version from IPFS.
147
164
5. The browser does not perceive the gateway as the origin of the content and therefore enforces the single-origin policy to protect `example.com`.
@@ -150,18 +167,18 @@ DNSLink resolution occurs when the gateway recognizes an IPNS identifier contain
150
167
Learn more at [Address IPFS on the web: DNSLink Gateway](../how-to/address-ipfs-on-web.md#dnslink-gateway) and [DNSLink Gateway Specification](https://specs.ipfs.tech/http-gateways/dnslink-gateway/).
151
168
:::
152
169
153
-
###Gateway services
170
+
## Gateway URL formats
154
171
155
-
Currently HTTP gateways may access both IPFS and IPNS services:
172
+
Currently HTTP gateways typically expose both immutable IPFS and mutable IPNS (either IPNS names or DNSLink) resources using the following URL formats:
| IPFS | path |`https://{gateway URL}/ipfs/{CID}/{optional path to resource}`|
160
-
| IPFS | subdomain |`https://{CID}.ipfs.{gatewayURL}/{optional path to resource}`|
161
-
| IPFS | DNSLink |`https://{example.com}/{optional path to resource}`**preferred**, or <br>`https://{gateway URL}/ipns/{example.com}/{optional path to resource}`|
162
-
| IPNS | path |`https://{gateway URL}/ipns/{IPNS identifier}/{optional path to resource}`|
163
-
| IPNS | subdomain |`https://{IPNS identifier}.ipns.{gatewayURL}/{optional path to resource}`|
164
-
| IPNS | DNSLink | Useful when IPNS identifier is a domain: <br>`https://{example.com}/{optional path to resource}`**preferred**, or <br>`https://{gateway URL}/ipns/{example.com}/{optional path to resource}`|
174
+
| Service |Resolution style| Canonical form of access |
| IPFS | path |`https://{gateway URL}/ipfs/{CID}/{optional path to resource}`|
177
+
| IPFS | subdomain |`https://{CID}.ipfs.{gatewayURL}/{optional path to resource}`|
178
+
| IPFS | DNSLink |`https://{example.com}/{optional path to resource}`**preferred**, or <br>`https://{gateway URL}/ipns/{example.com}/{optional path to resource}`|
179
+
| IPNS | path |`https://{gateway URL}/ipns/{IPNS identifier}/{optional path to resource}`|
180
+
| IPNS | subdomain |`https://{IPNS identifier}.ipns.{gatewayURL}/{optional path to resource}`|
181
+
| IPNS | DNSLink | Useful when IPNS identifier is a domain: <br>`https://{example.com}/{optional path to resource}`**preferred**, or <br>`https://{gateway URL}/ipns/{example.com}/{optional path to resource}`|
0 commit comments