You need a central place where brig stores its metadata. This place is
called a »repository« or short »repo«. This is not the place, where your files
are stored. Those are copied (if you did setup IPFS in a normal way) to
~/.ipfs. Keep in mind that brig will copy files and thus will never
modify the original files on your hard drive.
By creating a new repository you also generate your identity, under which your buddies can later find and authenticate you. But enough of the mere theory, let’s get started:
# Create a place where we store our metadata.
# The repository is created by default in the current working directory.
# (This can be changed via `brig --repo`)
$ mkdir repo && cd repo
$ brig init ali@woods.org/desktop -w 'echo my-password'
_____ / /\ ___ / /\
/ /::\ / /::\ / /\ / /:/_
/ /:/\:\ / /:/\:\ / /:/ / /:/ /\
/ /:/~/::\ / /:/~/:/ /__/::\ / /:/_/::\
/__/:/ /:/\:| /__/:/ /:/___ \__\/\:\__ /__/:/__\/\:\
\ \:\/:/~/:/ \ \:\/:::::/ \ \:\/\ \ \:\ /~~/:/
\ \::/ /:/ \ \::/~~~~ \__\::/ \ \:\ /:/
\ \:\/:/ \ \:\ /__/:/ \ \:\/:/
\ \::/ \ \:\ \__\/ \ \::/
\__\/ \__\/ \__\/
A new file README.md was automatically added.
Use 'brig cat README.md' to view it & get started.
$ ls
config.yml gateway immutable.yml keyring
metadata README.md remotes.yml
The name you specified after the init is the name that will be shown
to other users and by which you are searchable in the network.
See Choosing and finding names for more details on the subject.
Once the init ran successfully there will be a daemon process running in
the background. Every other brig commands will communicate with it via
a local network socket. If the daemon does not run yet, it will be started for
you in the background without you noticing.
Note
If no IPFS daemon is running, brig will start one for you. If you don’t
have ipfs installed, it will even install and set it up for you. By
default, brig init will also set some default options that help brig
to run a bit smoother. If you do not want those, please add
--no-ipfs-optimization to the init command above.
You might wonder what the name you pass to init is actually for. As
previously noted, there is no real restriction for choosing a name, so all of
the following are indeed valid names:
aliali@woods.orgali@woods.org/desktopali/desktopIt’s however recommended to choose a name that is formatted like
a XMPP/Jabber-ID. Those IDs can look like plain emails, but can optionally have
a »resource« part as suffix (separated by a »/« like desktop). Choosing
such a name has two advantages:
Other peers can find you by only specifying parts of your name.
Imagine all of the Smith family members use brig, then they’d possibly those names:
dad@smith.org/desktopmom@smith.org/tabletson@smith.org/laptopWhen dad now sets up brig on his server, he can use brig net locate
-m domain 'smith.org' to get all fingerprints of all family members. Note
however that brig net locate is not secure. Its purpose is solely
discovery, but is not able to verify that the fingerprints really correspond
to the persons they claim to be. This due to the distributed nature of
brig where there is no central or federated authority that coordinate
user name registrations. So it is perfectly possible that one name can be
taken by several repositories - only the fingerprint is unique.
Later development of brig might interpret the user name and domain as
email and might use your email account for verification purposes.
Having a resource part is optional, but can help if you have several instances
of brig on your machines. i.e. one user name could be
dad@smith.org/desktop and the other dad@smith.org/server.
The following sections are not a required read. They are useful to keep in mind, but in the ideal case you’re don’t even need to think about the daemon.
As discussed before, the daemon is being started on demand in the background.
Subsequent commands will then use the daemon. For debugging purposes it can be useful
to run in the daemon in the foreground. You can do this with the brig daemon commands:
# Make sure no prior daemon is running:
$ brig daemon quit
# Start the daemon in the foreground and log to stdout:
$ brig daemon launch -s
If you want to quit the instance, either just hit CTRL-C or type brig daemon
quit into another terminal window.
Unless you pass the -s (--log-to-stdout flag) as above, all logs are
being piped to the system log. You can follow the log like this:
# Follow the actual daemon log:
$ journalctl -ft brig
This assumes you’re using a systemd-based distribution. If not, refer to
the documentation of your syslog daemon.
It can be useful to run more than one instance of the brig daemon in
parallel. Either for testing purposes or as actual production configuration. In
order for the brig client to know what daemon to talk to, you have to be
specific about the repository (--repo) path. Here is an example:
# Be explicit
$ brig --repo /tmp/ali init ali -x --ipfs-path ~/.ipfs
$ brig --repo /tmp/bob init bob -x --ipfs-path ~/.ipfs2
# Since you specified --repo we know what daemon to talk to.
# You can also set BRIG_PATH for the same effect:
$ BRIG_PATH=/tmp/ali brig ls
<file list of ali>
# Add some alias to your .bashrc to save you some typing:
$ alias brig-ali="brig --repo /tmp/ali"
$ alias brig-bob="brig --repo /tmp/bob"
# Now you can use them normally,
# e.g. by adding them as remotes each:
$ brig-ali remote add bob $(brig-bob whoami -f)
$ brig-bob remote add ali $(brig-ali whoami -f)
Note
It is possible to have several repositories per IPFS instances. Since things
might get confusing though when it comes to pinning, it is recommended to
have several IPFS daemons running in this case. This is done via the
--ipfs-port flag in the example above.
The repository on disk is not encrypted. If you plan on moving the repository
to somewhere else, e.g. by copying it onto an USB stick and physically moving
it somewhere else you should always consider to first create an encrypted
archive out of it and unpack it on the target machine. brig has a built-in
helper for this. Please refer to brig pack-repo --help and brig
unpack-repo --help.