coosld/kubo
1
0
Fork 0
mirror of https://github.com/ipfs/kubo.git synced 2026-02-21 10:27:46 +08:00
Code Issues Actions 3 Packages Projects Releases Wiki Activity

docs: Update and clean-up

Browse Source 
License: MIT
Signed-off-by: Łukasz Magiera <magik6k@gmail.com>
This commit is contained in:
Łukasz Magiera 2017-09-08 17:19:02 +02:00
parent ec43a84372
commit f70fa0a2a5
7 changed files with 222 additions and 145 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

39
docs/config.md
View File

@ -1,8 +1,8 @@
# The go-ipfs config file
The go-ipfs config file is a json document. It is read once at node instantiation,
either for an offline command, or for starting the daemon. Commands that execute on
a running daemon do not read the config file at runtime.
either for an offline command, or when starting the daemon. Commands that execute
on a running daemon do not read the config file at runtime.
## Table of Contents
@ -68,29 +68,32 @@ Default: The ipfs.io bootstrap nodes
Contains information related to the construction and operation of the on-disk
storage system.
- `Path`
Path to the leveldb datastore directory. Set during init to either `$IPFS_PATH/datastore`, or `$HOME/.ipfs/datastore` if `$IPFS_PATH` is unset.
- `StorageMax`
An upper limit on the total size of the ipfs repository's datastore. Writes to the datastore will begin to fail once this limit is reached.
An upper limit on the total size of the ipfs repository's datastore. Writes to
the datastore will begin to fail once this limit is reached.
Default: `10GB`
- `StorageGCWatermark`
The percentage of the `StorageMax` value at which a garbage collection will be triggered automatically if the daemon was run with automatic gc enabled (that option defaults to false currently).
The percentage of the `StorageMax` value at which a garbage collection will be
triggered automatically if the daemon was run with automatic gc enabled (that
option defaults to false currently).
Default: `90`
- `GCPeriod`
A time duration specifying how frequently to run a garbage collection. Only used if automatic gc is enabled.
A time duration specifying how frequently to run a garbage collection. Only used
if automatic gc is enabled.
Default: `1h`
- `HashOnRead`
A boolean value. If set to true, all block reads from disk will be hashed and verified. This will cause increased CPU utilization.
A boolean value. If set to true, all block reads from disk will be hashed and
verified. This will cause increased CPU utilization.
- `BloomFilterSize`
A number representing the size in bytes of the blockstore's bloom filter. A value of zero represents the feature being disabled.
A number representing the size in bytes of the blockstore's bloom filter. A
value of zero represents the feature being disabled.
Default: `0`
@ -185,7 +188,9 @@ Default: `[]`
## `Identity`
- `PeerID`
The unique PKI identity label for this configs peer. Set on init and never read, its merely here for convenience. Ipfs will always generate the peerID from its keypair at runtime.
The unique PKI identity label for this configs peer. Set on init and never read,
its merely here for convenience. Ipfs will always generate the peerID from its
keypair at runtime.
- `PrivKey`
The base64 encoded protobuf describing (and containing) the nodes private key.
@ -193,14 +198,17 @@ The base64 encoded protobuf describing (and containing) the nodes private key.
## `Ipns`
- `RepublishPeriod`
A time duration specifying how frequently to republish ipns records to ensure they stay fresh on the network. If unset, we default to 12 hours.
A time duration specifying how frequently to republish ipns records to ensure
they stay fresh on the network. If unset, we default to 12 hours.
- `RecordLifetime`
A time duration specifying the value to set on ipns records for their validity lifetime.
A time duration specifying the value to set on ipns records for their validity
lifetime.
If unset, we default to 24 hours.
- `ResolveCacheSize`
The number of entries to store in an LRU cache of resolved ipns entries. Entries will be kept cached until their lifetime is expired.
The number of entries to store in an LRU cache of resolved ipns entries. Entries
will be kept cached until their lifetime is expired.
Default: `128`
@ -242,7 +250,8 @@ Options for configuring the swarm.
- `AddrFilters`
An array of address filters (multiaddr netmasks) to filter dials to.
See https://github.com/ipfs/go-ipfs/issues/1226#issuecomment-120494604 for more information.
See https://github.com/ipfs/go-ipfs/issues/1226#issuecomment-120494604 for more
information.
- `DisableBandwidthMetrics`
A boolean value that when set to true, will cause ipfs to not keep track of

