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 $HOME/upspin/config.

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 upspin signup command, it is sometimes necessary to adjust the configuration by editing the file manually. 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 contents. That is the purpose of this document.


A config file is a plain text file in YAML format. 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

key: value

The keys identify settings, and there several defined:

One can also specify values for flags used by various commands. The syntax is:

  flag-name: flag-value

The cacheserver and upspinfs commands honor these settings. The flags must be in the command line flag set of the command or will generate an error. These flag values will supersede the value of any flags not set to their default. Thus one can override these settings in the command line.

Not all of these settings must be present. In practice, you will likely need only username, dirserver, storeserver, and cache. The defaults for the other settings are usually fine. Moreover, things like server addresses are multipart but can often be simplified. They are discussed in the next section.

Here then is what a typical config file might look like:


cache: localhost:8888
  cachedir: /usr/augie/tmp
  cachesize: 5000000000

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 transport, 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

Other than remote, the default, the only other transports are inprocess, 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.

go doc