upbox

Documentation

Overview

Package upbox provides the Schema mechanism for declaring and creating a set of Upspin users and servers.

Schema files must be in YAML format, of this general form:

users:
- name: joe
- name: jess@example.net
  storeserver: store.upspin.io
  dirserver: dir.upspin.io
  packing: ee
  cache: true
servers:
- name: storeserver
- name: dirserver
  user: joe
- name: myserver
  importpath: github.com/user/myserver
  flags:
    debug: cockroach
keyserver: key.uspin.io
domain: example.com
dir: /path/to/upbox/state

The Users and Servers lists specify the users and servers to create within this schema.

Users

Name specifies the user name of this user. It must be non-empty. It can be a full email address, or just the user component. In the latter case, the top-level domain field must be set.

StoreServer and DirServer specify the store and directory endpoints for this user. If empty, they default to the servers "storeserver" and "dirserver", respectively. If they are of the form "$servername" then the address of the server "servername" is used.

Packing specifies the packing method for this user. If empty, it defaults to "ee".

Cache is a boolean that specifies whether to start a cacheserver for this user.

Servers

Name specifies a short name for this server. It must be non-empty. The names "keyserver", "storeserver", and "dirserver" represent useful defaults.

User specifies the user to run this server as. It can be a full email address, or just the user component. If empty, the Name of the server is combined with the Schema's Domain and a user is created with that name. In the latter cases, the top-level Domain field must be set.

ImportPath specifies the import path for this server that is built before starting the server. If empty, the server Name is appended to the string "upspin.io/cmd/".

Other top-level fields

KeyServer specifies the KeyServer that each user in the cluster should use. If it is empty, then a Server named "keyserver" must be included in the list of Servers, and the address of that server is used.

Domain specifies a domain that is appended to any user names that do not include a domain component. Domain must be specified if any domain suffixes are omitted from User Names or if a Servers is specified with an empty User field.

Default schema

If no schema is specified, the default schema is used:

users:
  - name: user
servers:
  - name: keyserver
  - name: storeserver
  - name: dirserver
domain: example.com

This creates the users user@example.com, keyserver@example.com, storeserver@example.com, and dirserver@example.com, builds and runs the servers keyserver, storeserver, and dirserver (running as their respective users), and runs "upspin shell" as user@example.com.

Generated data

A running Schema needs to store data on disk: config files, TLS certificates, and dirserver log data (if a dirserver of kind 'server' is selected). By default, these files are kept in a temporary directory that is created by the Start method and removed by the Stop method.

If the "dir" property is set, upbox will use that path to store its data and will not clean up inside Stop. Upon a restart, upbox will use whatever it finds, filling in any missing gaps in regards to the schema. If persistent storage (eg. 'disk') is used, one can resume a previously started session. An example schema for a resumable session:

dir: /tmp/upbox
users:
- name: john
servers:
- name: storeserver
  flags:
    kind: server
- name: dirserver
  flags:
    kind: server
- name: keyserver
domain: local.host

Index

• Constants
• type Schema
  • func SchemaFromFile(name string) (*Schema, error)
  • func SchemaFromYAML(doc string) (*Schema, error)
  • func (sc *Schema) Config(user string) string
  • func (sc *Schema) Start() error
  • func (sc *Schema) Stop() error
• type Server
• type User

Constants

const DefaultSchema = `
users:
  - name: user
servers:
  - name: keyserver
  - name: storeserver
  - name: dirserver
domain: example.com
`

DefaultSchema is the schema that is used if none is provided.

Types

type Schema

type Schema struct {
	Users   []*User
	Servers []*Server

	// Dir specifies the directory in which to store the config files and keys.
	// Any data that may already be present there will be reused. This allows
	// restoring previous sessions. If unspecified, a temporary directory
	// will be used.
	Dir string

	// Domain specifies the default domain of any user names that do not
	// include a domain component.
	Domain string

	// KeyServer specifies the KeyServer used by each user in the cluster.
	KeyServer string

	// LogLevel specifies the logging level that each server should use.
	LogLevel string
	// contains filtered or unexported fields
}

Schema defines a set of Upspin Users and Servers.

func SchemaFromFile

func SchemaFromFile(name string) (*Schema, error)

SchemaFromFile parses a Schema from the named file. If no name is provided the DefaultSchema is used.

func SchemaFromYAML

func SchemaFromYAML(doc string) (*Schema, error)

SchemaFromYAML parses a Schema from the given YAML document.

func (*Schema) Config

func (sc *Schema) Config(user string) string

Config returns the path to the config for the given user.

func (*Schema) Start

func (sc *Schema) Start() error

Start sets up the Users and Servers specified by the Schema.

func (*Schema) Stop

func (sc *Schema) Stop() error

Stop terminates any running server processes and deletes all temporary files.

type Server

type Server struct {
	// Name specifies a short name for this server.
	Name string

	// User specifies the user to run this server as.
	User string

	// ImportPath specifies the import path for this server
	// that is built before starting the server.
	// If empty, the server Name is appended to the string
	// "upspin.io/cmd/".
	ImportPath string

	// Flags specifies command-line flags to supply to this server.
	Flags map[string]string
	// contains filtered or unexported fields
}

Server defines an Upspin server to be created and used within a schema.

type User

type User struct {
	// Name specifies the user name of this user.
	Name string

	// StoreServer and DirServer specify the store and directory endpoints
	// for this user.
	StoreServer string
	DirServer   string

	// Packing specifies the packing method for this user.
	Packing string

	// Cache specifies whether to run a cacheserver for this user.
	Cache bool
	// contains filtered or unexported fields
}

User defines an Upspin user to be created and used within a schema.