docs.ipfs.tech Open in urlscan Pro
2400:52e0:1e00::1080:1  Public Scan

Form analysis
0 forms found in the DOM

Text Content

IPFS Docs
Get Started
Concepts
Guides
Reference
Project
Case Studies Case Studies
 * Arbol
 * Audius
 * Fleek
 * LikeCoin
 * Morpheus.Network
 * Snapshot


Get Started
Concepts
Guides
Reference
Project
Case Studies Case Studies
 * Arbol
 * Audius
 * Fleek
 * LikeCoin
 * Morpheus.Network
 * Snapshot

 * IPFS Desktop Tutorial

 * IPFS Kubo Tutorials

 * Manage files

 * Work with peers

 * Websites on IPFS

 * IPFS in the browser
   
    * Address IPFS on the Web
      * Dweb addressing in brief
      * HTTP gateways
      * Path gateway
      * Subdomain gateway
      * DNSLink gateway
      * Native URLs
      * Further resources
    * Create a simple chat app
    * Browser tools and frameworks

 * IPNS

 * IPFS Gateway

 * IPFS Companion

 * IPFS & Blockchain Networks

 * Privacy and Encryption


# ADDRESS IPFS ON THE WEB

How to link to content on IPFS.

https://ipfs.io/ipfs/<CID>
# e.g
https://ipfs.io/ipfs/Qme7ss3ARVgxv6rXqVPiikMJ8u2NLgmgszg13pYrDKEoiu


Browsers that support IPFS can redirect these requests to your local IPFS node,
while those that don't can fetch the resource from the ipfs.io gateway.

You can swap out ipfs.io for your own http-to-ipfs gateway, but you are then
obliged to keep that gateway running forever. If your gateway goes down, users
with IPFS aware tools will still be able to fetch the content from the IPFS
network as long as any node still hosts it, but for those without, the link will
be broken. Don't do that.


# DWEB ADDRESSING IN BRIEF

 * In IPFS, addresses (for content) are path-like; they are components separated
   by slashes.
 * The first component is the protocol, which tells you how to interpret
   everything after it.
 * Content referenced by a hash might have named links. (For example, a Git
   commit has a link named parent, which is really just a pointer to the hash of
   another Git commit.) Everything after the CID in an IPFS address is those
   named links.
 * Since these addresses aren’t URLs, using them in a web browser requires
   reformatting them slightly:
   * Through an HTTP gateway, as http://<gateway host>/<IPFS address>
   * Through the gateway subdomain (more secure, harder to set up):
     http://<cid>.ipfs.<gateway host>/<path>, so the protocol and CID are
     subdomains.
   * Through custom URL protocols like ipfs://<CID>/<path>, ipns://<peer
     ID>/<path>, and dweb://<IPFS address>


# HTTP GATEWAYS

Gateways are provided strictly for convenience: in other words, they help tools
that speak HTTP but do not speak distributed protocols (such as IPFS) to
communicate. They are the first stage of the upgrade path for the web. More
information about IPFS Gateways.


# CENTRALIZATION

HTTP gateways have worked well since 2015, but they come with a significant set
of limitations related both to the centralized nature of HTTP and some of HTTP's
semantics. Location-based addressing of a gateway depends on both DNS and
HTTPS/TLS, which relies on trust in certificate authorities (opens new window)
(CAs) and public key infrastructure (opens new window) (PKI). In the long term,
these issues should be mitigated by the use of opportunistic protocol upgrade
schemes.


# PROTOCOL UPGRADE

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.

TIP

Use relative or absolute URLs that include content-addressed paths. This will
take advantage of content addressing today while ensuring backward compatibility
with the legacy web.

For example, a website can load static assets from content-addressed paths:

<link rel="stylesheet" href="https://example.com/ipfs/QmNrgEMcUygbKzZeZgYFosdd27VE9KnWbyUD73bKZJ3bGi?filename=style.css">


<link rel="stylesheet" href="/ipfs/QmNrgEMcUygbKzZeZgYFosdd27VE9KnWbyUD73bKZJ3bGi?filename=style.css">


User agents that support IPFS, such as a browser with ipfs-companion (opens new
window), may recognize the /ipfs/<CID> content path and load the related asset
over IPFS instead of HTTP. User agents without IPFS support still get the
correct data from the original HTTP server.


# 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. Given a gateway host address (such as ipfs.io) and a path to the
resource, (/path/to/resource), a CID (<cid>), IPNS ID (<ipnsid>) or DNSLink
(<dnslink>) can all be used.

 * Using a CID
 * Using IPNS
 * Using DNSLink


