IPFS Examples

IPFS

Dealing With Blocks

The ipfs add command will create a Merkle DAG out of the data in the files you
specify. It follows the unixfs data format when doing this. This means
that your files are broken down into blocks, and then arranged in a tree-like
structure using 'link nodes' to tie them together. A given file's 'hash' is
actually the hash of the root (uppermost) node in the DAG. For a given DAG, you
can easily view the sub-blocks under it with ipfs ls.

For example:

# ensure this file is larger than 256k
ipfs add alargefile 
ipfs ls thathash

The above command should print out something like:

ipfs@earth ~> ipfs ls qms2hjwx8qejwm4nmwu7ze6ndam2sfums3x6idwz5myzbn
qmv8ndh7ageh9b24zngaextmuhj7aiuw3scc8hkczvjkww 7866189 
qmuvjja4s4cgyqyppozttssquvgcv2n2v8mae3gnkrxmol 7866189 
qmrgjmlhlddhvxuieveuuwkeci4ygx8z7ujunikzpfzjuk 7866189 
qmrolalcquyo5vu5v8bvqmgjcpzow16wukq3s3vrll2tdk 7866189 
qmwk51jygpchgwr3srdnmhyerheqd22qw3vvyamb3emhuw 5244129

This shows all of the immediate sub-blocks of your file, as well as the
size of them and their children on the disk.

What to do with Blocks?

If you feel adventurous, you can get a lot of different information out of these
different blocks. You can use the sub-block hashes as input to ipfs cat to
see only the data in any given sub-tree (the data of that block and its
children). To see just the data of a given block and not its children, use
ipfs block get. But be careful, as ipfs block get on an intermediate block
will print out the raw binary data of its DAG structure to your screen.

ipfs block stat will tell you the exact size of a given block (without its
children), and ipfs refs will tell you all the children of that block.
Similarly, ipfs ls or ipfs object links will show you all children and
their sizes. ipfs refs is a more suitable command for scripting something
to run on each child block of a given object.

Blocks vs Objects

In IPFS, a block refers to a single unit of data, identified by its key (hash).
A block can be any sort of data, and does not necessarily have any sort of
format associated with it. An object, on the other hand, refers to a block that
follows the Merkle DAG protobuf data format. It can be parsed and manipulated
via the ipfs object command. Any given hash may represent an object or a block.

Creating a Block from scratch

Creating your own blocks is easy! Simply put your data in a file and run
ipfs block put <yourfile> on it. Or, you can pipe your filedata into
ipfs block put, like so:

$ echo "This is some data" | ipfs block put
QmfQ5QAjvg4GtA3wg3adpnDJug8ktA1BxurVqBD8rtgVjM
$ ipfs block get QmfQ5QAjvg4GtA3wg3adpnDJug8ktA1BxurVqBD8rtgVjM
This is some data

Note: When making your own block data, you won't be able to read the data with
ipfs cat. This is because you are inputting raw data without the unixfs data
format. To read raw blocks, use ipfs block get as shown in the example.

By whyrusleeping

Be the swarm(Playing With the Network)

IPFS的一切都和网络相关!其中包括一组有用的命令帮助观察网络。

查看你当前连接了哪些节点:

ipfs swarm peers

获取整个网络列表-已废弃:

ipfs diag net

手工连接到一个指定的节点. 如果下面的节点不生效, 请从 ipfs swarm peers的输出选择一个新节点.

ipfs swarm connect /ip4/104.236.176.52/tcp/4001/ipfs/QmSoLnSGccFuZQJzRadHn95W2CrSFmZuTdDWP8HXaHca9z

根据节点Hash在网络中搜索一个给定节点:

ipfs dht findpeer QmSoLnSGccFuZQJzRadHn95W2CrSFmZuTdDWP8HXaHca9z

By whyrusleeping
Translated By Asch.zhenxi

Pinning

Pinning是ipfs中一个非常重要的概念。 ipfs语意尝试让每个单独的文件看起来都像是本地的，没有"从远程服务器检索该文件给我"这个概念， ipfs cat 或者 ipfs get 确实如此，他们不管实际对象是否在本地。 虽然这很好，但有时你想控制住周围的东西。Pinning机制允许你告诉ipfs要把给定的对象永久在本地保存。 ipfs有相当积极的缓存机制，在对对象进行ipfs操作后它会将这些对象短暂的保存在本地，但这些对象也可能会频繁地被ipfs进行垃圾回收。为了防止垃圾回收仅需要将你关心的内容pin住。 通过 ipfs add 添加的对象默认是被递归pin住的。