15
docs/debug-guide.md
View File

@ -60,13 +60,14 @@ Given that information, look for another goroutine that might be
holding the semaphore in question in the rest of the stack dump.
(If you need help doing this, ping and we'll stub this out.)
There are a few different reasons that goroutines can be hung:
- `semacquire` means we're waiting to take a lock or semaphore.
- `select` means that the goroutine is hanging in a select statement and none of the cases are yielding
anything.
- `chan receive` and `chan send` are waiting for a channel to be received from or sent on, respectively.
- `IO wait` generally means that we are waiting on a socket to read or write data, although it *can* mean we are
waiting on a very slow filesystem.
There are a few different reasons that goroutines can be hung:
- `semacquire` means we're waiting to take a lock or semaphore.
- `select` means that the goroutine is hanging in a select statement and none of
the cases are yielding anything.
- `chan receive` and `chan send` are waiting for a channel to be received from
or sent on, respectively.
- `IO wait` generally means that we are waiting on a socket to read or write
data, although it *can* mean we are waiting on a very slow filesystem.
If you see any of those tags _without_ a `,
X minutes` suffix, that generally means there isn't a problem -- you just caught

77
docs/experimental-features.md
View File

@ -2,13 +2,15 @@
This document contains a list of experimental features in go-ipfs.
These features, commands, and APIs aren't mature, and you shouldn't rely on them.
Once they reach maturity, there's going to be mention in the changelog and release posts.
If they don't reach maturity, the same applies, and their code is removed.
Once they reach maturity, there's going to be mention in the changelog and
release posts. If they don't reach maturity, the same applies, and their code is
removed.
Subscribe to https://github.com/ipfs/go-ipfs/issues/3397 to get updates.
When you add a new experimental feature to go-ipfs, or change an experimental feature,
you MUST please make a PR updating this document, and link the PR in the above issue.
When you add a new experimental feature to go-ipfs, or change an experimental
feature, you MUST please make a PR updating this document, and link the PR in
the above issue.
- [ipfs pubsub](#ipfs-pubsub)
- [Client mode DHT routing](#client-mode-dht-routing)
@ -33,7 +35,8 @@ experimental, default-disabled.
### How to enable
run your daemon with the `--enable-pubsub-experiment` flag. Then use the `ipfs pubsub` commands.
run your daemon with the `--enable-pubsub-experiment` flag. Then use the
`ipfs pubsub` commands.
### Road to being a real feature
- [ ] Needs more people to use and report on how well it works
@ -43,7 +46,8 @@ run your daemon with the `--enable-pubsub-experiment` flag. Then use the `ipfs p
---
## Client mode DHT routing
Allows the dht to be run in a mode that doesnt serve requests to the network, saving bandwidth.
Allows the dht to be run in a mode that doesnt serve requests to the network,
saving bandwidth.
### State
experimental.
@ -61,7 +65,10 @@ run your daemon with the `--routing=dhtclient` flag.
---
## go-multiplex stream muxer
Adds support for using the go-multiplex stream muxer alongside (or instead of) yamux and spdy. This multiplexer is far simpler, and uses less memory and bandwidth than the others, but is lacking on congestion control and backpressure logic. It is available to try out and experiment with.
Adds support for using the go-multiplex stream muxer alongside (or instead of)
yamux and spdy. This multiplexer is far simpler, and uses less memory and
bandwidth than the others, but is lacking on congestion control and backpressure
logic. It is available to try out and experiment with.
### State
Experimental
@ -72,12 +79,14 @@ Experimental
### How to enable
run your daemon with `--enable-mplex-experiment`
To make it the default stream muxer, set the environment variable `LIBP2P_MUX_PREFS` as follows:
To make it the default stream muxer, set the environment variable
`LIBP2P_MUX_PREFS` as follows:
```
export LIBP2P_MUX_PREFS="/mplex/6.7.0 /yamux/1.0.0 /spdy/3.1.0"
```
To check which stream muxer is being used between any two given peers, check the json output of the `ipfs swarm peers` command, you'll see something like this:
To check which stream muxer is being used between any two given peers, check the
json output of the `ipfs swarm peers` command, you'll see something like this:
```
$ ipfs swarm peers -v --enc=json | jq .
{
@ -104,7 +113,8 @@ $ ipfs swarm peers -v --enc=json | jq .
```
### Road to being a real feature
- [ ] Significant real world testing and performance metrics across a wide variety of workloads showing that it works well.
- [ ] Significant real world testing and performance metrics across a wide
variety of workloads showing that it works well.
---
@ -167,16 +177,22 @@ go get github.com/Kubuxu/go-ipfs-swarm-key-gen/ipfs-swarm-key-gen
ipfs-swarm-key-gen > ~/.ipfs/swarm.key
```
To join a given private network, get the key file from someone in the network and save it to `~/.ipfs/swarm.key` (If you are using a custom `$IPFS_PATH`, put it in there instead).
To join a given private network, get the key file from someone in the network
and save it to `~/.ipfs/swarm.key` (If you are using a custom `$IPFS_PATH`, put
it in there instead).
When using this feature, you will not be able to connect to the default bootstrap nodes (Since we arent part of your private network) so you will need to set up your own bootstrap nodes.
When using this feature, you will not be able to connect to the default bootstrap
nodes (Since we arent part of your private network) so you will need to set up
your own bootstrap nodes.
To prevent your node from even trying to connect to the default bootstrap nodes, run:
```bash
ipfs bootstrap rm --all
```
To be extra cautious, You can also set the `LIBP2P_FORCE_PNET` environment variable to `1` to force the usage of private networks. If no private network is configured, the daemon will fail to start.
To be extra cautious, You can also set the `LIBP2P_FORCE_PNET` environment
variable to `1` to force the usage of private networks. If no private network is
configured, the daemon will fail to start.
### Road to being a real feature
- [ ] Needs more people to use and report on how well it works
@ -204,10 +220,12 @@ Basic usage:
- Open a listener on one node (node A)
`ipfs p2p listener open p2p-test /ip4/127.0.0.1/tcp/10101`
- Where `/ip4/127.0.0.1/tcp/10101` put address of application you want to pass p2p connections to
- Where `/ip4/127.0.0.1/tcp/10101` put address of application you want to pass
p2p connections to
- On the other node, connect to the listener on node A
`ipfs p2p stream dial $NODE_A_PEERID p2p-test /ip4/127.0.0.1/tcp/10102`
- Node B is now listening for a connection on TCP at 127.0.0.1:10102, connect your application there to complete the connection
- Node B is now listening for a connection on TCP at 127.0.0.1:10102, connect
your application there to complete the connection
### Road to being a real feature
- [ ] Needs more people to use and report on how well it works / fits use cases
@ -229,15 +247,14 @@ master, 0.4.11
### How to enable
The relay transport is enabled by default, which allows peers to dial
through relay and listens for incoming relay connections.
The transport can be disabled by setting `Swarm.DisableRelay = true` in
the configuration.
The relay transport is enabled by default, which allows peers to dial through
relay and listens for incoming relay connections. The transport can be disabled
by setting `Swarm.DisableRelay = true` in the configuration.
By default, peers don't act as intermediate nodes (relays). This can
be enabled by setting `Swarm.EnableRelayHop = true` in the configuration.
Note that the option needs to be set before online services are started
to have an effect; an already online node would have to be restarted.
By default, peers don't act as intermediate nodes (relays). This can be enabled
by setting `Swarm.EnableRelayHop = true` in the configuration. Note that the
option needs to be set before online services are started to have an effect; an
already online node would have to be restarted.
### Basic Usage:
@ -258,10 +275,10 @@ Peers can see their (unspecific) relay address in the output of
### Road to being a real feature
- [ ] Needs more people to use it and report on how well it works.
- [ ] Advertise relay addresses to the DHT for NATed or otherwise
unreachable peers.
- [ ] Active relay discovery for specific relay address advertisement.
We would like advertised relay addresses to designate specific relays
for efficient dialing.
- [ ] Dialing priorities for relay addresses; arguably, relay addresses
should have lower priority than direct dials.
- [ ] Advertise relay addresses to the DHT for NATed or otherwise unreachable
peers.
- [ ] Active relay discovery for specific relay address advertisement. We would
like advertised relay addresses to designate specific relays for efficient
dialing.
- [ ] Dialing priorities for relay addresses; arguably, relay addresses should
have lower priority than direct dials.

123
docs/fuse.md
View File

@ -1,8 +1,55 @@
# FUSE
As a golang project, `go-ipfs` is easily downloaded and installed with `go get github.com/ipfs/go-ipfs`. All data is stored in a leveldb data store in `~/.ipfs/datastore`. If, however, you would like to mount the datastore (`ipfs mount /ipfs`) and use it as you would a normal filesystem, you will need to install fuse.
`go-ipfs` makes it possible to mount `/ipfs` and `/ipns` namespaces in your OS,
allowing arbitrary apps access to IPFS.
As a precursor, you will have to create the `/ipfs` and `/ipns` directories explicitly. Note that modifying root requires sudo permissions.
## Install FUSE
You will need to install and configure fuse before you can mount IPFS
#### Linux
Note: while this guide should work for most distributions, you may need to refer
to your distribution manual to get things working.
Install `fuse` with your favorite package manager:
```
sudo apt-get install fuse
```
Add the user which will be running IPFS daemon to the `fuse` group:
```sh
sudo usermod -a -G fuse <username>
```
Restart user session, if active, for the change to apply, either by restarting
ssh connection or by re-logging to the system.
#### Mac OSX -- OSXFUSE
It has been discovered that versions of `osxfuse` prior to `2.7.0` will cause a
kernel panic. For everyone's sake, please upgrade (latest at time of writing is
`2.7.4`). The installer can be found at https://osxfuse.github.io/. There is
also a homebrew formula (`brew install osxfuse`) but users report best results
installing from the official OSXFUSE installer package.
Note that `ipfs` attempts an automatic version check on `osxfuse` to prevent you
from shooting yourself in the foot if you have pre `2.7.0`. Since checking the
OSXFUSE version [is more complicated than it should be], running `ipfs mount`
may require you to install another binary:
```sh
go get github.com/jbenet/go-fuse-version/fuse-version
```
If you run into any problems installing FUSE or mounting IPFS, hop on IRC and
speak with us, or if you figure something new out, please add to this document!
## Prepare mountpoints
By default ipfs uses `/ipfs` and `/ipns` directories for mounting, this can be
changed in config. You will have to create the `/ipfs` and `/ipns` directories
explicitly. Note that modifying root requires sudo permissions.
```sh
# make the directories
@ -16,54 +63,14 @@ sudo chown <username> /ipns
Depending on whether you are using OSX or Linux, follow the proceeding instructions.
## Mac OSX -- OSXFUSE
It has been discovered that versions of `osxfuse` prior to `2.7.0` will cause a kernel panic. For everyone's sake, please upgrade (latest at time of writing is `2.7.4`). The installer can be found at https://osxfuse.github.io/. There is also a homebrew formula (`brew install osxfuse`) but users report best results installing from the official OSXFUSE installer package.
Note that `ipfs` attempts an automatic version check on `osxfuse` to prevent you from shooting yourself in the foot if you have pre `2.7.0`. Since checking the OSXFUSE version [is more complicated than it should be], running `ipfs mount` may require you to install another binary:
```sh
go get github.com/jbenet/go-fuse-version/fuse-version
```
If you run into any problems installing FUSE or mounting IPFS, hop on IRC and speak with us, or if you figure something new out, please add to this document!
## Linux
Install `fuse` with your favorite package manager:
```
sudo apt-get install fuse
```
Then change permissions on the fuse config:
```sh
sudo chown <username>:<groupname> /etc/fuse.conf
```
You may also have to change `/dev/fuse`:
```sh
sudo chown <username>:<groupname> /dev/fuse
```
NOTE: `<groupname>` will usually be `fuse`. Typically, you add the authorized users to the `fuse` group:
```sh
sudo usermod -a -G fuse <username>
```
## Mounting IPFS
Once FUSE and the mountpoints have been created, issue the following command:
```sh
ipfs daemon --mount
```
If you wish to allow other users to use the mount points, edit /etc/fuse.conf to enable non-root users, i.e.:
If you wish to allow other users to use the mount points, edit `/etc/fuse.conf`
to enable non-root users, i.e.:
```sh
# /etc/fuse.conf - Configuration file for Filesystem in Userspace (FUSE)
@ -75,8 +82,7 @@ If you wish to allow other users to use the mount points, edit /etc/fuse.conf to
user_allow_other
```
and use the following:
Next set `Mounts.FuseAllowOther` config option to `true`:
```sh
ipfs config --json Mounts.FuseAllowOther true
ipfs daemon --mount
@ -84,40 +90,45 @@ ipfs daemon --mount
## Troubleshooting
### Getting `Permission denied` or `fusermount: user has no write access to mountpoint` error in Linux
#### `Permission denied` or `fusermount: user has no write access to mountpoint` error in Linux
Verify that the config file can be read by your user:
```sh
sudo ls -l /etc/fuse.conf
-rw-r----- 1 root fuse 216 Jan 2 2013 /etc/fuse.conf
```
In most distributions group named `fuse` will be created during installation. You can check with:
In most distributions group named `fuse` is be created during fuse installation.
You can check this with:
```sh
sudo grep -q fuse /etc/group && echo fuse_group_present || echo fuse_group_missing
```
If group is present, just add your regular user to the `fuse` group:
If the group is present, just add your regular user to the `fuse` group:
```sh
sudo usermod -G fuse -a <username>
```
If not, create `fuse` group (add your regular user to it) and set necessary permissions, for example:
If the group didn't exist, create `fuse` group (add your regular user to it) and
set necessary permissions, for example:
```sh
sudo chgrp fuse /etc/fuse.conf
sudo chmod g+r /etc/fuse.conf
sudo chgrp fuse /ipfs /ipns
sudo chmod g+rw /ipfs /ipns
```
<!--
TODO: udev rules for /dev/fuse?
-->
Note that the use of `fuse` group is optional and may depend on your operating system.
It is okay to use a different group as long as proper permissions are set for user running `ipfs mount` command.
Note that the use of `fuse` group is optional and may depend on your operating
system. It is okay to use a different group as long as proper permissions are
set for user running `ipfs mount` command.
### Mount command crashes and mountpoint gets stuck
#### Mount command crashes and mountpoint gets stuck
```
sudo umount /ipfs
sudo umount /ipns
```
If you manage to mount on other systems (or followed an alternative path to one above), please contribute to these docs :D
If you manage to mount on other systems (or followed an alternative path to one
above), please contribute to these docs :D

28
docs/github-issue-guide.md
View File

@ -1,15 +1,21 @@
# How to file a GitHub Issue
We use GitHub Issues to log all of our todos and tasks. Here is [a good guide](https://guides.github.com/features/issues/) for them if you are unfamiliar.
We use GitHub Issues to log all of our todos and tasks. Here is
[a good guide](https://guides.github.com/features/issues/) for them if you are
unfamiliar.
When logging an issue with go-ipfs, it would be useful if you specified the below information, if possible. This will help us triage the issues faster. Please title your issues with the type. For instance:
When logging an issue with go-ipfs, it would be useful if you specified the
below information, if possible. This will help us triage the issues faster.
Please title your issues with the type. For instance:
- "bug: Cannot add file with `ipfs add`"
- "question: How do I use `ipfs block <hash>`?"
Putting the command in backticks helps us parse the natural language description, and is generally suggested.
Putting the command in backticks helps us parse the natural language description,
and is generally suggested.
This is a _living guide_. If you see anything that should be here and isn't, or have ideas on improvement, please open a "meta" issue.
This is a _living guide_. If you see anything that should be here and isn't, or
have ideas on improvement, please open a "meta" issue.
### Type
@ -33,7 +39,7 @@ Your platform.
### Processor
Your processor.
Your processor architecture.
- "x86"
- "amd64"
@ -72,8 +78,10 @@ What your issue refers to. Multiple items are OK.
### Priority
- "P0 - Operations on Fire (critical bug affecting release)"
- "P1 - Operations Foobar (critical bug affecting master)"
- "P2 - Operations Not Functioning"
- "P3 - Operations Sort of Functioning"
- "P4 - Operations Functioning"
- Critical - System crash, application panic.
- High - The main functionality of the application does not work, API breakage,
repo format breakage, etc.
- Medium - A non-essential functionality does not work, performance issues, etc.
- Low - An optional functionality does not work.
- Very Low - Translation or documentation mistake. Something that really does
not matter much but should be noticed for a future release.

82
docs/implement-api-bindings.md
View File

@ -1,6 +1,7 @@
# IPFS API Implementation Doc
This short document aims to give a quick guide to anyone implementing API bindings for IPFS implementations-- in particular go-ipfs.
This short document aims to give a quick guide to anyone implementing API
bindings for IPFS implementations-- in particular go-ipfs.
Sections:
- IPFS Types
@ -10,71 +11,98 @@ Sections:
## IPFS Types
IPFS uses a set of type value that is useful to enumerate up front:
IPFS uses a set of value type that is useful to enumerate up front:
- `<ipfs-path>` is unix-style path, beginning with `/ipfs/<hash>/...` or `/ipns/<hash>/...` or `/ipns/<domain>/...`.
- `<hash>` is a base58 encoded [multihash](https://github.com/jbenet/multihash) (there are [many implementations](https://github.com/jbenet/multihash#implementations)). Usually the hash of an IPFS object (or merkle dag node).
- `<ipfs-path>` is unix-style path, beginning with `/ipfs/<cid>/...` or
`/ipns/<hash>/...` or `/ipns/<domain>/...`.
- `<hash>` is a base58 encoded [multihash](https://github.com/multiformats/multihash)
- `cid` is a [multibase](https://github.com/multiformats/multibase) encoded
[CID](https://github.com/ipld/cid) - a self-describing content-addressing identifier
A note on streams: IPFS is a streaming protocol. Everything about it can be streamed. When importing files, API requests should aim to stream the data in, and handle back-pressure correctly, so that the IPFS node can handle it sequentially without too much memory pressure. (If using HTTP, this is typically handled for you by writes to the request body blocking.)
A note on streams: IPFS is a streaming protocol. Everything about it can be
streamed. When importing files, API requests should aim to stream the data in,
and handle back-pressure correctly, so that the IPFS node can handle it
sequentially without too much memory pressure. (If using HTTP, this is typically
handled for you by writes to the request body blocking.)
## API Transports
Like with everything else, IPFS aims to be flexible regarding the API transports. Currently, the [go-ipfs](https://github.com/ipfs/go-ipfs) implementation supports both an in-process API and an HTTP api. More can be added easily, by mapping the API functions over a transport. (This is similar to how gRPC is also _mapped on top of transports_, like HTTP).
Like with everything else, IPFS aims to be flexible regarding the API transports.
Currently, the [go-ipfs](https://github.com/ipfs/go-ipfs) implementation supports
both an in-process API and an HTTP api. More can be added easily, by mapping the
API functions over a transport. (This is similar to how gRPC is also _mapped on
top of transports_, like HTTP).
Mapping to a transport involves leveraging the transport's features to express function calls. For example:
Mapping to a transport involves leveraging the transport's features to express
function calls. For example:
### CLI API Transport
#### CLI API Transport
In the commandline, IPFS uses a traditional flag and arg-based mapping, where:
- the first arguments selects the command, as in git - e.g. `ipfs object get`
- the flags specify options - e.g. `--enc=protobuf -q`
- the rest are positional arguments - e.g. `ipfs object patch <hash1> add-link foo <hash2>`
- the rest are positional arguments - e.g.
`ipfs object patch <hash1> add-linkfoo <hash2>`
- files are specified by filename, or through stdin
(NOTE: When go-ipfs runs the daemon, the CLI API is actually converted to HTTP calls. otherwise, they execute in the same process)
(NOTE: When go-ipfs runs the daemon, the CLI API is actually converted to HTTP
calls. otherwise, they execute in the same process)
### HTTP API Transport
#### HTTP API Transport
In HTTP, our API layering uses a REST-like mapping, where:
- the URL path selects the command - e.g `/object/get`
- the URL query string implements option arguments - e.g. `&enc=protobuf&q=true`
- the URL query also implements positional arguments - e.g. `&arg=<hash1>&arg=add-link&arg=foo&arg=<hash2>`
- the URL query also implements positional arguments - e.g.
`&arg=<hash1>&arg=add-link&arg=foo&arg=<hash2>`
- the request body streams file data - reads files or stdin
- multiple streams are muxed with multipart (todo: add tar stream support)
## API Commands
There is a "standard IPFS API" with a set of commands, which we are documenting clearly soon. But this is not yet extracted into its own document. Perhaps -- as part of this API Bindings effort -- we can document it all. It is currently defined as "all the commands exposed by the go-ipfs implementation". You can see [a listing here](https://github.com/ipfs/go-ipfs/blob/916f987de2c35db71815b54bbb9a0a71df829838/core/commands/root.go#L82-L111), or by running `ipfs commands` locally. **The good news is: we should be able to easily write a program that outputs a markdown API specification!**
(NOTE: The go-ipfs [commands library](https://github.com/ipfs/go-ipfs/tree/916f987de2c35db71815b54bbb9a0a71df829838/commands) also makes sure to keep the CLI and the HTTP API exactly in sync.)
There is a "standard IPFS API" which is currently defined as "all the commands
exposed by the go-ipfs implementation". There are auto-generated [API Docs](https://ipfs.io/docs/api/).
You can Also see [a listing here](https://git.io/v5KG1), or get a list of
commands by running `ipfs commands` locally.
## Implementing bindings for the HTTP API
As mentioned above, the API commands map to HTTP with:
- the URL path selects the command - e.g `/object/get`
- the URL query string implements option arguments - e.g. `&enc=protobuf&q=true`
- the URL query also implements positional arguments - e.g. `&arg=<hash1>&arg=add-link&arg=foo&arg=<hash2>`
- the URL query also implements positional arguments - e.g.
`&arg=<hash1>&arg=add-link&arg=foo&arg=<hash2>`
- the request body streams file data - reads files or stdin
- multiple streams are muxed with multipart (todo: add tar stream support)
To date, we have two different HTTP API clients:
- [node-ipfs-api](https://github.com/ipfs/node-ipfs-api) - simple javascript wrapper -- best to look at
- [go-ipfs/commands/http](https://github.com/ipfs/go-ipfs/tree/916f987de2c35db71815b54bbb9a0a71df829838/commands/http) - generalized transport based on the [command definitions](https://github.com/ipfs/go-ipfs/tree/916f987de2c35db71815b54bbb9a0a71df829838/core/commands)
- [js-ipfs-api](https://github.com/ipfs/js-ipfs-api) - simple javascript
wrapper -- best to look at
- [go-ipfs/commands/http](https://git.io/v5KnB) -
generalized transport based on the [command definitions](https://git.io/v5KnE)
The Go implementation is good to answer harder questions, like how is multipart handled, or what headers should be set in edge conditions. But the javascript implementation is very concise, and easy to follow.
The Go implementation is good to answer harder questions, like how is multipart
handled, or what headers should be set in edge conditions. But the javascript
implementation is very concise, and easy to follow.
### Anatomy of node-ipfs-api
#### Anatomy of node-ipfs-api
Currently, node-ipfs-api has three main files
- [src/index.js](https://github.com/ipfs/node-ipfs-api/blob/66d1462bd02181d46e8baf4cd9d476b213426ad8/src/index.js) defines the functions clients of the API module will use. uses `RequestAPI`, and translates function call parameters to the API almost directly.
- [src/get-files-stream.js](https://github.com/ipfs/node-ipfs-api/blob/66d1462bd02181d46e8baf4cd9d476b213426ad8/src/get-files-stream.js) implements the hardest part: file streaming. This one uses multipart.
- [src/request-api.js](https://github.com/ipfs/node-ipfs-api/blob/66d1462bd02181d46e8baf4cd9d476b213426ad8/src/request-api.js) generic function call to perform the actual HTTP requests
- [src/index.js](https://git.io/v5Kn2) defines the functions clients of the API
module will use. uses `RequestAPI`, and translates function call parameters to
the API almost directly.
- [src/get-files-stream.js](https://git.io/v5Knr) implements the hardest part:
file streaming. This one uses multipart.
- [src/request-api.js](https://git.io/v5KnP) generic function call to perform
the actual HTTP requests
### Note on multipart + inspecting requests
## Note on multipart + inspecting requests
Despite all the generalization spoken about above, the IPFS API is actually very simple. You can inspect all the requests made with `nc` and the `--api` option (as of [this PR](https://github.com/ipfs/go-ipfs/pull/1598), or `0.3.8`):
Despite all the generalization spoken about above, the IPFS API is actually very
simple. You can inspect all the requests made with `nc` and the `--api` option
(as of [this PR](https://github.com/ipfs/go-ipfs/pull/1598), or `0.3.8`):
```
> nc -l 5002 &
@ -89,7 +117,9 @@ Accept-Encoding: gzip
```
The only hard part is getting the file streaming right. It is (now) fairly easy to stream files to go-ipfs using multipart. Basically, we end up with HTTP requests like this:
The only hard part is getting the file streaming right. It is (now) fairly easy
to stream files to go-ipfs using multipart. Basically, we end up with HTTP
requests like this:
```
> nc -l 5002 &

3
docs/openbsd.md
View File

@ -20,7 +20,8 @@ $ export PATH="$PATH:$GOPATH/bin"
## Build
The `install_unsupported` target works nicely for openbsd. This will install `gx`, `gx-go` and run `go install -tags nofuse ./cmd/ipfs`.
The `install_unsupported` target works nicely for openbsd. This will install
`gx`, `gx-go` and run `go install -tags nofuse ./cmd/ipfs`.
```
$ go get -v -u -d github.com/ipfs/go-ipfs