to get started, we need to make sure ipfs has been initialized, if you havent done this yet:
ipfs init
next lets start up the ipfs daemon:
ipfs daemon
once the daemon is fully set up it will print something like "api server listening on /ip4/127.0.0.1/tcp/5001". after you see this message, youll be able to run any of the ipfs commands you want. without running the daemon, youll only be able to successfully run a smaller subset of the commands.
now that we have the daemon up, lets have some fun.
basic work with files in ipfs:
echo "welcome to ipfs!" > hello
ipfs add hello
that should have printed out something along the lines of:
added qmxzzpcazv6tw1tvicf9poare9kkb1fwmzbvamytdwvshe hello
that means that the file was successfully added into the ipfs datastore, and may be accessed through ipfs now.
to check, try:
ipfs cat qmxzzpcazv6tw1tvicf9poare9kkb1fwmzbvamytdwvshe
(note: if your files hash was different in the first step, use your hash instead of mine)
if all went well, you should see the text from your file printed out to you!
ipfs cat is a great command to quickly retrieve and view files, but if the
file you are requesting contains binary data (such as an image or movie)
ipfs get might be more appropriate:
ipfs get -o cats.png $hashofcatpic
this will create a file named 'cats.png' that contains the data from the given hash.
lets take a quick look at how ipfs can be used to keep basic backups.
save your directory:
ipfs add -r ~/code/myproject
note the hash:
echo $hash `date` >> backups
or all at once:
echo `ipfs add -q -r ~/code/myproject | tail -n1` `date` >> backups
note: the -q makes the output only contain the hashes, piping through
tail -n1 ensures only the hash of the top folder is output.
view the backups 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 backup.
ipfs can be used to store and share videos, if someone gives you the hash of a video, you can view it a couple different ways.
on the command line:
ipfs cat $vidhash | mplayer -vo xv -
via local gateway:
mplayer http://localhost:4001/ipfs/$vidhash
# or open it up in a tab in chrome (or firefox)
chromium http://localhost:4001/ipfs/$vidhash
(note: the gateway method works with most video players and browsers)
ipfs is all about networking! included are a useful set of commands to aid in observing that network.
see who youre directly connected to:
ipfs swarm peers
get a listing of the entire network:
ipfs diag net
manually connect to a specific peer:
ipfs swarm connect /ip4/104.236.176.52/tcp/4001/ipfs/qmsolnsgccfuzqjzradhn95w2crsfmzutddwp8hxahca9z
search for a given peer on the network:
ipfs dht findpeer $peerid
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. what this means, is
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 files '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
what this is showing is all of the immediate sub-blocks of your file, and the size of them and their children on disk.
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.
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 merkledag protobuf data format. it can be parsed and manipulated
via the ipfs object command. any given hash may represent an object or a block.
the merkledag structure makes it really easy to define your own datastructures on top of them. lets take a look at how that is accomplished through the cli.
the easiest way to manually create an object is by defining its structure in a json file.
for example:
{
"data": "hello world"
}
todo: im stuck here currently, this example is hard to write due to base64 encoding.
I have some problem like during I was trying to use (ipfs ls .............my-hash................). There is no result. Can you help me!