Upspin part 2: Configuring an Upspin user
Jun 2018    |    upspin   client  


Intro

To access data within the Upspin world one does not require a directory or storage server. Think of yourself as a client, i.e., a user, that was granted access to another user’s data.

For the sake of this tutorial I’ll be hosting a publicly accessible file that any Upspin user can access. This is a great way to test if everything is setup correctly, available at:

frid.mike@gmail.com/Public/mikes_fav_book.txt

Out of the box all commands should work on a , but there is no reason users can’t follow along.


Install the Upspin tools

There are two methods, pick one, if unsure choose option 1:

1 - Download binaries directly

Download and extract the tools inside a directory listed in your system $PATH. E.g., I’ll create $HOME/upspin directory and add it to my $PATH.

The files originate from the Download Upspin page.

mkdir $HOME/upspin && cd $_
# if you don't have wget, install homebrew from https://brew.sh/ and then wget like so:
# brew install wget
wget https://upspin.io/dl/upspin.darwin_amd64.tar.gz
tar xvzf upspin.darwin_amd64.tar.gz && rm upspin.darwin_amd64.tar.gz
ls -1
# you should see at least the following:
README
cacheserver
upspin
upspin-audit
upspin-ui
upspinfs
# permanently add the upspin tools to your PATH
echo -e export PATH="$PATH:$HOME/upspin" >> ~/.bash_profile && . ~/.bash_profile
# check installation
upspin -version
# oops
-bash: upspin: command not found
# good
Build time: Jun 27 01:13:37 2018 UTC
Git hash:   1e73992b518722f8eb59d37ad70df02179063d76
2 - Use Go to pull and build

If you’re a Go user and understand what this means you can install the tools to $GOPATH/bin

go get -u upspin.io/cmd/...
# check installation
upspin -version
# oops
-bash: upspin: command not found
# good
devel
# if you check your $GOPATH/bin or $GOBIN you should at least see the following:
ls -1tr $GOPATH/bin
upspin-setupstorage
upbox
storeserver
keyserver
cacheserver
upspin
frontend
dirserver
upspin-audit
upspinfs
upspinserver

go get -u augie.upspin.io/cmd/upspin-ui
# which adds
upspin-ui

At this point, do we care about all those binaries? Nope, all we need for the next few sections are:

upspin and upspin-ui


Creating an Upspin user

To create an Upspin user you’ll need a valid email address; think of this as a user name. The email address is used one-time to verify your identity.

To reiterate, this email address will receive a total of ONE confirmation email. It cannot be used to recover your keys, and if someone hijacks your email they CANNOT gain access to your keys. As far as Upspin is concerned, once you click on the confirmation link you can abandon or delete your email account (not saying you should, just making a point).

Your email address, i.e., user name, is how the Upspin world identifies you and your files.

In my opinion the shorter the email the better. A typical command looks like this:

upspin get frid.mike@gmail.com/Public/file.txt
# where frid.mike@gmail.com is my $HOME within the Upspin world

Also note: sharable links contain email addresses, e.g., https://upspin.mfridman.com/frid.mike@gmail.com/Public

Lastly, the email address is permanently added to the keyserver log. I don’t think it’s a big deal, but this may be of importance to you.

Now let’s create a user, thankfully this process has been made easy with the upspin-ui tool. Hop over to your terminal and run:

upspin-ui
# opens a browser window at http://localhost:8000/#
upspin-ui.png

Once you enter a valid email address and click Sign Up a few things will happen:

upspin-ui-2.png
  1. a directory with 2 files is created $HOME/.ssh/fridman0101@gmail.com
    public.upspinkey
    secret.upspinkey
  2. a human-readable “secret seed” string will be displayed (see above screenshot, albeit blurred)
    Write this down and store it in a secure, private place.
    Do not share your secret key or this string with anyone.
  3. look out for a confirmation email from noreply@upspin.io. Open the email and click on the link:
    An account for “fridman0101@gmail.com” has been registered with the key server.
  4. the upspin config file is created at $HOME/upspin/config

Once you click Ok, I wrote it down you’ll be presented with an option to create servers, we’ll be skipping this step.

Creating an Upspin server will be covered in a separate post.

upspin-ui-2.png

Quit out of the browser and ^C (Control-C) to stop upspin-ui.

Side note, to see “Configure your Upspin Servers” options again, open your $HOME/upspin/config file and remove these lines:

dirserver: and storeserver:

then restart upspin-ui

For a quick one-liner on the mac:

sed -i '' -e '/^dirserver/d;/^storeserver/d' $HOME/upspin/config && upspin-ui

Testing your Upspin user

Congrats, if all went well your Upspin user should be setup. Try to read a public file I’ve setup within the Upspin world

upspin get frid.mike@gmail.com/Public/mikes_fav_book.txt
# ...

upspin get: writes to standard output the contents identified by the Upspin path

But what is an Upspin path?

From the docs: Every Upspin file name has the same basic structure. It begins with the user’s name—an email address—followed by a slash-separated Unix-like path name

Example of an Upspin path: frid.mike@gmail.com/Public/mikes_fav_book.txt, don’t get hung up on the email address portion, just make a mental conversion between your email address and $HOME, so it feels like $HOME/Public/mikes_fav_book.txt within the Upspin world.