echo "ipfs rocks" > foo
ipfs add foo
ipfs pin ls --type=all
ipfs pin rm <foo hash>
ipfs pin rm -r <foo hash>
ipfs pin ls --type=all

你可能注意到了, 第一次执行的 ipfs pin rm 命令没有生效（译者注：我这里返回结果和-r一致，都是unpined成功，但ipfs repo gc后确实没有回收相关内容）,它应该对你发出了警告，给出的hash值已经被“递归地pin住了”。ipfs有三种pin类型

• direct pins 仅仅pin住一个和其它区块没有关联的独立block
• recursive pins pin住给出的block以及递归pin住它的所有children
• indirect pins recursive pin的children，不是直接被pin住的，是被递归pin住的

一个pin住的对象是不能被进行垃圾回收的, 如果你不相信可以试试:

ipfs add foo
ipfs repo gc
ipfs cat <foo hash>

But if foo were to somehow become unpinned...

ipfs pin rm -r <foo hash>
ipfs repo gc
ipfs cat <foo hash>

By whyrusleeping
Translated By Asch.zhenxi

Snapshots

Lets take a quick look at how ipfs can be used to take basic snapshots.

Save your directory:

$ ipfs add -r ~/code/myproject

Note the hash:

$ echo $hash `date` >> snapshots

Or all at once:

$ echo `ipfs add -q -r ~/code/myproject | tail -n1` `date` >> snapshots

(Note: the -q makes the output only contain the hashes, piping through
tail -n1 ensures only the hash of the top folder is output.)

Make sure to have the placeholders for the mount points:

$ sudo mkdir /ipfs /ipns
$ sudo chown `whoami` /ipfs /ipns

You will need to have Fuse installed on your machine in order to be able to mount directories from the ipfs. You can find instructions of how to install Fuse in the go-ipfs docs

View the snapshots live:

$ ipfs mount
$ ls /ipfs/$hash/
# can also
$ cd /ipfs/$hash/
$ ls

Through the fuse interface, youll be able to access your files exactly as
they were when you took the snapshot.

By whyrusleeping
Translated By Asch.zhenxi

The Inter-Planetary Naming System

ipns is a way to add a small amount of mutability to the permanent immutability
that is ipfs. It allows you to store a reference to an ipfs hash under the
namespace of your peerID ( the hash of your public key ). The commands to set it up
are quite simple.

First, you'll need some content to publish:

$ echo 'Let us have some mutable fun!' | ipfs add

Note the hash that was printed out, and use it here to publish it to the network:

$ ipfs name publish <that hash>
Published to <your peer ID>: <that hash>

Now, to test that it worked, you could try a couple of different things:

$ ipfs name resolve <your peer ID>
<that hash>

If you ran that on the same machine, it should return instantly, as you have
cached the entry locally; give it a shot on another computer running ipfs.

Another thing to try is viewing it on a gateway:

https://ipfs.io/ipns/<your peer ID>

So, now comes the fun part: Lets change things.

$ echo 'Look! Things have changed!' | ipfs add

Next, take the hash from there and...

$ ipfs name publish <the new hash>
Published to <your peer ID>: <the new hash>

Voila! Now, if you resolve that entry again, you'll see your new object.

Congratulations! You just successfully published and resolved an ipns entry!
Note that updating an ipns entry can "break links" because anything referencing an ipns
entry might no longer point to the content it expected. There is no way around
this ( you know, mutability ), therefore, ipns links should be used carefully if
you want to ensure permanence. In the future, we may have ipns entries work as
a git commit chain, with each successive entry pointing back in time to other
values.

By whyrusleeping

Bootstrap

The IPFS bootstrap list is a list of peers with which the IPFS daemon learns about other peers on the network. IPFS comes with a default list of trusted peers, but you are free to modify the list to suit your needs. One popular use for a custom bootstrap list is to create a personal IPFS network.

First, let's list your node's bootstrap list:

