Documentation
¶
Overview ¶
Package targethost readies a run's target hosts before anything starts: a target host is a machine the person names when a run starts, as the answer to an intake question of type host, and the runner reaches it over SSH from the host link (runnerimage/hostlink), never from the agent's containers. Here the answer is read, its address resolved and checked, its host key checked against the person's known_hosts and the runner's own, and its credential taken from a flag, the keychain or a prompt. Nothing here connects to the host but to read its key.
Index ¶
- Constants
- func Algorithms(k ssh.PublicKey) string
- func BaseRef(pol *policy.Policy) (string, error)
- func CheckAddress(a netip.Addr) error
- func Fingerprint(k ssh.PublicKey) string
- func HasSavedSignIn(a Answer) (bool, error)
- func HostLinkKnownHosts(k ssh.PublicKey) []byte
- func ResolveAddress(ctx context.Context, id string, a Answer, rule policy.HostsPolicy) (netip.Addr, error)
- type Answer
- type Asker
- type Credential
- type Flags
- type Host
- type HostKey
- type Image
- type ImageSpec
- type KnownHostsFiles
- type Options
- type Refusal
Constants ¶
const ( RefusedAddress = receipt.HostAddress RefusedKeyUnknown = receipt.HostKeyUnknown RefusedKeyChanged = receipt.HostKeyChanged RefusedCredential = receipt.HostCredential RefusedUnreached = receipt.HostUnreachable )
The details of a refusal: the receipt's own words (receipt.Host*).
const ( FromFlag = "flag" FromKeychain = "keychain" FromPrompt = "prompt" )
Where a credential came from, as the receipt says it.
const ( TrustPersonsFile = "your known_hosts" TrustRunnersFile = "Agentry's known hosts" TrustedNow = "accepted at this run's start" )
Where a host key's trust came from, as the receipt says it.
const DefaultPort = 22
DefaultPort is SSH's.
const HostlinkPackagesFile = "/etc/agentry/hostlink/packages"
HostlinkPackagesFile is where the hostlink image records the version apk resolved for each of its packages.
Variables ¶
This section is empty.
Functions ¶
func Algorithms ¶
Algorithms is the host key algorithms ssh is held to for k: its type, and for an RSA key the two SHA-2 signatures OpenSSH accepts.
func CheckAddress ¶
CheckAddress refuses an address a target host is never at: this machine's own loopback, a link-local address (a cloud's metadata service among them), and addresses that are no one host. Private, LAN and Tailscale addresses are reached.
func Fingerprint ¶
Fingerprint says a key as ssh-keygen -l does: its type and SHA256.
func HasSavedSignIn ¶
HasSavedSignIn reports whether a sign-in for a is saved (in the keychain, or the sealed credential of a signed-out schedule's fire): what a scheduled run, with no flag and no one to ask, signs in with.
func HostLinkKnownHosts ¶
HostLinkKnownHosts is the one-line known_hosts the host link is given: the checked key under the alias ssh looks it up by.
func ResolveAddress ¶
func ResolveAddress(ctx context.Context, id string, a Answer, rule policy.HostsPolicy) (netip.Addr, error)
ResolveAddress is the IPv4 address a run reaches a target host at: the host if it is an address, else the first IPv4 answer this machine's resolver gives for it. It refuses what a target host is never (loopback, link-local, an unspecified, multicast or broadcast address), what the policy's hosts lists exclude, and a host with no IPv4 address: the relay that reaches it is on docker's IPv4 network.
Types ¶
type Answer ¶
type Answer struct {
User string `json:"user"`
// Host is the name or the address as written, without brackets.
Host string `json:"host"`
Port int `json:"port"`
}
Answer is a host question's answer, [user@]host[:port] (an IPv6 address in brackets), as the person wrote it.
func ParseAnswer ¶
ParseAnswer reads a host question's answer. The user defaults to this machine's user name and the port to 22; neither ever carries a credential, and an answer that holds a password (user:password@host) is refused, saying so.
func (Answer) Account ¶
Account is the system keychain account a target host's saved sign-in is kept under (service agentry): a name, never a secret.
func (Answer) KnownHostsName ¶
KnownHostsName is the name the host's key is looked up and kept under in a known_hosts file, as OpenSSH writes it: the host as named, in brackets with its port when the port is not 22.
type Asker ¶
type Asker interface {
Ask(prompt, def string) (string, error)
AskSecret(prompt string) (string, error)
Confirm(prompt string, def bool) (bool, error)
}
Asker is how a person at a terminal is asked; nil is no one to ask.
type Credential ¶
type Credential struct {
// Auth is hostlink.AuthKey or hostlink.AuthPassword.
Auth string
// KeyFile is the key's path on this machine, for the receipt; Key is
// its bytes, as the file holds them.
KeyFile string
Key []byte
Passphrase string
Password string
// Sudo is the password sudo is fed, "" for none.
Sudo string
// From and SudoFrom say where each came from (From*).
From, SudoFrom string
}
Credential is a target host's sign-in.
func ResolveCredential ¶
func ResolveCredential(id string, a Answer, f Flags, getenv func(string) string, ask Asker, warn func(string)) (Credential, error)
ResolveCredential takes a target host's sign-in, in the order above. ask nil is a run with no terminal: what no flag and no saved sign-in gives is refused (the sign-in) or gone without (sudo). warn reports a keychain that could not be read, which the run then looks past.
func (Credential) Values ¶
func (c Credential) Values() []string
Values are the credential's secrets, for the run's redactor.
func (Credential) Words ¶
func (c Credential) Words() string
Words say the credential as the receipt does: its kind and where it came from, never a value.
type Flags ¶
Flags are the target-host flags of agentry run, by host id: a key file's path, and the environment variables a passphrase, a password and a sudo password are read from.
func ParseFlags ¶
ParseFlags reads --host-key id=PATH, --host-passphrase id=ENV, --host-password id=ENV and --host-sudo-password id=ENV.
type Host ¶
type Host struct {
ID string
Answer Answer
Address netip.Addr
HostKey HostKey
Credential Credential
}
Host is a target host readied for a run: the person's answer, the address it resolved to, its checked key, and its sign-in.
func Prepare ¶
Prepare readies one target host. With a person at a terminal it asks for nothing a refusal would waste: the address, the host key, and only then the sign-in. With no one to ask it takes the sign-in first: such a run has only its flags and its keychain, and one with neither (a hosted run, whose host has no keychain and passes no host flag) is refused before any name is resolved or any address dialled.
func (*Host) Document ¶
Document is the host's entry in intake.json: where the run reached and as whom, and the key it trusted, never a credential.
func (*Host) ReceiptLine ¶
ReceiptLine is the host's capabilities_enforced line: who, the host as named and the address it resolved to, the port, the key and where its trust came from, the sign-in's kind and source, and what the run's boundary does not cover.
type HostKey ¶
HostKey is a target host's checked key.
func CheckHostKey ¶
func CheckHostKey(ctx context.Context, id string, a Answer, addr netip.Addr, files KnownHostsFiles, ask Asker, say func(string)) (HostKey, error)
CheckHostKey reads the key the host offers at addr and decides whether the run may trust it.
func (HostKey) Fingerprint ¶
Fingerprint is the key's type and SHA256 fingerprint, as ssh shows it.
type ImageSpec ¶
type ImageSpec struct {
Tag, Base, Runner string
}
ImageSpec is the host link's image for a runner image and a base.
func HostLinkImage ¶
HostLinkImage is the image spec; its tag is a hash of the whole build, so a new runner, base or recipe gets an image of its own.
func (ImageSpec) Dockerfile ¶
Dockerfile is the build, every step in exec form.
type KnownHostsFiles ¶
type KnownHostsFiles struct {
// Persons is the person's ~/.ssh/known_hosts, read only; "" or absent
// is no file.
Persons string
// Runners is the runner home's known_hosts, where a key trusted at a
// run's start is kept.
Runners string
}
KnownHostsFiles are the two files a host key is looked up in.
func DefaultKnownHostsFiles ¶
func DefaultKnownHostsFiles(runnerHome string) KnownHostsFiles
DefaultKnownHostsFiles are the person's file and the runner home's.
type Options ¶
type Options struct {
// Hosts is the policy's hosts lists.
Hosts policy.HostsPolicy
// KnownHosts are the files host keys are looked up in.
KnownHosts KnownHostsFiles
Flags Flags
Getenv func(string) string
// Ask is a person at a terminal; nil, no one is asked anything.
Ask Asker
// Say reports a warning or a note to the person.
Say func(string)
// Pin is the SHA256 fingerprint (ssh.FingerprintSHA256) of the host
// key a schedule was made with: a run that finds another refuses, as a
// changed key does.
Pin string
// Keep saves the sign-in in the keychain, without asking, wherever it
// came from: a schedule's runs, or a persistent agent's segments,
// read it there.
Keep bool
}
Options are what readying a target host reads besides its answer.