# USING A CID

Given a CID <cid>, a URL path can be constructed as follows:

https://<gateway-host>.tld/ipfs/<cid>/path/to/resource


Example:

https://ipfs.io/ipfs/bafybeiemxf5abjwjbikoz4mc3a3dla6ual3jsgpdr4cjr3oz3evfyavhwq/wiki/Vincent_van_Gogh.html
https://ipfs.io/ipfs/QmT5NvUtoM5nWFfrQdVrFtvGfKFmG7AHE8P34isapyhCxX/wiki/Mars.html



# USING IPNS

Given an IPNS <ipnsid>, a URL path can be constructed as follows:

https://<gateway-host>.tld/ipns/<ipnsid>/path/to/resource


Example:

https://ipfs.io/ipns/k51qzi5uqu5dlvj2baxnqndepeb86cbk3ng7n3i46uzyxzyqj2xjonzllnv0v8



# USING DNSLINK

Given a DNSLink <dnslink>, a URL path can be constructed as follows:

https://<gateway-host>.tld/ipns/<dnslink>/path/to/resource


Example:

https://ipfs.io/ipns/tr.wikipedia-on-ipfs.org/wiki/Anasayfa.html


DANGER

In this scheme, all pages share a single origin (opens new window), 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.


# SUBDOMAIN GATEWAY

When origin-based security (opens new window) is needed, CIDv1 in
case-insensitive encoding such as Base32 or Base36 should be used in the
subdomain:

https://<cidv1b32>.ipfs.<gateway-host>.tld/path/to/resource


Example:

https://bafybeiemxf5abjwjbikoz4mc3a3dla6ual3jsgpdr4cjr3oz3evfyavhwq.ipfs.dweb.link/wiki/
https://bafybeiemxf5abjwjbikoz4mc3a3dla6ual3jsgpdr4cjr3oz3evfyavhwq.ipfs.cf-ipfs.com/wiki/Vincent_van_Gogh.html
https://bafybeiemxf5abjwjbikoz4mc3a3dla6ual3jsgpdr4cjr3oz3evfyavhwq.ipfs.localhost:8080/wiki/


# NATIVE SUPPORT IN KUBO 0.5+

Kubo (opens new window) provides native support for subdomain gateways on
hostnames defined in the Gateway.PublicGateways (opens new window) configuration
map.

Learn more about daemon configuration for hosting a public gateway:

 * Gateway.PublicGateways docs (opens new window) for defining gateway behavior
   on specified hostnames
 * Gateway recipes (opens new window) with ready to use one-liners for most
   common use cases

Known issues

 * Some browsers and other user agents force lowercase for the authority part of
   URLs, breaking case-sensitive CIDs before the HTTP gateway has a chance to
   read them
 * DNS label length is limited to 63 characters (RFC 1034 (opens new window))

Due to these limitations, the use of short, case-insensitive CIDv1 in a
subdomain context is advised. Base32 is the safe default; the less-popular
Base36 can be used for longer ED25519 libp2p keys.

See the next section to learn how to convert an existing CIDv0 to a DNS-safe
representation.

# CID CONVERSION FOR SUBDOMAINS

If you have content identified by an older CIDv0, there are easy ways to safely
represent it as CIDv1 for use in subdomains and other case-insensitive contexts.

# AUTOMATIC — LEVERAGE THE GATEWAY IN KUBO

TL;DR: Using a subdomain gateway as a drop-in replacement for a path one removes
the need for manual CID conversion.

Request for a content path sent to the gateway domain will return an HTTP 301
redirect to a correct subdomain version, taking care of any necessary encoding
conversion if needed:

https://<gateway-host>.tld/ipfs/<cid> -> https://<cidv1>.ipfs.<gateway-host>.tld/


To illustrate, opening the CIDv0 resource at
https://dweb.link/ipfs/QmT5NvUtoM5nWFfrQdVrFtvGfKFmG7AHE8P34isapyhCxX/wiki/Mars.html
(opens new window) returns a redirect to a CIDv1 representation at
https://bafybeicgmdpvw4duutrmdxl4a7gc52sxyuk7nz5gby77afwdteh3jc5bqa.ipfs.dweb.link/wiki/Mars.html
(opens new window).

The gateway takes care of converting the CID to case-insensitive encoding. The
multihash in CIDv1 is the same as in the original CIDv0.

# MANUAL — USE CID.IPFS.IO OR THE COMMAND LINE

One can also do the conversion manually.

To convert a CID to Base32 (RFC4648 (opens new window), no padding) use
cid.ipfs.io (opens new window) or the command line:

$ ipfs cid base32 QmbWqxBEKC3P8tqsKc98xmWNzrzDtRLMiMPL8wBuTGsMnR
bafybeigdyrzt5sfp7udm7hu76uh7y26nf3efuylqabf3oclgtqy55fbzdi


PeerIDs can be represented as CID with libp2p-key multicodec (opens new window).
Base36 is suggested as a safer default for longer keys:

$ ipfs key list -l --ipns-base base36
k51qzi5uqu5dh9ihj4p2v5sl3hxvv27ryx2w0xrsv6jmmqi91t9xp8p9kaipc2 self

$ ipfs cid format -v 1 -b base36 --codec libp2p-key QmNnooDu7bfjPFoTZYxMNLWUQJyrVwtbZg5gBMjTezGAJN
k2k4r8jl0yz8qjgqbmc2cdu5hkqek5rj6flgnlkyywynci20j0iuyfuj



# DNSLINK GATEWAY

The gateway provided by the IPFS daemon understands the Host header present in
HTTP requests and will check if DNSLink exists for a specified domain name
(opens new window). 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 (opens new window).

Example: https://docs.ipfs.tech (opens new window) (this website)

TIP

For a complete DNSLink guide, including tutorials, usage examples, and FAQs,
check out dnslink.io (opens new window).


# NATIVE URLS

ipfs://{cid}/path/to/subresource/cat.jpg


The native address format is the same as a subdomain gateway (opens new window)
HTTP URL, but with:

 * protocol scheme replaced by ipfs or ipns namespace
 * location-based authority component (gateway host+port) replaced with
   content-addressed one in the form of a unique content identifier (CID)

For example:

ipfs://{cidv1}
ipfs://{cidv1}/path/to/resource
ipfs://{cidv1}/path/to/resource?query=foo#fragment

ipns://{cidv1-libp2p-key}
ipns://{cidv1-libp2p-key}/path/to/resource
ipns://{dnslink-name}/path/to/resource?query=foo#fragment


TIP

Our main goal here is to reuse existing standards that maximize interoperability
with existing user-agents like browsers and CLI tools. If something is not
clear, HTTP URL rules apply.

The first element after the double slash is an opaque identifier representing
the content root. It is interpreted as an authority component used for origin
calculation, which provides necessary isolation between security contexts of
different content trees.

Example:

ipfs://bafybeiemxf5abjwjbikoz4mc3a3dla6ual3jsgpdr4cjr3oz3evfyavhwq/wiki/Vincent_van_Gogh.html


Avoid case-sensitive CID in ipfs://

Some user agents will force-lowercase the CID component of URL-like address. To
ensure interop with existing libraries and software, use case-insensitive CID
encoding. Use of CIDv1 in Base32 or Base36 is advised.


# TURNING NATIVE ADDRESS TO A CANONICAL CONTENT PATH

Every "URL" address can be turned back into a content path with ease:

> ipfs://{immutable-root}/path/to/resourceA →
> /ipfs/{immutable-root}/path/to/resourceA
> ipns://{mutable-root}/path/to/resourceB →
> /ipns/{mutable-root}/path/to/resourceB


# FURTHER RESOURCES


# TECHNICAL SPECIFICATION FOR IMPLEMENTERS

The best and most up-to-date source of truth about IPFS addressing can be found
in the IPFS in-web-browsers repo (opens new window).


# BACKGROUND ON ADDRESS SCHEME DISCUSSIONS

Discussions around IPFS addressing have been going on since @jbenet (opens new
window) published the IPFS whitepaper (opens new window), with a number of other
approaches being proposed. This long-standing design discussion includes many
lengthy GitHub issue threads, but a good summary can be found in this PR (opens
new window).


# IPFS COMPANION

IPFS Companion (opens new window) is a browser extension that simplifies access
to IPFS resources.

It provides support for native URLs and will automatically redirect IPFS gateway
requests to your local daemon so that you are not relying on or trusting remote
gateways.


# SHARED D-WEB NAMESPACE

This concept isn't yet built but may be explored and experimented with in the
future. The distributed web community is exploring the idea of a shared dweb
namespace to remove the complexity of addressing IPFS and other
content-addressed protocols. Currently investigated approaches include:

 * dweb:// protocol handler (arewedistributedyet/issues/28 (opens new window))
 * .dweb special-use top-level domain name (arewedistributedyet/issues/34 (opens
   new window))


WAS THIS INFORMATION HELPFUL?

Yes No
Edit this page on GitHub or open an issue

Help us improve this site!

 * Suggest new content

 * Give general feedback