Upspin configuration: The config file
Every interaction with Upspin requires knowledge about the user: some or all of
the user’s Upspin name, directory server, key server, security keys, and so on.
This information is described by a configuration that is by default stored in
a config file stored in
The config file is short but its contents mediate all interactions with Upspin,
and although a user’s config file is initially created by the
command, it is sometimes necessary to adjust the configuration by editing the
Also, for experts it is common to have multiple config files available that
describe different configurations used for administration or debugging.
The config file is therefore important enough to deserve a discussion about its
That is the purpose of this document.
A config file is a plain text file in
YAML is a simple format, and the information stored in the config file is
straightforward, so the result is very easy to understand.
Each line of the file is blank, a comment, or a line of the format
The keys identify settings, and there several defined:
username: E-mail address of user.
packing: Algorithm to encrypt or protect data.
keyserver: Which key server to use.
dirserver: Server that holds user’s directory tree.
storeserver: Server to write new storage.
cache: Address of local cache server.
secrets: Directory holding private keys.
tlscerts: Directory holding TLS certificates.
Not all of these settings must be present.
In practice, you will likely need only
The defaults for the other settings are usually fine.
Moreover, things like server addresses are multipart but can often be
They are discussed in the next section.
Here then is what a typical config file might look like:
This should be mostly self-explanatory.
The following sections describe things in more detail.
Format of server addresses
In general a server address in a config file comprises three elements: a
transport, a network address, and a network port.
The format is like this:
with a comma separating the transport and address and a colon separating the
address and port.
In practice, though, the transport and port are omitted because the default
remote, defines a service provided across a network connection,
and the default port, 443, is the standard port for encrypted (TLS)
communications, as used by the HTTPS protocol.
Thus the server specification above can be shortened to
remote, the default, the only other transports are
which defines a service in the process as the client and is typically used only
for debugging, and
unassigned, which represents a server that does not exist.
These appear in config files only rarely, and only for expert use.
This section describes the various settings available.
username setting is the e-mail address of the user and must be
packing setting names an algorithm used to encrypt or otherwise
protect the data written to Upspin during a
The default packing is
ee, which stands for end-to-end encryption and is the
safest, securest packing.
plain, which leaves the data untouched, and
plain leaves the data untouched but adds an end-to-end integrity check
that can detect tampering.
Integrity packing is used to store things like Access files, which must be readable by outside
agents such as directory servers but must also be secured.
If the packing is not set in the config file,
ee is assumed.
keyserver setting names the key server used to discover other
user’s public keys.
Almost always, this will be to the Upspin global key server,
and so if the keyserver is not named in the config file, that is the default.
dirserver setting names the directory server holding the user’s
Upspin directory tree.
It must be set.
storeserver setting names the storage server to which to write any
new data created by the user.
It must be set.
cache setting names a (typically local) cache server that speeds up
interactions with Upspin by caching directories and storage blocks.
It is usually run as a service on the local machine at some convenient address
If the cache is not set by the config file, none is used.
For more information about the cache server, run
go doc upspin.io/cmd/cacheserver
secrets setting identifies a directory in which the user’s public
and private keys are stored.
If not set, the keys are assumed to live in the directory
the user’s home directory (on Unix,
tlscerts setting identifies a directory in which to locate TLS
certificate root authorities.
If not set, the system uses the local operating system’s default set of root
authorities, which is usually a larger set than required.