Skip to content

Commit c9dd755

Browse files
lidellidel
committed
docs(config): refactor to match updated style
Reuses style from #6855 License: MIT Signed-off-by: Marcin Rataj <[email protected]>
1 parent bb82e48 commit c9dd755

File tree

1 file changed

+102
-62
lines changed

1 file changed

+102
-62
lines changed

‎docs/config.md

+102-62
Original file line numberDiff line numberDiff line change
@@ -83,10 +83,13 @@ Available profiles:
8383
- [`Routing.Type`](#routingtype)
8484
- [`Gateway`](#gateway)
8585
- [`Gateway.NoFetch`](#gatewaynofetch)
86+
- [`Gateway.NoDNSLink`](#gatewaynodnslink)
8687
- [`Gateway.HTTPHeaders`](#gatewayhttpheaders)
8788
- [`Gateway.RootRedirect`](#gatewayrootredirect)
8889
- [`Gateway.Writable`](#gatewaywritable)
8990
- [`Gateway.PathPrefixes`](#gatewaypathprefixes)
91+
- [`Gateway.PublicGateways`](#gatewaypublicgateways)
92+
- [`Gateway` recipes](#gateway-recipes)
9093
- [`Identity`](#identity)
9194
- [`Identity.PeerID`](#identitypeerid)
9295
- [`Identity.PrivKey`](#identityprivkey)
@@ -348,6 +351,14 @@ and will not fetch files from the network.
348351

349352
Default: `false`
350353

354+
### `Gateway.NoDNSLink`
355+
356+
A boolean to configure whether DNSLink lookup for value in `Host` HTTP header
357+
should be performed. If DNSLink is present, content path stored in the DNS TXT
358+
record becomes the `/` and respective payload is returned to the client.
359+
360+
Default: `false`
361+
351362
### `Gateway.HTTPHeaders`
352363

353364
Headers to set on gateway responses.
@@ -408,43 +419,97 @@ location /blog/ {
408419

409420
Default: `[]`
410421

411-
- `NoDNSLink`
412-
A boolean to configure whether DNSLink lookup for value in `Host`
413-
HTTP header should be performed. If DNSLink is present, content path stored
414-
in the DNS TXT record is mounted at `/` and respective payload is returned to
415-
the client.
422+
423+
### `Gateway.PublicGateways`
424+
425+
`PublicGateways` is a dictionary for defining gateway behavior on specified hostnames.
426+
427+
#### `Gateway.PublicGateways[hostname]: Paths`
428+
429+
Array of paths that should be exposed on the hostname.
430+
431+
Example:
432+
```json
433+
{
434+
"Gateway": {
435+
"PublicGateways": {
436+
"example.com": {
437+
"Paths": ["/ipfs", "/ipns"],
438+
```
439+
440+
Above enables `http://example.com/ipfs/*` and `http://example.com/ipns/*` but not `http://example.com/api/*`
441+
442+
Default: `[]`
443+
444+
#### `Gateway.PublicGateways[hostname]: UseSubdomains`
445+
446+
A boolean to configure whether the gateway at the hostname provides [Origin isolation](https://developer.mozilla.org/en-US/docs/Web/Security/Same-origin_policy)
447+
between content roots.
448+
449+
- `true` - enable [subdomain gateway](#https://docs-beta.ipfs.io/how-to/address-ipfs-on-web/#subdomain-gateway) at `http://*.{hostname}/`
450+
- **Note 1:** make sure respective `Paths` are set.
451+
For example, `Paths: ["/ipfs", "/ipns"]` are required for `http://{cid}.ipfs.{hostname}` and `http://{foo}.ipns.{hostname}` to work:
452+
```json
453+
{
454+
"Gateway": {
455+
"PublicGateways": {
456+
"dweb.link": {
457+
"UseSubdomains": true,
458+
"Paths": ["/ipfs", "/ipns"],
459+
```
460+
- **Note 2:** Requests for content paths such as `http://{hostname}/ipfs/{cid}` produce redirect to `http://{cid}.ipfs.{hostname}`
461+
462+
- `false` - enable [path gateway](https://docs-beta.ipfs.io/how-to/address-ipfs-on-web/#path-gateway) at `http://{hostname}/*`
463+
- Example:
464+
```json
465+
{
466+
"Gateway": {
467+
"PublicGateways": {
468+
"ipfs.io": {
469+
"UseSubdomains": false,
470+
"Paths": ["/ipfs", "/ipns", "/api"],
471+
```
472+
<!-- **(not implemented yet)** due to the lack of Origin isolation, cookies and storage on `Paths` will be disabled by [Clear-Site-Data](https://github.com/ipfs/in-web-browsers/issues/157) header -->
416473

417474
Default: `false`
418475

419-
### Gateway.PublicGateways
420476

421-
`PublicGateways` is a dictionary for defining gateway behavior on specific fully qualified domain names (FQDN).
422-
Options for changing behavior per hostname:
477+
#### `Gateway.PublicGateways[hostname]: NoDNSLink`
478+
479+
A boolean to configure whether DNSLink for hostname present in `Host`
480+
HTTP header should be resolved. Overrides global setting.
481+
If `Paths` are defined, they take priority over DNSLink.
423482

424-
- `Paths`
425-
Array of paths that should be mounted at the root of domain name.
426-
Example: `["/ipfs", "/ipns", "/api"]`
427-
**Note:** If DNSLink is enabled, all defined `Paths` are mounted on top of `/` and take priority over DNSLink.
483+
Default: `false` (DNSLink lookup enabled by default for every defined hostname)
428484

429-
- `UseSubdomains`
430-
A boolean to configure whether the gateway provides [Origin isolation](https://developer.mozilla.org/en-US/docs/Web/Security/Same-origin_policy)
431-
between content roots.
432-
Default: `false`
433-
- `true` – mount [subdomain gateway](#https://docs-beta.ipfs.io/how-to/address-ipfs-on-web/#subdomain-gateway) at `http://*.{hostname}`
434-
- requires respective `Paths` to be set
435-
Example: `Paths: ["/ipfs", "/ipns"]` is required for `http://{cid}.ipfs.{hostname}` and `http://{foo}.ipns.{hostname}` to work.
436-
- requests for content paths such as `http://{hostname}/ipfs/{cid}` will return redirect to `http://{cid}.ipfs.{hostname}`
437-
- `false` – mount [path gateway](https://docs-beta.ipfs.io/how-to/address-ipfs-on-web/#path-gateway) at `http://{hostname}/ipfs/{cid}`
438-
<!-- **(not implemented yet)** due to the lack of Origin isolation, cookies and storage on `Paths` will be disabled by [Clear-Site-Data](https://github.com/ipfs/in-web-browsers/issues/157) header -->
485+
#### Implicit defaults of `Gateway.PublicGateways`
439486

440-
- `NoDNSLink`
441-
A boolean to configure whether DNSLink for FQDN present in `Host`
442-
HTTP header should be resolved. Overrides global setting.
443-
Default: `false` (DNSLink enabled by default for every defined hostname)
487+
Default entries for `localhost` hostname and loopback IPs are always present.
488+
If additional config is provided for those hostnames, it will be merged on top of implicit values:
489+
```json
490+
{
491+
"Gateway": {
492+
"PublicGateways": {
493+
"127.0.0.1": {
494+
"Paths": ["/ipfs", "/ipns", "/api"],
495+
"UseSubdomains": false
496+
},
497+
"::1": {
498+
"Paths": ["/ipfs", "/ipns", "/api"],
499+
"UseSubdomains": false
500+
},
501+
"localhost": {
502+
"Paths": ["/ipfs", "ipns"],
503+
"UseSubdomains": true
504+
}
505+
}
506+
}
507+
}
508+
```
444509

445-
#### Examples of common use cases
510+
### `Gateway` recipes
446511

447-
* Public [subdomain gateway](https://docs-beta.ipfs.io/how-to/address-ipfs-on-web/#subdomain-gateway) at `http://{cid}.ipfs.dweb.link`
512+
* Public [subdomain gateway](https://docs-beta.ipfs.io/how-to/address-ipfs-on-web/#subdomain-gateway) at `http://{cid}.ipfs.dweb.link` (each content root gets its own Origin)
448513
```json
449514
"Gateway": {
450515
"PublicGateways": {
@@ -455,7 +520,7 @@ Options for changing behavior per hostname:
455520
**Note:** this enables automatic redirects from content paths to subdomains
456521
`http://dweb.link/ipfs/{cid}` → `http://{cid}.ipfs.dweb.link`
457522

458-
* Public [path gateway](https://docs-beta.ipfs.io/how-to/address-ipfs-on-web/#path-gateway) at `http://ipfs.io/ipfs/{cid}`
523+
* Public [path gateway](https://docs-beta.ipfs.io/how-to/address-ipfs-on-web/#path-gateway) at `http://ipfs.io/ipfs/{cid}` (no Origin separation)
459524
```json
460525
"Gateway": {
461526
"PublicGateways": {
@@ -464,17 +529,14 @@ Options for changing behavior per hostname:
464529
"Paths": ["/ipfs", "/ipns", "/api"]
465530
```
466531

467-
* Public [DNSLink](https://dnslink.io/) gateway resolving every hostname passed in `Host` header
468-
(this is the default, works out of the box):
469-
```json
470-
"Gateway": {
471-
"NoDNSLink": false
472-
```
532+
* Public [DNSLink](https://dnslink.io/) gateway resolving every hostname passed in `Host` header.
533+
* `NoDNSLink: false` is the default, works out of the box, no configuration needed
473534

474-
* Hardened, site-specific [DNSLink](https://dnslink.io/) gateway.
475-
Disabling public gateway by default (`NoFetch: true`),
476-
and enabling selected gateway features only on specific hostname for which data
477-
is already present on the node:
535+
* Hardened, site-specific [DNSLink gateway](https://docs-beta.ipfs.io/how-to/address-ipfs-on-web/#dnslink-gateway).
536+
Disable fetching of remote data (`NoFetch: true`)
537+
and resolving DNSLink at unknown hostnames (`NoDNSLink: true`).
538+
Then, enable DNSLink gateway only for the specific hostname (for which data
539+
is already present on the node), without exposing any content-addressing `Paths`:
478540
```json
479541
"Gateway": {
480542
"NoFetch": true,
@@ -483,30 +545,8 @@ Options for changing behavior per hostname:
483545
"en.wikipedia-on-ipfs.org": {
484546
"NoDNSLink": false,
485547
"Paths": []
486-
```
548+
```
487549

488-
**Note:** Default entries for localhost name and loopback IPs are always present.
489-
User-provided config will be merged on top of implicit values:
490-
```json
491-
{
492-
"Gateway": {
493-
"PublicGateways": {
494-
"127.0.0.1": {
495-
"Paths": ["/ipfs", "/ipns", "/api"],
496-
"UseSubdomains": false
497-
},
498-
"::1": {
499-
"Paths": ["/ipfs", "/ipns", "/api"],
500-
"UseSubdomains": false
501-
},
502-
"localhost": {
503-
"Paths": ["/ipfs", "ipns"],
504-
"UseSubdomains": true
505-
}
506-
}
507-
}
508-
}
509-
```
510550

511551
## `Identity`
512552

0 commit comments

Comments
 (0)