Documentation
¶
Overview ¶
Package checks verifies the environment proximo needs, one independently verifiable statement at a time, and collects the outcomes into one Report.
A Check reports; it never repairs, and it never elevates: everything proximo must read is readable unprivileged, and a check that needed a password would be describing a repair. Every failure therefore carries a Remedy — the cure where one exists, and otherwise the command whose own output names the cause.
Index ¶
Constants ¶
const ( IDPeerIntermediate = "peer-intermediate" IDPeerRoutes = "peer-routes" IDPeerDNS = "peer-dns" IDPeerRelay = "peer-relay" IDMesh = "mesh" )
The peer Checks (docs/cli.md#the-peer-checks). On a machine that has not opted in every one of them is Skipped, and no other Check reads a peer value.
const ( IDDocker = "docker" IDPortHTTP = "port-http" IDPortHTTPS = "port-https" IDPortDNS = "port-dns" IDCertutil = "certutil" IDInstalled = "installed" IDTrustSystem = "trust-system" IDTrustNSS = "trust-nss" IDStack = "stack" IDStackVersion = "stack-version" IDStackImage = "stack-image" IDDNSServer = "dns-server" IDDNSResolver = "dns-resolver" IDAccessLog = "access-log" IDIncidents = "incidents" IDRoutes = "routes" IDAgentSkill = "agent-skill" )
Check IDs. They are the vocabulary prerequisites are written in, so they are named rather than spelled out at each use.
Variables ¶
This section is empty.
Functions ¶
func DockerReachable ¶
DockerReachable pings the Docker daemon. It is the one reading the rest of the CLI shares: every command that talks to Docker needs the same answer, and this way it is worded once.
Types ¶
type Check ¶
type Check struct {
// ID is how other checks name this one as a prerequisite.
ID string
// Name is the statement itself, asserted in the positive, so that a pass
// and a failure read as the same sentence with opposite marks.
Name string
// Doc is the anchor of the docs/troubleshooting.md section explaining this
// failure. A test asserts the section exists: a documented failure with no
// check, or a check with no explanation, is the drift this prevents.
Doc string
// Needs are the IDs of checks that must pass first. A prerequisite that
// failed or was skipped skips this one instead of producing a second red
// line for one cause.
Needs []string
// Run performs the verification. It must not mutate the host.
Run func(ctx context.Context) Result
}
Check is one independently verifiable statement about the environment.
func All ¶
All is the registry: every check proximo knows how to make, in the order a developer should read them. One list, so the pre-install subset and the full report can never drift apart.
func PreInstall ¶
PreInstall is what `install` gates on: Preflight plus the one statement about a store `install` is about to write. It is not what `up` gates on, because `up` changes no host configuration and a machine that cannot install browser trust must still be allowed to start the stack.
type Env ¶
type Env struct {
// TLD is the domain proximo claims, and the suffix of the sentinel name the
// DNS checks resolve.
TLD string
// CLIVersion is the version of this binary, compared against the stack's.
CLIVersion string
// CanonicalImage is the stack image this CLI pins itself to.
CanonicalImage string
// CAPath and ResolverPath are the two host artifacts that together mean
// "installed": the CA on disk and the file pointing the TLD at proximo.
CAPath string
ResolverPath string
// ResolverRemedy and CertutilRemedy are OS-specific commands, resolved once
// here so the registry stays free of platform branching.
ResolverRemedy string
CertutilRemedy string
FileExists func(path string) bool
PortHeldBy func(ctx context.Context, port int, proto string) (PortHolder, string)
QueryLocal func(ctx context.Context, name string) (string, error)
SystemResolve func(ctx context.Context, name string) (string, error)
SystemTrusted func(ctx context.Context) (bool, error)
NSSTrusted func(ctx context.Context) (found, total int, err error)
// CertutilInstallable reports whether browser trust can be installed at
// all — before `install` writes anything that would have to be undone.
CertutilInstallable func() bool
Docker func(ctx context.Context) error
Stack func(ctx context.Context) (docker.StackInfo, error)
Routes func(ctx context.Context) ([]docker.Route, error)
// AccessLog reports whether the Traefik that is running records an access
// log. Without one no route produces an Exchange, and `proximo errors` is
// silent for a reason that has nothing to do with a developer's code.
AccessLog func(ctx context.Context) (bool, error)
// Incidents reports whether the running watcher publishes the Incident read
// API. Without it nothing says that a container exited, restarted or was
// OOM-killed, and `proximo errors` is silent about a restart-looping worker
// for a reason that has nothing to do with a developer's code.
Incidents func(ctx context.Context) (bool, error)
// AgentSkill reports every copy of the agent Skill proximo can see, so the
// registry can tell a copy that is level with this binary from one that is
// behind it and one it may not touch.
AgentSkill func() ([]skill.Copy, error)
// Peer holds the peer-sharing values; on a machine that has not opted in
// they are empty and every peer Check is Skipped.
Peer config.Config
// PeerErr is why the configuration holding them could not be read, if it
// could not: the peer Checks then say so rather than claim a value is unset.
PeerErr error
// Intermediate returns the installed intermediate, nil when there is none.
Intermediate func() (*x509.Certificate, error)
// QueryAt asks a DNS server (host:port) directly for a name's A record.
QueryAt func(ctx context.Context, server, name string) (string, error)
// InterfaceAddrs lists every interface address of this machine, so a
// failed peer DNS bind can say whether the mesh address is held at all.
InterfaceAddrs func() ([]net.Addr, error)
// TLSHandshake completes a TLS handshake with addr for serverName, without
// judging the certificate: it proves something answered TLS there.
TLSHandshake func(ctx context.Context, addr, serverName string) error
}
Env is everything the checks read the host through. Checks take their dependencies as parameters, the way the install host steps do, so the suite can build a machine with no resolver, a port held by a stranger, or no NSS store, without touching the host running the tests.
func DefaultEnv ¶
DefaultEnv wires the checks to the real host. It fails only where proximo itself cannot run — an unsupported platform, or no home directory — since every other unknown is a check's answer to give, not an error to return.
type PortHolder ¶
type PortHolder string
PortHolder says who holds a host port. Three of the four outcomes are healthy, which is why the check asks who rather than whether.
const ( // PortFree means nothing is listening. PortFree PortHolder = "free" // PortStack means a proximo stack container publishes it. PortStack PortHolder = "stack" // PortContainer means another container publishes it — nameable, so the // remedy can be a docker question. PortContainer PortHolder = "container" // PortProcess means no container publishes it, so a host process does. PortProcess PortHolder = "process" )
type Report ¶
type Report struct {
Outcomes []Outcome
}
Report is one complete pass of Checks — passes, failures and skips together, which is what makes it a whole thing rather than a stream of errors.
func Run ¶
Run performs each check in order, skipping any whose prerequisite did not pass and naming the prerequisite it waited on.
type Result ¶
type Result struct {
Status Status
// Detail is what was observed, in the developer's terms. A passing check
// says it too: a pass narrows the search as much as a failure does.
Detail string
// Remedy is the exact command the developer runs next. Required on Fail,
// and meaningless otherwise.
Remedy string
// Doc names a troubleshooting section for this failure when it is not the
// one the Check usually points at. One check can fail for causes that are
// documented apart — a contested host is not a mislabelled container — and
// sending a developer to the wrong section is worse than sending them to
// none. Empty means the Check's own section.
Doc string
}
Result is what one Check observed.
func Failed ¶
Failed records a statement that did not hold, with the command that clears it (or, where nothing cures it, the command whose output names the cause).
type Status ¶
type Status string
Status is the outcome of one Check. There are exactly three. A fourth ("warn") would mean a failure proximo decided not to insist on, and that decision belongs to whoever reads the Report, not to proximo writing it.
const ( // Pass is a statement that held. Pass Status = "pass" // Fail is a statement that did not hold. It always carries a Remedy. Fail Status = "fail" // Skip is a statement the environment could not answer — never one whose // answer was inconvenient. A skip names what it waited on. Skip Status = "skip" )