romenskiy2012/curl
1
0
Fork 0
mirror of https://github.com/curl/curl.git synced 2026-07-26 09:47:18 +03:00
Code Issues Projects Releases Packages Wiki Activity

GHA: add a job scanning for "bad words" in markdown

Browse source 
This means words, phrases or things we have decided not to use - words that
are spelled right according to the dictionary but we want to avoid. In the
name of consistency and better documentation.

Closes #12764
This commit is contained in:
Daniel Stenberg 2024-01-23 15:12:09 +01:00
parent 2620aa930b
commit e5000e797f
No known key found for this signature in database
GPG key ID: 5CC908FDB71E12C2
93 changed files with 530 additions and 348 deletions
Download patch file Download diff file Expand all files Collapse all files

93
docs/IPFS.md
View file

@ -19,12 +19,29 @@ By explicitly requesting [application/vnd.ipld.raw](https://www.iana.org/assignm
This enables users to use untrusted, public gateways without worrying they might return invalid/malicious bytes.
## IPFS and IPNS protocol handling
There are various ways to access data from the IPFS network. One such way is through the concept of public "[gateways](https://docs.ipfs.tech/concepts/ipfs-gateway/#overview)". The short version is that entities can offer gateway services. An example here that is hosted by Protocol Labs (who also makes IPFS) is `dweb.link` and `ipfs.io`. Both sites expose gateway functionality. Getting a file through `ipfs.io` looks like this: `https://ipfs.io/ipfs/bafybeigagd5nmnn2iys2f3doro7ydrevyr2mzarwidgadawmamiteydbzi`
If you were to be [running your own IPFS node](https://docs.ipfs.tech/how-to/command-line-quick-start/) then you, by default, also have a [local gateway](https://specs.ipfs.tech/http-gateways/) running. In it's default configuration the earlier example would then also work in this link: `http://127.0.0.1:8080/ipfs/bafybeigagd5nmnn2iys2f3doro7ydrevyr2mzarwidgadawmamiteydbzi`
There are various ways to access data from the IPFS network. One such way is
through the concept of public
"[gateways](https://docs.ipfs.tech/concepts/ipfs-gateway/#overview)". The
short version is that entities can offer gateway services. An example here
that is hosted by Protocol Labs (who also makes IPFS) is `dweb.link` and
`ipfs.io`. Both sites expose gateway functionality. Getting a file through
`ipfs.io` looks like this:
`https://ipfs.io/ipfs/bafybeigagd5nmnn2iys2f3doro7ydrevyr2mzarwidgadawmamiteydbzi`
If you were to be [running your own IPFS
node](https://docs.ipfs.tech/how-to/command-line-quick-start/) then you, by
default, also have a [local gateway](https://specs.ipfs.tech/http-gateways/)
running. In its default configuration the earlier example would then also work
in this link:
`http://127.0.0.1:8080/ipfs/bafybeigagd5nmnn2iys2f3doro7ydrevyr2mzarwidgadawmamiteydbzi`
## cURL handling of the IPFS protocols
The IPFS integration in cURL hides this gateway logic for you. So instead of providing a full URL to a file on IPFS like this:
The IPFS integration in cURL hides this gateway logic for you. Instead of
providing a full URL to a file on IPFS like this:
```
curl http://127.0.0.1:8080/ipfs/bafybeigagd5nmnn2iys2f3doro7ydrevyr2mzarwidgadawmamiteydbzi
```
@ -34,49 +51,75 @@ You can provide it with the IPFS protocol instead:
curl ipfs://bafybeigagd5nmnn2iys2f3doro7ydrevyr2mzarwidgadawmamiteydbzi
```
With the IPFS protocol way of asking a file, cURL still needs to know the gateway. curl essentially just rewrites the IPFS based URL to a gateway URL.
With the IPFS protocol way of asking a file, cURL still needs to know the
gateway. curl essentially just rewrites the IPFS based URL to a gateway URL.
### IPFS_GATEWAY environment variable
If the `IPFS_GATEWAY` environment variable is found, it's value is used as gateway.
If the `IPFS_GATEWAY` environment variable is found, its value is used as
gateway.
### Automatic gateway detection
When you provide no additional details to cURL then cURL will:
1. First look for the `IPFS_GATEWAY` environment variable and use that if it's set.
2. Look for the file: `~/.ipfs/gateway`. If it can find that file then it means that you have a local gateway running and that file contains the URL to your local gateway.
1. First look for the `IPFS_GATEWAY` environment variable and use that if it
is set.
2. Look for the file: `~/.ipfs/gateway`. If it can find that file then it
means that you have a local gateway running and that file contains the URL
to your local gateway.
If cURL fails you'll be presented with an error message and a link to this page to the option most applicable to solving the issue.
If cURL fails you will be presented with an error message and a link to this
page to the option most applicable to solving the issue.
### `--ipfs-gateway` argument
You can also provide a `--ipfs-gateway` argument to cURL. This overrules any other gateway setting. curl won't fallback to the other options if the provided gateway didn't work.
You can also provide a `--ipfs-gateway` argument to cURL. This overrules any
other gateway setting. curl will not fallback to the other options if the
provided gateway did not work.
## Gateway redirects
A gateway could redirect to another place. For example, `dweb.link` redirects [path based](https://docs.ipfs.tech/how-to/address-ipfs-on-web/#path-gateway) requests to [subdomain based](https://docs.ipfs.tech/how-to/address-ipfs-on-web/#subdomain-gateway) ones. So a request to:
```
curl ipfs://bafybeigagd5nmnn2iys2f3doro7ydrevyr2mzarwidgadawmamiteydbzi --ipfs-gateway https://dweb.link
```
A gateway could redirect to another place. For example, `dweb.link` redirects
[path based](https://docs.ipfs.tech/how-to/address-ipfs-on-web/#path-gateway)
requests to [subdomain
based](https://docs.ipfs.tech/how-to/address-ipfs-on-web/#subdomain-gateway)
ones. A request using:
curl ipfs://bafybeigagd5nmnn2iys2f3doro7ydrevyr2mzarwidgadawmamiteydbzi --ipfs-gateway https://dweb.link
Which would be translated to:
```
https://dweb.link/ipfs/bafybeigagd5nmnn2iys2f3doro7ydrevyr2mzarwidgadawmamiteydbzi
```
https://dweb.link/ipfs/bafybeigagd5nmnn2iys2f3doro7ydrevyr2mzarwidgadawmamiteydbzi
Will redirect to:
```
https://bafybeigagd5nmnn2iys2f3doro7ydrevyr2mzarwidgadawmamiteydbzi.ipfs.dweb.link
```
https://bafybeigagd5nmnn2iys2f3doro7ydrevyr2mzarwidgadawmamiteydbzi.ipfs.dweb.link
If you trust this behavior from your gateway of choice then passing the `-L` option will follow the redirect.
## Error messages and hints
Depending on the arguments, cURL could present the user with an error.
### Gateway file and environment variable
cURL tried to look for the file: `~/.ipfs/gateway` but couldn't find it. It also tried to look for the `IPFS_GATEWAY` environment variable but couldn't find that either. This happens when no extra arguments are passed to cURL and letting it try to figure it out [automatically](#automatic-gateway-detection).
Any IPFS implementation that has gateway support should expose it's URL in `~/.ipfs/gateway`. If you are already running a gateway, make sure it exposes the file where cURL expects to find it.
cURL tried to look for the file: `~/.ipfs/gateway` but could not find it. It
also tried to look for the `IPFS_GATEWAY` environment variable but could not
find that either. This happens when no extra arguments are passed to cURL and
letting it try to figure it out [automatically](#automatic-gateway-detection).
Alternatively you could set the `IPFS_GATEWAY` environment variable or pass the `--ipfs-gateway` flag to the cURL command.
Any IPFS implementation that has gateway support should expose its URL in
`~/.ipfs/gateway`. If you are already running a gateway, make sure it exposes
the file where cURL expects to find it.
Alternatively you could set the `IPFS_GATEWAY` environment variable or pass
the `--ipfs-gateway` flag to the cURL command.
### Malformed gateway URL
The command executed evaluates in an invalid URL. This could be anywhere in the URL, but a likely point is a wrong gateway URL.
Inspect the URL set via the `IPFS_GATEWAY` environment variable or passed with the `--ipfs-gateway` flag.
Alternatively opt to go for the [automatic](#automatic-gateway-detection) gateway detection.
The command executed evaluates in an invalid URL. This could be anywhere in
the URL, but a likely point is a wrong gateway URL.
Inspect the URL set via the `IPFS_GATEWAY` environment variable or passed with
the `--ipfs-gateway` flag. Alternatively opt to go for the
[automatic](#automatic-gateway-detection) gateway detection.