Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

docs: subdomain gateways #61

Merged
merged 1 commit into from
Jan 9, 2020
Merged

docs: subdomain gateways #61

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
41 changes: 27 additions & 14 deletions docs/how-to/address-ipfs-on-web.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -30,9 +30,7 @@ HTTP gateways have worked well since 2015, but they come with a significant set

Tools and browser extensions should detect IPFS content paths and resolve them directly over IPFS protocol. They should use HTTP gateway only as a fallback when no native implementation is available in order to ensure a smooth, backward-compatible transition.

### Gateway types

#### Path gateway
### Path gateway

In the most basic scheme, a URL path used for content addressing is effectively a resource name without a canonical location. The HTTP server provides the location part, which makes it possible for browsers to interpret an IPFS content path as relative to the current server and just work without a need for any conversion:

Expand All @@ -41,9 +39,11 @@ https://<gateway-host>.tld/ipfs/<cid>/path/to/resource
https://<gateway-host>.tld/ipns/<ipnsid_or_dnslink>/path/to/resource
```

<aside class="alert alert-info">
In this scheme, all pages share a <a href="https://en.wikipedia.org/wiki/Same-origin_policy" target="_blank">single Origin&nbsp;<i class="fas fa-external-link-square-alt fa-sm"></i></a>, which means this type of gateway should be used when site isolation does not matter.
</aside>
::: danger
In this scheme, all pages share a <a href="https://en.wikipedia.org/wiki/Same-origin_policy" target="_blank">single Origin&nbsp;<i class="fas fa-external-link-square-alt fa-sm"></i></a>, which means this type of gateway should be used only when site isolation does not matter (static content without cookies, local storage or Web APIs that require user permission).

When in doubt, use subdomain gateway instead (see below).
:::

Examples:

Expand All @@ -53,7 +53,7 @@ https://ipfs.io/ipfs/QmT5NvUtoM5nWFfrQdVrFtvGfKFmG7AHE8P34isapyhCxX/wiki/Mars.ht
https://ipfs.io/ipns/tr.wikipedia-on-ipfs.org/wiki/Anasayfa.html
```

#### Subdomain gateway
### Subdomain gateway

When [origin-based security](https://en.wikipedia.org/wiki/Same-origin_policy) perimeter is needed, [CIDv1](https://github.com/ipld/cid#cidv1) in Base32 ([RFC4648](https://tools.ietf.org/html/rfc4648#section-6), no padding) should be used in the subdomain:

Expand All @@ -64,19 +64,32 @@ Example:
https://bafybeiemxf5abjwjbikoz4mc3a3dla6ual3jsgpdr4cjr3oz3evfyavhwq.ipfs.dweb.link/wiki/
https://bafybeiemxf5abjwjbikoz4mc3a3dla6ual3jsgpdr4cjr3oz3evfyavhwq.ipfs.cf-ipfs.com/wiki/Vincent_van_Gogh.html

<aside class="alert alert-info">
Right now, this type of gateway requires additional configuration (<a href="https://github.com/ipfs/infra/issues/81#issuecomment-461045160" target="_blank">example for Nginx&nbsp;<i class="fas fa-external-link-square-alt fa-sm"></i></a>); however, there is ongoing work to <a href="https://github.com/ipfs/go-ipfs/issues/5982" target="_blank">add native support in the IPFS daemon&nbsp;<i class="fas fa-external-link-square-alt fa-sm"></i></a>.
</aside>
::: tip

For now, this type of gateway requires additional reverse proxy configuration.
As a reference, Nginx config for subdomain gateway at <code>dweb.link</code> is:

```nginx
if ($http_host ~ ^(.+)\.(ipfs|ipns)\.dweb\.link$) {
set $ipfspath /$2/$1;
rewrite "^(.*)$" $ipfspath$1 last;
}
```

There is ongoing work to <a href="https://github.com/ipfs/go-ipfs/issues/6498" target="_blank">add native subdomain support to the IPFS daemon&nbsp;<i class="fas fa-external-link-square-alt fa-sm"></i></a> which will simplify setup and remove the need for path translation at reverse proxy.
:::

#### DNSLink gateway
### DNSLink gateway

The gateway provided by the IPFS daemon understands the `Host` header present in HTTP requests, and will check if [DNSLink](/guides/concepts/dnslink) exists for a specified [domain name](https://en.wikipedia.org/wiki/Fully_qualified_domain_name).
If DNSLink is present, the gateway will return content from a path resolved via DNS TXT record.
This type of gateway provides full [origin isolation](https://en.wikipedia.org/wiki/Same-origin_policy).

Example: [https://docs.ipfs.io](https://docs.ipfs.io) (this website)

::: tip
For a more complete DNSLink guide, including tutorials, usage examples and FAQs, check out [dnslink.io](https://dnslink.io).
:::

## Native URLs

Expand All @@ -99,9 +112,9 @@ Example:
ipfs://bafybeiemxf5abjwjbikoz4mc3a3dla6ual3jsgpdr4cjr3oz3evfyavhwq/wiki/Vincent_van_Gogh.html
```

<aside class="alert alert-info">
Support for case-insensitive IPNS roots is a <a href="https://github.com/ipfs/go-ipfs/issues/5287" target="_blank">work in progress&nbsp;<i class="fas fa-external-link-square-alt fa-sm"></i></a>.
</aside>
::: tip
Support for case-insensitive IPNS roots is a <a href="https://github.com/ipfs/go-ipfs/issues/5287" target="_blank">work in progress&nbsp;<i class="fas fa-external-link-square-alt fa-sm"></i></a>.
:::

## Further resources

Expand Down