@cryptotaxi247 / kubo / commits / f70fa0a2a

docs: Update and clean-up

License: MIT Signed-off-by: Łukasz Magiera <magik6k@gmail.com>

Łukasz Magiera committed Sep 8, 2017 at 17:19 UTC f70fa0a2a5ef1155734a2150b83c1c7e3bd50c13

7 files changed +214 -137

docs/config.md

+24 -15

@@ -1,8 +1,8 @@

1 # The go-ipfs config file

3 The go-ipfs config file is a json document. It is read once at node instantiation,

4 -either for an offline command, or for starting the daemon. Commands that execute on

5 -a running daemon do not read the config file at runtime.

4 +either for an offline command, or when starting the daemon. Commands that execute

5 +on a running daemon do not read the config file at runtime.

7 ## Table of Contents

@@ -68,29 +68,32 @@ Default: The ipfs.io bootstrap nodes

68 Contains information related to the construction and operation of the on-disk

69 storage system.

71 -- `Path`

72 -Path to the leveldb datastore directory. Set during init to either `$IPFS_PATH/datastore`, or `$HOME/.ipfs/datastore` if `$IPFS_PATH` is unset.

73 -

71 - `StorageMax`

75 -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.

72 +An upper limit on the total size of the ipfs repository's datastore. Writes to

73 +the datastore will begin to fail once this limit is reached.

75 Default: `10GB`

77 - `StorageGCWatermark`

80 -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).

78 +The percentage of the `StorageMax` value at which a garbage collection will be

79 +triggered automatically if the daemon was run with automatic gc enabled (that

80 +option defaults to false currently).

82 Default: `90`

84 - `GCPeriod`

85 -A time duration specifying how frequently to run a garbage collection. Only used if automatic gc is enabled.

85 +A time duration specifying how frequently to run a garbage collection. Only used

86 +if automatic gc is enabled.

88 Default: `1h`

90 - `HashOnRead`

90 -A boolean value. If set to true, all block reads from disk will be hashed and verified. This will cause increased CPU utilization.

91 +A boolean value. If set to true, all block reads from disk will be hashed and

92 +verified. This will cause increased CPU utilization.

94 - `BloomFilterSize`

93 -A number representing the size in bytes of the blockstore's bloom filter. A value of zero represents the feature being disabled.

95 +A number representing the size in bytes of the blockstore's bloom filter. A

96 +value of zero represents the feature being disabled.

98 Default: `0`

@@ -185,7 +188,9 @@ Default: `[]`

188 ## `Identity`

189

190 - `PeerID`

188 -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.

191 +The unique PKI identity label for this configs peer. Set on init and never read,

192 +its merely here for convenience. Ipfs will always generate the peerID from its

193 +keypair at runtime.

194

195 - `PrivKey`

196 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.

198 ## `Ipns`

199

200 - `RepublishPeriod`

196 -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.

201 +A time duration specifying how frequently to republish ipns records to ensure

202 +they stay fresh on the network. If unset, we default to 12 hours.

203

204 - `RecordLifetime`

199 -A time duration specifying the value to set on ipns records for their validity lifetime.

205 +A time duration specifying the value to set on ipns records for their validity

206 +lifetime.

207 If unset, we default to 24 hours.

208

209 - `ResolveCacheSize`

203 -The number of entries to store in an LRU cache of resolved ipns entries. Entries will be kept cached until their lifetime is expired.

210 +The number of entries to store in an LRU cache of resolved ipns entries. Entries

211 +will be kept cached until their lifetime is expired.

212

213 Default: `128`

214

@@ -242,7 +250,8 @@ Options for configuring the swarm.

250

251 - `AddrFilters`

252 An array of address filters (multiaddr netmasks) to filter dials to.

245 -See https://github.com/ipfs/go-ipfs/issues/1226#issuecomment-120494604 for more information.

253 +See https://github.com/ipfs/go-ipfs/issues/1226#issuecomment-120494604 for more

254 +information.

255

256 - `DisableBandwidthMetrics`

257 A boolean value that when set to true, will cause ipfs to not keep track of

docs/debug-guide.md

+8 -7

@@ -60,13 +60,14 @@ Given that information, look for another goroutine that might be

60 holding the semaphore in question in the rest of the stack dump.

61 (If you need help doing this, ping and we'll stub this out.)

63 -There are a few different reasons that goroutines can be hung:

64 -- `semacquire` means we're waiting to take a lock or semaphore.

65 -- `select` means that the goroutine is hanging in a select statement and none of the cases are yielding

66 -anything.

67 -- `chan receive` and `chan send` are waiting for a channel to be received from or sent on, respectively.

68 -- `IO wait` generally means that we are waiting on a socket to read or write data, although it *can* mean we are

69 -waiting on a very slow filesystem.

63 +There are a few different reasons that goroutines can be hung:

64 +- `semacquire` means we're waiting to take a lock or semaphore.

65 +- `select` means that the goroutine is hanging in a select statement and none of

66 + the cases are yielding anything.

67 +- `chan receive` and `chan send` are waiting for a channel to be received from

68 + or sent on, respectively.

69 +- `IO wait` generally means that we are waiting on a socket to read or write

70 + data, although it *can* mean we are waiting on a very slow filesystem.

72 If you see any of those tags _without_ a `,

73 X minutes` suffix, that generally means there isn't a problem -- you just caught

docs/experimental-features.md

+47 -30

@@ -2,13 +2,15 @@

3 This document contains a list of experimental features in go-ipfs.

4 These features, commands, and APIs aren't mature, and you shouldn't rely on them.

5 -Once they reach maturity, there's going to be mention in the changelog and release posts.

6 -If they don't reach maturity, the same applies, and their code is removed.

5 +Once they reach maturity, there's going to be mention in the changelog and

6 +release posts. If they don't reach maturity, the same applies, and their code is

7 +removed.

9 Subscribe to https://github.com/ipfs/go-ipfs/issues/3397 to get updates.

10 -When you add a new experimental feature to go-ipfs, or change an experimental feature,

11 -you MUST please make a PR updating this document, and link the PR in the above issue.

11 +When you add a new experimental feature to go-ipfs, or change an experimental

12 +feature, you MUST please make a PR updating this document, and link the PR in

13 +the above issue.

15 - [ipfs pubsub](#ipfs-pubsub)

16 - [Client mode DHT routing](#client-mode-dht-routing)

@@ -33,7 +35,8 @@ experimental, default-disabled.

36 ### How to enable

36 -run your daemon with the `--enable-pubsub-experiment` flag. Then use the `ipfs pubsub` commands.

38 +run your daemon with the `--enable-pubsub-experiment` flag. Then use the

39 +`ipfs pubsub` commands.

41 ### Road to being a real feature

42 - [ ] 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

46 ---

48 ## Client mode DHT routing

46 -Allows the dht to be run in a mode that doesnt serve requests to the network, saving bandwidth.

49 +Allows the dht to be run in a mode that doesnt serve requests to the network,

50 +saving bandwidth.

52 ### State

53 experimental.

@@ -61,7 +65,10 @@ run your daemon with the `--routing=dhtclient` flag.

65 ---

67 ## go-multiplex stream muxer

64 -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.

68 +Adds support for using the go-multiplex stream muxer alongside (or instead of)

69 +yamux and spdy. This multiplexer is far simpler, and uses less memory and

70 +bandwidth than the others, but is lacking on congestion control and backpressure

71 +logic. It is available to try out and experiment with.

73 ### State

74 Experimental

@@ -72,12 +79,14 @@ Experimental

79 ### How to enable

80 run your daemon with `--enable-mplex-experiment`

75 -To make it the default stream muxer, set the environment variable `LIBP2P_MUX_PREFS` as follows:

82 +To make it the default stream muxer, set the environment variable

83 +`LIBP2P_MUX_PREFS` as follows:

84 ```

85 export LIBP2P_MUX_PREFS="/mplex/6.7.0 /yamux/1.0.0 /spdy/3.1.0"

86 ```

80 -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:

88 +To check which stream muxer is being used between any two given peers, check the

89 +json output of the `ipfs swarm peers` command, you'll see something like this:

90 ```

91 $ ipfs swarm peers -v --enc=json | jq .

92 {

@@ -104,7 +113,8 @@ $ ipfs swarm peers -v --enc=json | jq .

113 ```

114

115 ### Road to being a real feature

107 -- [ ] Significant real world testing and performance metrics across a wide variety of workloads showing that it works well.

116 +- [ ] Significant real world testing and performance metrics across a wide

117 + variety of workloads showing that it works well.

118

119 ---

120

@@ -167,16 +177,22 @@ go get github.com/Kubuxu/go-ipfs-swarm-key-gen/ipfs-swarm-key-gen

177 ipfs-swarm-key-gen > ~/.ipfs/swarm.key

178 ```

179

170 -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).

180 +To join a given private network, get the key file from someone in the network

181 +and save it to `~/.ipfs/swarm.key` (If you are using a custom `$IPFS_PATH`, put

182 +it in there instead).

183

172 -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.

184 +When using this feature, you will not be able to connect to the default bootstrap

185 +nodes (Since we arent part of your private network) so you will need to set up

186 +your own bootstrap nodes.

187

188 To prevent your node from even trying to connect to the default bootstrap nodes, run:

189 ```bash

190 ipfs bootstrap rm --all

191 ```

192

179 -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.

193 +To be extra cautious, You can also set the `LIBP2P_FORCE_PNET` environment

194 +variable to `1` to force the usage of private networks. If no private network is

195 +configured, the daemon will fail to start.

196

197 ### Road to being a real feature

198 - [ ] Needs more people to use and report on how well it works

@@ -204,10 +220,12 @@ Basic usage:

220

221 - Open a listener on one node (node A)

222 `ipfs p2p listener open p2p-test /ip4/127.0.0.1/tcp/10101`

207 -- Where `/ip4/127.0.0.1/tcp/10101` put address of application you want to pass p2p connections to

223 +- Where `/ip4/127.0.0.1/tcp/10101` put address of application you want to pass

224 + p2p connections to

225 - On the other node, connect to the listener on node A

226 `ipfs p2p stream dial $NODE_A_PEERID p2p-test /ip4/127.0.0.1/tcp/10102`

210 -- Node B is now listening for a connection on TCP at 127.0.0.1:10102, connect your application there to complete the connection

227 +- Node B is now listening for a connection on TCP at 127.0.0.1:10102, connect

228 + your application there to complete the connection

229

230 ### Road to being a real feature

231 - [ ] Needs more people to use and report on how well it works / fits use cases

@@ -229,15 +247,14 @@ master, 0.4.11

247

248 ### How to enable

249

232 -The relay transport is enabled by default, which allows peers to dial

233 -through relay and listens for incoming relay connections.

234 -The transport can be disabled by setting `Swarm.DisableRelay = true` in

235 -the configuration.

250 +The relay transport is enabled by default, which allows peers to dial through

251 +relay and listens for incoming relay connections. The transport can be disabled

252 +by setting `Swarm.DisableRelay = true` in the configuration.

253

237 -By default, peers don't act as intermediate nodes (relays). This can

238 -be enabled by setting `Swarm.EnableRelayHop = true` in the configuration.

239 -Note that the option needs to be set before online services are started

240 -to have an effect; an already online node would have to be restarted.

254 +By default, peers don't act as intermediate nodes (relays). This can be enabled

255 +by setting `Swarm.EnableRelayHop = true` in the configuration. Note that the

256 +option needs to be set before online services are started to have an effect; an

257 +already online node would have to be restarted.

258

259 ### Basic Usage:

260

@@ -258,10 +275,10 @@ Peers can see their (unspecific) relay address in the output of

275 ### Road to being a real feature

276

277 - [ ] Needs more people to use it and report on how well it works.

261 -- [ ] Advertise relay addresses to the DHT for NATed or otherwise

262 - unreachable peers.

263 -- [ ] Active relay discovery for specific relay address advertisement.

264 - We would like advertised relay addresses to designate specific relays

265 - for efficient dialing.

266 -- [ ] Dialing priorities for relay addresses; arguably, relay addresses

267 - should have lower priority than direct dials.

278 +- [ ] Advertise relay addresses to the DHT for NATed or otherwise unreachable

279 + peers.

280 +- [ ] Active relay discovery for specific relay address advertisement. We would

281 + like advertised relay addresses to designate specific relays for efficient

282 + dialing.

283 +- [ ] Dialing priorities for relay addresses; arguably, relay addresses should

284 + have lower priority than direct dials.

docs/fuse.md

+59 -48

@@ -1,69 +1,76 @@

1 # FUSE

3 -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.

3 +`go-ipfs` makes it possible to mount `/ipfs` and `/ipns` namespaces in your OS,

4 +allowing arbitrary apps access to IPFS.

5 -As a precursor, you will have to create the `/ipfs` and `/ipns` directories explicitly. Note that modifying root requires sudo permissions.

6 +## Install FUSE

7 -```sh

8 -# make the directories

9 -sudo mkdir /ipfs

10 -sudo mkdir /ipns

11 -

12 -# chown them so ipfs can use them without root permissions

13 -sudo chown <username> /ipfs

14 -sudo chown <username> /ipns

15 -```

8 +You will need to install and configure fuse before you can mount IPFS

17 -Depending on whether you are using OSX or Linux, follow the proceeding instructions.

10 +#### Linux

19 -## Mac OSX -- OSXFUSE

12 +Note: while this guide should work for most distributions, you may need to refer

13 +to your distribution manual to get things working.

21 -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.

22 -

23 -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:

15 +Install `fuse` with your favorite package manager:

16 +```

17 +sudo apt-get install fuse

18 +```

20 +Add the user which will be running IPFS daemon to the `fuse` group:

21 ```sh

26 -go get github.com/jbenet/go-fuse-version/fuse-version

22 +sudo usermod -a -G fuse <username>

23 ```

29 -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!

25 +Restart user session, if active, for the change to apply, either by restarting

26 +ssh connection or by re-logging to the system.

31 -## Linux

32 -

33 -Install `fuse` with your favorite package manager:

28 +#### Mac OSX -- OSXFUSE

35 -```

36 -sudo apt-get install fuse

37 -```

30 +It has been discovered that versions of `osxfuse` prior to `2.7.0` will cause a

31 +kernel panic. For everyone's sake, please upgrade (latest at time of writing is

32 +`2.7.4`). The installer can be found at https://osxfuse.github.io/. There is

33 +also a homebrew formula (`brew install osxfuse`) but users report best results

34 +installing from the official OSXFUSE installer package.

39 -Then change permissions on the fuse config:

36 +Note that `ipfs` attempts an automatic version check on `osxfuse` to prevent you

37 +from shooting yourself in the foot if you have pre `2.7.0`. Since checking the

38 +OSXFUSE version [is more complicated than it should be], running `ipfs mount`

39 +may require you to install another binary:

41 ```sh

42 -sudo chown <username>:<groupname> /etc/fuse.conf

42 +go get github.com/jbenet/go-fuse-version/fuse-version

43 ```

45 -You may also have to change `/dev/fuse`:

45 +If you run into any problems installing FUSE or mounting IPFS, hop on IRC and

46 +speak with us, or if you figure something new out, please add to this document!

47 -```sh

48 -sudo chown <username>:<groupname> /dev/fuse

49 -```

48 +## Prepare mountpoints

51 -NOTE: `<groupname>` will usually be `fuse`. Typically, you add the authorized users to the `fuse` group:

50 +By default ipfs uses `/ipfs` and `/ipns` directories for mounting, this can be

51 +changed in config. You will have to create the `/ipfs` and `/ipns` directories

52 +explicitly. Note that modifying root requires sudo permissions.

54 ```sh

54 -sudo usermod -a -G fuse <username>

55 +# make the directories

56 +sudo mkdir /ipfs

57 +sudo mkdir /ipns

58 +

59 +# chown them so ipfs can use them without root permissions

60 +sudo chown <username> /ipfs

61 +sudo chown <username> /ipns

62 ```

57 -## Mounting IPFS

64 +Depending on whether you are using OSX or Linux, follow the proceeding instructions.

59 -Once FUSE and the mountpoints have been created, issue the following command:

66 +## Mounting IPFS

68 ```sh

69 ipfs daemon --mount

70 ```

65 -If you wish to allow other users to use the mount points, edit /etc/fuse.conf to enable non-root users, i.e.:

66 -

72 +If you wish to allow other users to use the mount points, edit `/etc/fuse.conf`

73 +to enable non-root users, i.e.:

74 ```sh

75 # /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

82 user_allow_other

83 ```

78 -and use the following:

79 -

85 +Next set `Mounts.FuseAllowOther` config option to `true`:

86 ```sh

87 ipfs config --json Mounts.FuseAllowOther true

88 ipfs daemon --mount

@@ -84,40 +90,45 @@ ipfs daemon --mount

91 ## Troubleshooting

87 -### Getting `Permission denied` or `fusermount: user has no write access to mountpoint` error in Linux

93 +#### `Permission denied` or `fusermount: user has no write access to mountpoint` error in Linux

95 Verify that the config file can be read by your user:

96 ```sh

97 sudo ls -l /etc/fuse.conf

98 -rw-r----- 1 root fuse 216 Jan 2 2013 /etc/fuse.conf

99 ```

94 -In most distributions group named `fuse` will be created during installation. You can check with:

100 +In most distributions group named `fuse` is be created during fuse installation.

101 +You can check this with:

102

103 ```sh

104 sudo grep -q fuse /etc/group && echo fuse_group_present || echo fuse_group_missing

105 ```

106

100 -If group is present, just add your regular user to the `fuse` group:

107 +If the group is present, just add your regular user to the `fuse` group:

108 ```sh

109 sudo usermod -G fuse -a <username>

110 ```

111

105 -If not, create `fuse` group (add your regular user to it) and set necessary permissions, for example:

112 +If the group didn't exist, create `fuse` group (add your regular user to it) and

113 +set necessary permissions, for example:

114 ```sh

115 sudo chgrp fuse /etc/fuse.conf

116 sudo chmod g+r /etc/fuse.conf

109 -sudo chgrp fuse /ipfs /ipns

110 -sudo chmod g+rw /ipfs /ipns

117 ```

118 +<!--

119 +TODO: udev rules for /dev/fuse?

120 +-->

121

113 -Note that the use of `fuse` group is optional and may depend on your operating system.

114 -It is okay to use a different group as long as proper permissions are set for user running `ipfs mount` command.

122 +Note that the use of `fuse` group is optional and may depend on your operating

123 +system. It is okay to use a different group as long as proper permissions are

124 +set for user running `ipfs mount` command.

125

116 -### Mount command crashes and mountpoint gets stuck

126 +#### Mount command crashes and mountpoint gets stuck

127

128 ```

129 sudo umount /ipfs

130 sudo umount /ipns

131 ```

132

123 -If you manage to mount on other systems (or followed an alternative path to one above), please contribute to these docs :D

133 +If you manage to mount on other systems (or followed an alternative path to one

134 +above), please contribute to these docs :D

docs/github-issue-guide.md

+18 -10

@@ -1,15 +1,21 @@

1 # How to file a GitHub Issue

3 -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.

3 +We use GitHub Issues to log all of our todos and tasks. Here is

4 +[a good guide](https://guides.github.com/features/issues/) for them if you are

5 +unfamiliar.

5 -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:

7 +When logging an issue with go-ipfs, it would be useful if you specified the

8 +below information, if possible. This will help us triage the issues faster.

9 +Please title your issues with the type. For instance:

11 - "bug: Cannot add file with `ipfs add`"

12 - "question: How do I use `ipfs block <hash>`?"

10 -Putting the command in backticks helps us parse the natural language description, and is generally suggested.

14 +Putting the command in backticks helps us parse the natural language description,

15 +and is generally suggested.

12 -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.

17 +This is a _living guide_. If you see anything that should be here and isn't, or

18 +have ideas on improvement, please open a "meta" issue.

20 ### Type

@@ -33,7 +39,7 @@ Your platform.

40 ### Processor

36 -Your processor.

42 +Your processor architecture.

44 - "x86"

45 - "amd64"

@@ -72,8 +78,10 @@ What your issue refers to. Multiple items are OK.

79 ### Priority

75 -- "P0 - Operations on Fire (critical bug affecting release)"

76 -- "P1 - Operations Foobar (critical bug affecting master)"

77 -- "P2 - Operations Not Functioning"

78 -- "P3 - Operations Sort of Functioning"

79 -- "P4 - Operations Functioning"

81 +- Critical - System crash, application panic.

82 +- High - The main functionality of the application does not work, API breakage,

83 + repo format breakage, etc.

84 +- Medium - A non-essential functionality does not work, performance issues, etc.

85 +- Low - An optional functionality does not work.

86 +- Very Low - Translation or documentation mistake. Something that really does

87 + not matter much but should be noticed for a future release.

docs/implement-api-bindings.md

+56 -26

@@ -1,6 +1,7 @@

1 # IPFS API Implementation Doc

3 -This short document aims to give a quick guide to anyone implementing API bindings for IPFS implementations-- in particular go-ipfs.

3 +This short document aims to give a quick guide to anyone implementing API

4 +bindings for IPFS implementations-- in particular go-ipfs.

6 Sections:

7 - IPFS Types

@@ -10,71 +11,98 @@ Sections:

12 ## IPFS Types

13 -IPFS uses a set of type value that is useful to enumerate up front:

14 +IPFS uses a set of value type that is useful to enumerate up front:

15 -- `<ipfs-path>` is unix-style path, beginning with `/ipfs/<hash>/...` or `/ipns/<hash>/...` or `/ipns/<domain>/...`.

16 -- `<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).

16 +- `<ipfs-path>` is unix-style path, beginning with `/ipfs/<cid>/...` or

17 + `/ipns/<hash>/...` or `/ipns/<domain>/...`.

18 +- `<hash>` is a base58 encoded [multihash](https://github.com/multiformats/multihash)

19 +- `cid` is a [multibase](https://github.com/multiformats/multibase) encoded

20 + [CID](https://github.com/ipld/cid) - a self-describing content-addressing identifier

18 -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.)

22 +A note on streams: IPFS is a streaming protocol. Everything about it can be

23 +streamed. When importing files, API requests should aim to stream the data in,

24 +and handle back-pressure correctly, so that the IPFS node can handle it

25 +sequentially without too much memory pressure. (If using HTTP, this is typically

26 +handled for you by writes to the request body blocking.)

28 ## API Transports

22 -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).

30 +Like with everything else, IPFS aims to be flexible regarding the API transports.

31 +Currently, the [go-ipfs](https://github.com/ipfs/go-ipfs) implementation supports

32 +both an in-process API and an HTTP api. More can be added easily, by mapping the

33 +API functions over a transport. (This is similar to how gRPC is also _mapped on

34 +top of transports_, like HTTP).

24 -Mapping to a transport involves leveraging the transport's features to express function calls. For example:

36 +Mapping to a transport involves leveraging the transport's features to express

37 +function calls. For example:

26 -### CLI API Transport

39 +#### CLI API Transport

41 In the commandline, IPFS uses a traditional flag and arg-based mapping, where:

42 - the first arguments selects the command, as in git - e.g. `ipfs object get`

43 - the flags specify options - e.g. `--enc=protobuf -q`

31 -- the rest are positional arguments - e.g. `ipfs object patch <hash1> add-link foo <hash2>`

44 +- the rest are positional arguments - e.g.

45 + `ipfs object patch <hash1> add-linkfoo <hash2>`

46 - files are specified by filename, or through stdin

34 -(NOTE: When go-ipfs runs the daemon, the CLI API is actually converted to HTTP calls. otherwise, they execute in the same process)

48 +(NOTE: When go-ipfs runs the daemon, the CLI API is actually converted to HTTP

49 +calls. otherwise, they execute in the same process)

36 -### HTTP API Transport

51 +#### HTTP API Transport

53 In HTTP, our API layering uses a REST-like mapping, where:

54 - the URL path selects the command - e.g `/object/get`

55 - the URL query string implements option arguments - e.g. `&enc=protobuf&q=true`

41 -- the URL query also implements positional arguments - e.g. `&arg=<hash1>&arg=add-link&arg=foo&arg=<hash2>`

56 +- the URL query also implements positional arguments - e.g.

57 + `&arg=<hash1>&arg=add-link&arg=foo&arg=<hash2>`

58 - the request body streams file data - reads files or stdin

59 - multiple streams are muxed with multipart (todo: add tar stream support)

62 ## API Commands

48 -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!**

49 -

50 -(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.)

64 +There is a "standard IPFS API" which is currently defined as "all the commands

65 +exposed by the go-ipfs implementation". There are auto-generated [API Docs](https://ipfs.io/docs/api/).

66 +You can Also see [a listing here](https://git.io/v5KG1), or get a list of

67 +commands by running `ipfs commands` locally.

69 ## Implementing bindings for the HTTP API

71 As mentioned above, the API commands map to HTTP with:

72 - the URL path selects the command - e.g `/object/get`

73 - the URL query string implements option arguments - e.g. `&enc=protobuf&q=true`

57 -- the URL query also implements positional arguments - e.g. `&arg=<hash1>&arg=add-link&arg=foo&arg=<hash2>`

74 +- the URL query also implements positional arguments - e.g.

75 + `&arg=<hash1>&arg=add-link&arg=foo&arg=<hash2>`

76 - the request body streams file data - reads files or stdin

77 - multiple streams are muxed with multipart (todo: add tar stream support)

79 To date, we have two different HTTP API clients:

63 -- [node-ipfs-api](https://github.com/ipfs/node-ipfs-api) - simple javascript wrapper -- best to look at

64 -- [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)

81 +- [js-ipfs-api](https://github.com/ipfs/js-ipfs-api) - simple javascript

82 + wrapper -- best to look at

83 +- [go-ipfs/commands/http](https://git.io/v5KnB) -

84 + generalized transport based on the [command definitions](https://git.io/v5KnE)

66 -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.

86 +The Go implementation is good to answer harder questions, like how is multipart

87 +handled, or what headers should be set in edge conditions. But the javascript

88 +implementation is very concise, and easy to follow.

68 -### Anatomy of node-ipfs-api

90 +#### Anatomy of node-ipfs-api

92 Currently, node-ipfs-api has three main files

71 -- [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.

72 -- [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.

73 -- [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

93 +- [src/index.js](https://git.io/v5Kn2) defines the functions clients of the API

94 + module will use. uses `RequestAPI`, and translates function call parameters to

95 + the API almost directly.

96 +- [src/get-files-stream.js](https://git.io/v5Knr) implements the hardest part:

97 + file streaming. This one uses multipart.

98 +- [src/request-api.js](https://git.io/v5KnP) generic function call to perform

99 + the actual HTTP requests

100

75 -### Note on multipart + inspecting requests

101 +## Note on multipart + inspecting requests

102

77 -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`):

103 +Despite all the generalization spoken about above, the IPFS API is actually very

104 +simple. You can inspect all the requests made with `nc` and the `--api` option

105 +(as of [this PR](https://github.com/ipfs/go-ipfs/pull/1598), or `0.3.8`):

106

107 ```

108 > nc -l 5002 &

@@ -89,7 +117,9 @@ Accept-Encoding: gzip

117

118 ```

119

92 -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:

120 +The only hard part is getting the file streaming right. It is (now) fairly easy

121 +to stream files to go-ipfs using multipart. Basically, we end up with HTTP

122 +requests like this:

123

124 ```

125 > nc -l 5002 &

docs/openbsd.md

+2 -1

@@ -20,7 +20,8 @@ $ export PATH="$PATH:$GOPATH/bin"

21 ## Build

23 -The `install_unsupported` target works nicely for openbsd. This will install `gx`, `gx-go` and run `go install -tags nofuse ./cmd/ipfs`.

23 +The `install_unsupported` target works nicely for openbsd. This will install

24 +`gx`, `gx-go` and run `go install -tags nofuse ./cmd/ipfs`.

26 ```

27 $ go get -v -u -d github.com/ipfs/go-ipfs