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
- Variables
- func CheckGVisor(arch string, archive []byte) error
- func FetchGVisor(ctx context.Context, client *http.Client, arch string) ([]byte, error)
- func FetchGVisorArchive(ctx context.Context, client *http.Client, arch string) ([]byte, error)
- func MergeRuntimes(existing []byte) (out []byte, changed bool, err error)
- func NewListeners(before, after []string) []string
- func Remove(ctx context.Context, o RemoveOptions) (err error)
- func RemoveRuntimes(existing []byte) (out []byte, changed bool, err error)
- func RepackGVisor(archive []byte) ([]byte, error)
- func SetUnsafeMode(ctx context.Context, o SetOptions, on bool) (err error)
- func UnpackGVisor(repacked []byte, dir string) error
- type AdminAuth
- type Conn
- func (c *Conn) Close() error
- func (c *Conn) EnsureRoot(ctx context.Context, ask targethost.Asker, who string, red *redactor) error
- func (c *Conn) FindRoot(ctx context.Context) error
- func (c *Conn) ReadRoot(ctx context.Context, path string) ([]byte, error)
- func (c *Conn) Run(ctx context.Context, cmd string, stdin io.Reader, out io.Writer) (Result, error)
- func (c *Conn) RunRoot(ctx context.Context, cmd string, out io.Writer) (Result, error)
- func (c *Conn) SetSudo(ctx context.Context, pw string) error
- func (c *Conn) Stage(ctx context.Context) (string, error)
- func (c *Conn) Unstage(ctx context.Context, dir string)
- func (c *Conn) Upload(ctx context.Context, dir, name string, data []byte) error
- type Facts
- type Finding
- type Options
- type Outcome
- type PairOptions
- type PairOutcome
- type Plan
- type RemoveOptions
- type Result
- type SetOptions
Constants ¶
const ( LevelOK = "ok" LevelNote = "note" LevelStop = "stop" )
Finding levels.
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.
const DockerRepoHost = "download.docker.com"
DockerRepoHost is Docker's apt repository, which the server must reach only when setup installs Docker Engine.
const GVisorRelease = "20261102.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.
const MinSealingSystemd = 256
MinSealingSystemd is the oldest systemd that seals a credential to one user, which the runhost's schedules need for its store's key.
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 ¶
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.
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.
var ErrSudoPassword = errors.New("sudo asks for a password")
ErrSudoPassword means sudo asks for a password and none was given.
var GVisorBaseURL = "https://storage.googleapis.com/gvisor/releases/release"
GVisorBaseURL is gVisor's release bucket.
Functions ¶
func CheckGVisor ¶ added in v0.7.10
CheckGVisor checks that archive is the pinned GVisorRelease's archive for arch (uname -m), by its SHA-512.
func FetchGVisor ¶
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 FetchGVisorArchive ¶ added in v0.7.10
FetchGVisorArchive downloads gVisor's release archive for a server architecture and checks it against the pinned SHA-512 (CheckGVisor). It is the archive as gVisor publishes it, which a runhost checks again.
func MergeRuntimes ¶
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 ¶
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 ¶
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 ¶
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.
func SetUnsafeMode ¶ added in v0.7.7
func SetUnsafeMode(ctx context.Context, o SetOptions, on bool) (err error)
SetUnsafeMode turns the runhost's Unsafe Mode setting on or off, with the admin sign-in: a root-owned file outside the agentry account's home, which the service and the run keys can read and never write.
func UnpackGVisor ¶ added in v0.7.10
UnpackGVisor unpacks what RepackGVisor made into dir, which it creates: runsc and its helpers, each executable.
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.
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) 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 ¶
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) Run ¶
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 ¶
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) Stage ¶
Stage makes a private directory on the server for the files a step needs, owned by the admin account, and returns its path.
type Facts ¶
Facts are what the preflight read of a server, by key (assets/preflight.sh).
func ParseFacts ¶
ParseFacts reads the preflight's `key=value` lines; anything else is left out.
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 ¶
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 PairOptions ¶ added in v0.7.10
type PairOptions 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.
Ask targethost.Asker
// Say narrates, one line at a time.
Say func(string)
// Version is this device's CLI version.
Version string
// Owner is the account this device is signed in to, or the paired
// devices when it is signed out.
Owner runhost.Owner
// DeviceID and DeviceLabel name this device to the server.
DeviceID, DeviceLabel string
// Now is the clock, for the record's dates.
Now func() time.Time
}
PairOptions are what Pair needs.
type PairOutcome ¶ added in v0.7.10
type PairOutcome struct {
Record runhost.Record
// Bound is true when the pairing bound a runhost its devices owned to
// this device's account.
Bound bool
}
PairOutcome is a finished pairing.
func Pair ¶ added in v0.7.10
func Pair(ctx context.Context, o PairOptions) (out *PairOutcome, err error)
Pair adds this device to a runhost set up from another: with the admin sign-in, it installs this device's run key and sealing key and nothing else. The runhost must belong to the account this device is signed in to; one its devices own is bound to that account. The server's CLI stays as it is: a device newer than it updates it after, over the run key, and an older one is told to update itself. The record it returns is not yet saved: the caller saves it.
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
// Package is the server's package manager ("apt" or "dnf"), DockerRepo
// its tree in Docker's repository, and OSRelease the release that tree
// is named by.
Package, DockerRepo, OSRelease string
}
Plan is what the preflight decided: whether setup may go on, and what the install will do about the engine.
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 SetOptions ¶ added in v0.7.7
type SetOptions 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)
}
SetOptions are what SetUnsafeMode needs.