> ipfs bootstrap list
/ip4/104.131.131.82/tcp/4001/ipfs/QmaCpDMGvV2BGHeYERUEnRQAwe3N8SzbUtfsmvsqQLuvuJ
/ip4/104.236.151.122/tcp/4001/ipfs/QmSoLju6m7xTh3DuokvT3886QRYqxAzb1kShaanJgW36yx
/ip4/104.236.176.52/tcp/4001/ipfs/QmSoLnSGccFuZQJzRadHn95W2CrSFmZuTdDWP8HXaHca9z
/ip4/104.236.179.241/tcp/4001/ipfs/QmSoLpPVmHKQ4XTPdz8tjDFgdeRFkpV8JgYq8JVJ69RrZm
/ip4/104.236.76.40/tcp/4001/ipfs/QmSoLV4Bbm51jM9C4gDYZQ9Cy3U6aXMJDAbzgu2fzaDs64
/ip4/128.199.219.111/tcp/4001/ipfs/QmSoLSafTMBsPKadTEgaXctDQVcqN88CNLHXMkTNwMKPnu
/ip4/162.243.248.213/tcp/4001/ipfs/QmSoLueR4xBeUbY9WZ9xGUUxunbKWcrNFTDAadQJmocnWm
/ip4/178.62.158.247/tcp/4001/ipfs/QmSoLer265NRgSp2LA3dPaeykiS1J6DifTC88f5uVQKNAd
/ip4/178.62.61.185/tcp/4001/ipfs/QmSoLMeWqB7YGVLJN3pNLQpmmEk35v6wYtsMGLzSr5QBU3

The lines listed above are the addresses of the default IPFS bootstrap nodes -- they are run by the IPFS development team. The addresses listed are fully resolved and specified in multiaddr format, which makes every protocol explicit. This way, your node knows exactly where to reach the bootstrap nodes -- the location is unambiguous.

Don't change this list unless you understand what it means to do so. Bootstrapping is an important security point of failure in distributed systems: malicious bootstrap peers could only introduce you to other malicious peers. It is recommended to keep the default list provided by the IPFS dev team, or -- in the case of setting up private networks -- a list of nodes you control. Don't add peers to this list that you don't trust.

Here we add a new peer to the bootstrap list:

> ipfs bootstrap add /ip4/25.196.147.100/tcp/4001/ipfs/QmaMqSwWShsPg2RbredZtoneFjXhim7AQkqbLxib45Lx4S

Here we remove a node from the bootstrap list:

> ipfs bootstrap rm /ip4/128.199.219.111/tcp/4001/ipfs/QmSoLSafTMBsPKadTEgaXctDQVcqN88CNLHXMkTNwMKPnu

Let's say we want to create a backup of our new bootstrap list. We can easily do this by redirecting stdout of ipfs bootstrap list to a file:

> ipfs bootstrap list >save

If we ever want to start from scratch, we can delete the entire bootstrap list at once:

> ipfs bootstrap rm --all

With an empty list, we can restore the default bootstrap list:

> ipfs bootstrap add --default

Remove the entire bootstrap list again, and restore our saved one by piping the contents of the saved file to ipfs bootstrap add:

> ipfs bootstrap rm --all
> cat save | ipfs bootstrap add

By jbenet and insanity54

Configuring your node(The ipfs Config File)

ipfs is configured through a json formatted text file, located by default at
~/.ipfs/config.

Addresses

The config file stores a few different address types, all of which use the
multiaddr addressing format. Lets go over what each address type means.

"Addresses": {
    "Swarm": [
      "/ip4/0.0.0.0/tcp/4001"
    ],
    "API": "/ip4/127.0.0.1/tcp/5001",
    "Gateway": "/ip4/127.0.0.1/tcp/8080"
  }

Swarm

Swarm addresses are addresses that the local daemon will listen on for
connections from other ipfs peers. You should try to ensure that these
addresses can be dialed from a separate computer and that there are no
firewalls blocking the ports you specify.

API

The API address is the address that the daemon will serve the http API from.
This API is used to control the daemon through the command line, or simply
via curl if youre feeling adventurous. You should ensure that this address
is not dialable from outside of your machine, or other potentially malicious
parties may be able to send commands to your ipfs daemon.

Gateway

