Upspin configuration: The config file

Introduction

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.

Format

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:

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:

username: ann@example.com

dirserver: dir.example.com
storeserver: store.example.com
cache: localhost:8888

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:

remote,dir.example.com:443

with a comma separating the transport and address and a colon separating the address and port.

In practice, though the transport and port are elided 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

dir.example.com

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.

Settings

This section describes the various settings available.

go doc upspin.io/cmd/cacheserver