setup

package
v0.7.4 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Nov 2, 2026 License: MIT Imports: 33 Imported by: 0

Documentation

Overview

Package setup makes a Linux server the person owns into a remote runhost, over SSH, and takes it away again. The admin sign-in is used for this alone and kept nowhere. Setup reads the server first and changes nothing until the person has seen what it found; then it installs, idempotently, a dedicated account, Docker Engine where there is none, gVisor's runsc registered for every container, this device's own CLI release, and the runhost's service; pairs this device with a run key held to the service by a forced command; and checks the result over that run key alone.

Index

Constants

View Source
const (
	LevelOK   = "ok"
	LevelNote = "note"
	LevelStop = "stop"
)

Finding levels.

View Source
const (
	MinDiskKB = 20 * 1000 * 1000
	MinMemKB  = 2 * 1000 * 1000
)

MinDiskKB and MinMemKB are the free disk under /var/lib and the available memory a runhost needs: Docker's images and a run's containers.

View Source
const DockerRepoHost = "download.docker.com"

DockerRepoHost is Docker's apt repository, which the server must reach only when setup installs Docker Engine.

View Source
const GVisorRelease = "20261026.0"

GVisorRelease is the gVisor release a runhost runs, the one Agentry's own runhosts pin. Each architecture's archive is pinned by its SHA-512, so a changed archive is refused whatever the download says of itself.

View Source
const MinSystemd = 249

MinSystemd is the oldest systemd setup works with: a system account with linger and a user service are all it asks of it.

Variables

View Source
var ErrNoRoot = errors.New("the admin account is not root and cannot use sudo: sign in as root, or as an account in the sudo group")

ErrNoRoot means the account is neither root nor able to sudo.

View Source
var ErrNotARelease = errors.New("this CLI is not a signed release, so there is no build of its version to put on a server: set up a runhost with a released CLI")

ErrNotARelease means this CLI is not a release, so there is no signed build of it to put on the server.

View Source
var ErrSudoPassword = errors.New("sudo asks for a password")

ErrSudoPassword means sudo asks for a password and none was given.

View Source
var GVisorBaseURL = "https://storage.googleapis.com/gvisor/releases/release"

GVisorBaseURL is gVisor's release bucket.

Functions

func FetchGVisor

func FetchGVisor(ctx context.Context, client *http.Client, arch string) ([]byte, error)

FetchGVisor downloads gVisor's release archive for a server architecture (uname -m: x86_64, aarch64), checks it against the pinned SHA-512, and repacks runsc and its helper binaries as a gzip tar, which every server can unpack. The containerd shim is left out: Docker runs runsc directly.

func MergeRuntimes

func MergeRuntimes(existing []byte) (out []byte, changed bool, err error)

MergeRuntimes adds gVisor's two runtimes to the daemon's configuration. changed is false when they are already there as setup makes them, so the daemon is not reloaded for nothing. A runtime of either name that the person registered otherwise is refused, rather than taken over.

func NewListeners

func NewListeners(before, after []string) []string

NewListeners are the listening sockets in after that were not in before.

func Remove

func Remove(ctx context.Context, o RemoveOptions) (err error)

Remove takes the runhost away from the server. The host key must still be the one pinned at setup.

func RemoveRuntimes

func RemoveRuntimes(existing []byte) (out []byte, changed bool, err error)

RemoveRuntimes takes gVisor's two runtimes back out, when they are the ones setup made. changed is false when there is nothing to take out.

func RepackGVisor

func RepackGVisor(archive []byte) ([]byte, error)

RepackGVisor turns a checked gvisor.tar.zstd into the gzip tar the server unpacks: regular files and directories only, runsc at the top and the helpers under gvisor-bin/, no path that climbs out.

Types

type AdminAuth

type AdminAuth struct {
	// Key is a private key's bytes, and Passphrase its passphrase, if any.
	Key        []byte
	Passphrase string
	// Agent signs in with the SSH agent at SSH_AUTH_SOCK.
	Agent bool
	// Password signs in with the account's password.
	Password string
	// Sudo is the account's sudo password, when sudo asks for one; Ask
	// supplies it when it is needed and not given.
	Sudo string
}

AdminAuth is the admin sign-in: the server account setup signs in as, root or one that can sudo. It lives in memory for one command and is never written anywhere, on either machine.

func (AdminAuth) Values

func (a AdminAuth) Values() []string

Values are the sign-in's secrets, which no narration may carry.

type Conn

type Conn struct {
	// contains filtered or unexported fields
}

Conn is the admin connection to a server being set up.

func Dial

func Dial(ctx context.Context, addr netip.Addr, port int, user string, hostKey ssh.PublicKey, auth AdminAuth) (*Conn, error)

Dial signs in to addr:port as user with auth, holding the connection to hostKey, which the caller has already checked.

func (*Conn) Close

func (c *Conn) Close() error

Close ends the connection.

func (*Conn) EnsureRoot

func (c *Conn) EnsureRoot(ctx context.Context, ask targethost.Asker, who string, red *redactor) error

EnsureRoot is FindRoot, asking for sudo's password at a terminal when it is needed and was not given; a password typed there joins red's secrets.

func (*Conn) FindRoot

func (c *Conn) FindRoot(ctx context.Context) error

FindRoot learns how the root steps run: as root itself, through sudo with no password, or through sudo with the sudo password (or, when sudo takes it, the sign-in password).