The Gateway address is the address that the daemon will serve the gateway
interface from. The gateway may be used to view files through ipfs, and serve
static web content. This port may or may not be dialable from outside of your
machine, thats entirely up to you. The gateway address is optional, if you
leave it blank, the gateway server will not start.

Mounts

The mounts config values specifies the default mountpoints for the ipfs and
ipns virtual filesystems, if no other directories are specified by the
ipfs mount command. These folders should exist, and have permissions for your
user to be able to mount to them via fuse.

Bootstrap

The Bootstrap config array specifies the list of ipfs peers that your daemon
will connect to on startup. The default values for this are the 'ipfs solarnet'
nodes, which are a set of VPS servers distributed around the country.

By whyrusleeping

Playing Videos

ipfs can be used to store and play videos. Suppose we add a video:

ipfs add -q sintel.mp4 | tail -n1

Take the resulting hash, You can view it a couple different ways:

On the command line:

ipfs cat $vidhash | mplayer -vo xv -

Via local gateway:

mplayer http://localhost:8080/ipfs/$vidhash
# or open it up in a tab in chrome (or firefox)
chromium http://localhost:8080/ipfs/$vidhash

(Note: the gateway method works with most video players and browsers)

By whyrusleeping

Graphing Objects

When using ipfs for storing files, or writing more complex datastructures,
it is often very useful to visualize the merkledag being created. For this,
I wrote a simple tool called graphmd (graph merkle dag).

graphmd is a very short shell script (source). It uses the
ipfs refs --format flag to produce dot output.

Install graphmd

graphmd will be in its own repo soon, but for now you can install it with:

ipfs cat Qmcd7Sebd46vxDWjbUERK8w82zp8sgWTtHT5c93kzr2v3M  >/usr/local/bin/graphmd
chmod +x /usr/local/bin/graphmd

graphmd usage

> graphmd
usage: graphmd <ipfs-path>...
output merkledag links in graphviz dot
use it with dot:
  bin/graphmd QmZPAMWUfLD95GsdorXt9hH7aVrarb2SuLDMVVe6gABYmx | dot -Tsvg
  bin/graphmd QmZPAMWUfLD95GsdorXt9hH7aVrarb2SuLDMVVe6gABYmx | dot -Tpng
  bin/graphmd QmZPAMWUfLD95GsdorXt9hH7aVrarb2SuLDMVVe6gABYmx | dot -Tpdf

Example

Given this demo directory:

> tree demo
demo
├── cat.jpg
└── test
    ├── bar
    ├── baz
    │   ├── b
    │   └── f
    └── foo
2 directories, 5 files

Add the files to ipfs

> ipfs add -r demo
added QmajFHHivh25Qb2cNbnnnEeUe1gDLHX9ta7hs2XKX1vazb demo/cat.jpg
added QmTz3oc4gdpRMKP2sdGUPZTAGRngqjsi99BPoztyP53JMM demo/test/bar
added QmTz3oc4gdpRMKP2sdGUPZTAGRngqjsi99BPoztyP53JMM demo/test/baz/b
added QmYNmQKp6SuaVrpgWRsPTgCQCnpxUYGq76YEKBXuj2N4H6 demo/test/baz/f
added QmX1ebVUtfY11ZCpVmqyE5mDoN62SpLd8eLPpg5GGV1ABt demo/test/baz
added QmYNmQKp6SuaVrpgWRsPTgCQCnpxUYGq76YEKBXuj2N4H6 demo/test/foo
added QmNtpA5TBNqHrKf3cLQ1AiUKXiE4JmUodbG5gXrajg8wdv demo/test
added QmRCJXG7HSmprrYwDrK1GctXHgbV7EYpVcJPQPwevoQuqF demo

Use graphmd to generate the dot output

> graphmd QmRCJXG7HSmprrYwDrK1GctXHgbV7EYpVcJPQPwevoQuqF >graph.dot
digraph {
  graph [rankdir=LR];
  QmRCJXG7HSmprrYwDrK1GctXHgbV7EYpVcJPQPwevoQuqF [fontsize=8 shape=box];
  QmajFHHivh25Qb2cNbnnnEeUe1gDLHX9ta7hs2XKX1vazb [fontsize=8 shape=box];
  QmRCJXG7HSmprrYwDrK1GctXHgbV7EYpVcJPQPwevoQuqF -> QmajFHHivh25Qb2cNbnnnEeUe1gDLHX9ta7hs2XKX1vazb [label="cat.jpg"];
  QmRCJXG7HSmprrYwDrK1GctXHgbV7EYpVcJPQPwevoQuqF [fontsize=8 shape=box];
  QmNtpA5TBNqHrKf3cLQ1AiUKXiE4JmUodbG5gXrajg8wdv [fontsize=8 shape=box];
  QmRCJXG7HSmprrYwDrK1GctXHgbV7EYpVcJPQPwevoQuqF -> QmNtpA5TBNqHrKf3cLQ1AiUKXiE4JmUodbG5gXrajg8wdv [label="test"];
  QmNtpA5TBNqHrKf3cLQ1AiUKXiE4JmUodbG5gXrajg8wdv [fontsize=8 shape=box];
  QmTz3oc4gdpRMKP2sdGUPZTAGRngqjsi99BPoztyP53JMM [fontsize=8 shape=box];
  QmNtpA5TBNqHrKf3cLQ1AiUKXiE4JmUodbG5gXrajg8wdv -> QmTz3oc4gdpRMKP2sdGUPZTAGRngqjsi99BPoztyP53JMM [label="bar"];
  QmNtpA5TBNqHrKf3cLQ1AiUKXiE4JmUodbG5gXrajg8wdv [fontsize=8 shape=box];
  QmX1ebVUtfY11ZCpVmqyE5mDoN62SpLd8eLPpg5GGV1ABt [fontsize=8 shape=box];
  QmNtpA5TBNqHrKf3cLQ1AiUKXiE4JmUodbG5gXrajg8wdv -> QmX1ebVUtfY11ZCpVmqyE5mDoN62SpLd8eLPpg5GGV1ABt [label="baz"];
  QmX1ebVUtfY11ZCpVmqyE5mDoN62SpLd8eLPpg5GGV1ABt [fontsize=8 shape=box];
  QmTz3oc4gdpRMKP2sdGUPZTAGRngqjsi99BPoztyP53JMM [fontsize=8 shape=box];
  QmX1ebVUtfY11ZCpVmqyE5mDoN62SpLd8eLPpg5GGV1ABt -> QmTz3oc4gdpRMKP2sdGUPZTAGRngqjsi99BPoztyP53JMM [label="b"];
  QmX1ebVUtfY11ZCpVmqyE5mDoN62SpLd8eLPpg5GGV1ABt [fontsize=8 shape=box];
  QmYNmQKp6SuaVrpgWRsPTgCQCnpxUYGq76YEKBXuj2N4H6 [fontsize=8 shape=box];
  QmX1ebVUtfY11ZCpVmqyE5mDoN62SpLd8eLPpg5GGV1ABt -> QmYNmQKp6SuaVrpgWRsPTgCQCnpxUYGq76YEKBXuj2N4H6 [label="f"];
  QmNtpA5TBNqHrKf3cLQ1AiUKXiE4JmUodbG5gXrajg8wdv [fontsize=8 shape=box];
  QmYNmQKp6SuaVrpgWRsPTgCQCnpxUYGq76YEKBXuj2N4H6 [fontsize=8 shape=box];
  QmNtpA5TBNqHrKf3cLQ1AiUKXiE4JmUodbG5gXrajg8wdv -> QmYNmQKp6SuaVrpgWRsPTgCQCnpxUYGq76YEKBXuj2N4H6 [label="foo"];
}

Pipe it to dot to produce svg, pdf, png or whatever

graphmd QmRCJXG7HSmprrYwDrK1GctXHgbV7EYpVcJPQPwevoQuqF | dot -Tsvg >output/graph.svg
graphmd QmRCJXG7HSmprrYwDrK1GctXHgbV7EYpVcJPQPwevoQuqF | dot -Tpdf >output/graph.pdf
graphmd QmRCJXG7HSmprrYwDrK1GctXHgbV7EYpVcJPQPwevoQuqF | dot -Tpng >output/graph.png

Et voilà: svg, pdf, png

File blocks

graphmd is particularly useful to inspect file blocking algorithms.
For example, here is what the ipfs binary looks like with the default
semi-balanced indirect block chunking:

• dot output
• svg render
• pdf render

by Juan Benet