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:
Out of the box all commands should work on a , but there is no reason users can’t follow along.
There are two methods, pick one, if unsure choose option 1:
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
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
If you’re a Go user and understand what this means you can install the tools to
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:
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 firstname.lastname@example.org/Public/file.txt # where email@example.com is my $HOME within the Upspin world
Also note: sharable links contain email addresses, e.g., https://firstname.lastname@example.org/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/#
Once you enter a valid email address and click Sign Up a few things will happen:
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.
Quit out of the browser and ^C (Control-C) to stop
Side note, to see “Configure your Upspin Servers” options again, open your
$HOME/upspin/config file and remove these lines:
then restart upspin-ui
For a quick one-liner on the mac:
sed -i '' -e '/^dirserver/d;/^storeserver/d' $HOME/upspin/config && upspin-ui
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 email@example.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:
firstname.lastname@example.org/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.