func (*Conn) ReadRoot

func (c *Conn) ReadRoot(ctx context.Context, path string) ([]byte, error)

ReadRoot reads a file as root; a missing file is nil and no error.

func (*Conn) Run

func (c *Conn) Run(ctx context.Context, cmd string, stdin io.Reader, out io.Writer) (Result, error)

Run runs cmd as the admin account, with stdin as its input. out, when not nil, also receives the command's standard output as it comes.

func (*Conn) RunRoot

func (c *Conn) RunRoot(ctx context.Context, cmd string, out io.Writer) (Result, error)

RunRoot runs the shell command cmd as root. Under sudo with a password, the password is sudo's first line of input and nothing else is: a root step that needs input reads it from a staged file.

func (*Conn) SetSudo

func (c *Conn) SetSudo(ctx context.Context, pw string) error

SetSudo gives the sudo password after FindRoot asked for it, and checks it.

func (*Conn) Stage

func (c *Conn) Stage(ctx context.Context) (string, error)

Stage makes a private directory on the server for the files a step needs, owned by the admin account, and returns its path.

func (*Conn) Unstage

func (c *Conn) Unstage(ctx context.Context, dir string)

Unstage removes the staging directory, as root, since root steps may have left files in it.

func (*Conn) Upload

func (c *Conn) Upload(ctx context.Context, dir, name string, data []byte) error

Upload writes data to the file name in the staging directory dir, readable by its owner alone.

type Facts

type Facts map[string]string

Facts are what the preflight read of a server, by key (assets/preflight.sh).

func ParseFacts

func ParseFacts(out []byte) Facts

ParseFacts reads the preflight's `key=value` lines; anything else is left out.

func (Facts) Arch

func (f Facts) Arch() string

Arch is the server's architecture in Go's words (amd64, arm64), "" for one a runhost does not run on.

func (Facts) Listening

func (f Facts) Listening() []string

Listening is the set of listening sockets the preflight saw.

type Finding

type Finding struct {
	Level  string `json:"level"`
	Name   string `json:"name"`
	Detail string `json:"detail"`
}

Finding is one line of the preflight's report.

type Options

type Options struct {
	// Name is the runhost's name on this device.
	Name string
	// Answer is the server's SSH address and admin account.
	Answer targethost.Answer
	// Auth is the admin sign-in.
	Auth AdminAuth
	// KnownHosts are where the server's host key is looked up.
	KnownHosts targethost.KnownHostsFiles
	// Ask asks the person at a terminal; nil is no one to ask, so an unknown
	// host key or a missing sudo password refuses.
	Ask targethost.Asker
	// Say narrates, one line at a time.
	Say func(string)
	// Confirm is shown the preflight's plan before anything on the server
	// changes; false stops setup there. Nil goes on.
	Confirm func(Plan) (bool, error)
	// Version is this device's CLI version, which the server gets.
	Version string
	// Keys are the update-signing keys the CLI release is checked against.
	Keys *clirelease.KeySet
	// HTTP downloads the CLI release and gVisor.
	HTTP *http.Client
	// Owner is who the runhost will belong to.
	Owner runhost.Owner
	// DeviceID and DeviceLabel name this device to the server.
	DeviceID, DeviceLabel string
	// Reach are the hosts whose port 443 the server must reach: the image
	// registry and the Agentry registry.
	Reach []string

	// FetchCLI and FetchGVisor default to the real downloads; tests replace
	// them.
	FetchCLI    func(ctx context.Context, version, arch string) (*clirelease.Binary, error)
	FetchGVisor func(ctx context.Context, arch string) ([]byte, error)
	// Now is the clock, for the record's dates.
	Now func() time.Time
}

Options are what Add needs.

type Outcome

type Outcome struct {
	Record       runhost.Record
	Plan         Plan
	Restrictions []runhost.Restriction
	Status       json.RawMessage
	Doctor       runhost.Answer
}

Outcome is a finished setup.

func Add

func Add(ctx context.Context, o Options) (out *Outcome, err error)

Add sets the server up as a runhost and pairs this device with it. The record it returns is not yet saved: the caller saves it. It is returned only once the server holds this device's run key, so a record always has its keys in the keychain. No error and no narration carries a secret of the admin sign-in, a sudo password typed at the prompt included.

type Plan

type Plan struct {
	Findings []Finding
	// Supported is false when a finding stops setup.
	Supported bool
	// InstallDocker is true when there is no engine and setup installs
	// Docker Engine from Docker's repository.
	InstallDocker bool
	// Arch is the server's architecture in Go's words.
	Arch string
}

Plan is what the preflight decided: whether setup may go on, and what the install will do about the engine.

func Evaluate

func Evaluate(f Facts, reach []string) Plan

Evaluate decides, from the preflight's facts, whether setup may go on. reach names the hosts whose port 443 must answer.

type RemoveOptions

type RemoveOptions struct {
	Record runhost.Record
	Auth   AdminAuth
	// Answer names the admin account; its host and port are the record's.
	Answer targethost.Answer
	Ask    targethost.Asker
	Say    func(string)
	// RemoveImages and RemoveDocker take away the images runs used and,
	// when setup installed it, Docker Engine.
	RemoveImages, RemoveDocker bool
}

RemoveOptions are what Remove needs.

type Result

type Result struct {
	Stdout, Stderr []byte
	Code           int
}

Result is a command's outcome.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL