Documentation
¶
Overview ¶
Package labchecks is the contract of device bootstrap and lab checks: the secret documents the management agent writes (Secret <device>-bootstrap, key bootstrap.json; Secret <lab>-checks, key checks.json), the limits on them and the validation the agent applies before anything is written. The launcher and the checker read the same types.
Index ¶
- Constants
- Variables
- func BootstrapPause(failedAttempts int) time.Duration
- func MarshalBootstrap(b *Bootstrap) ([]byte, error)
- func MarshalChecks(checks []Check) ([]byte, error)
- func NormalizeBootstrap(b *Bootstrap)
- func NormalizeChecks(checks []Check)
- func TruncateDetail(s string) string
- func TruncateValue(s string) string
- func ValidateBootstrap(b *Bootstrap) error
- func ValidateChecks(checks []Check, devices map[string]bool) error
- type Bootstrap
- type Check
- type ChecksDoc
- type CustomPart
- type DirectoryPart
- type File
- type FilePart
- type KernelParamPart
- type Part
- type PermissionPart
- type PortPart
- type ProcessPart
- type RequestPart
Constants ¶
const ( BootstrapSecretSuffix = "-bootstrap" ChecksSecretSuffix = "-checks" // BootstrapKey and ChecksKey hold one JSON document each (Bootstrap and []Check wrapped in ChecksDoc). BootstrapKey = "bootstrap.json" ChecksKey = "checks.json" )
Secret names and keys. The device Secret is named after the Device object (as the -env Secret is), the lab Secret after the Lab.
const ( DefaultInterpreter = "/bin/sh" // DefaultCustomUser: a command of a check runs as nobody unless the author names a user (root included: an explicit choice). DefaultCustomUser = "nobody" DefaultBootstrapTimeLimit = 300 DefaultCheckTimeLimit = 30 )
Defaults filled in by Normalize, so a consumer never guesses them.
const ( // BootstrapMaxAttempts is the number of attempts before a device stays in "failed" (three, with growing pauses). BootstrapMaxAttempts = 3 // MaxBootstrapTimeLimit and MaxCheckTimeLimit are in seconds. MaxBootstrapTimeLimit = 3600 MaxCheckTimeLimit = 600 // MaxScheduleSeconds is the longest interval of a scheduled check (one day). MaxScheduleSeconds = 86400 MaxScriptBytes = 64 << 10 MaxBootstrapFiles = 32 MaxFileBytes = 256 << 10 MaxBootstrapBytes = 512 << 10 // script and all file contents of one device together; a Secret holds 1 MiB and JSON adds a third to bytes MaxChecksPerLab = 64 MaxPartsPerCheck = 8 MaxChecksBytes = 512 << 10 // the whole checks document of a lab MaxPathBytes = 4096 MaxPatternBytes = 1024 MaxExpectBytes = 4096 MaxCommandItems = 64 MaxCommandItemBytes = 4096 MaxIDBytes = 64 MaxNameBytes = 128 MaxResultDetailBytes = 2048 MaxResultValueBytes = 256 // The built-in observations. MaxEntryNames = 64 // names in has_entries / lacks_entries MaxEntryNameBytes = 255 // one name MaxProcessName = 128 // a process name or a user to match MaxHostBytes = 253 // the host of a request MaxRequestPath = 2048 // the path of an HTTP request MaxFileRead = 256 << 10 // the part of a file that is read; a larger file is an error where the content matters )
Limits. Each is a platform ceiling: the agent refuses a request over it, and GetFeatures reports them.
Variables ¶
var Observations = []string{"file", "directory", "process", "port", "kernel_param", "request", "permission", "custom"}
The kinds of observation a laboratory's checker runs. File and custom are the first two; the rest read the state of the device themselves and execute nothing of it.
Functions ¶
func BootstrapPause ¶
BootstrapPause is how long a device waits after the given number of failed bootstrap attempts before it tries again (10 s after the first, 30 s after the second). After BootstrapMaxAttempts failures there is no next attempt.
func MarshalBootstrap ¶
MarshalBootstrap and MarshalChecks produce the Secret documents (after Normalize and Validate).
func MarshalChecks ¶
MarshalChecks encodes the checks document and refuses one over MaxChecksBytes.
func NormalizeBootstrap ¶
func NormalizeBootstrap(b *Bootstrap)
NormalizeBootstrap fills the defaults of a bootstrap list.
func NormalizeChecks ¶
func NormalizeChecks(checks []Check)
NormalizeChecks fills the defaults of every check.
func TruncateDetail ¶
TruncateDetail cuts a result detail to MaxResultDetailBytes on a UTF-8 boundary.
func TruncateValue ¶
TruncateValue cuts a result value to MaxResultValueBytes on a UTF-8 boundary.
func ValidateBootstrap ¶
ValidateBootstrap checks the bootstrap list of one device. It must be called after NormalizeBootstrap.
Types ¶
type Bootstrap ¶
type Bootstrap struct {
Script string `json:"script,omitempty"`
Interpreter string `json:"interpreter,omitempty"`
Files []File `json:"files,omitempty"`
TimeLimitSeconds int32 `json:"timeLimitSeconds"`
}
Bootstrap is the list of one device with the values already filled in: an optional script and files, and a time limit.
type Check ¶
type Check struct {
ID string `json:"id"`
Device string `json:"device"`
Mode string `json:"mode"` // once | continuous
ScheduleSeconds int32 `json:"scheduleSeconds,omitempty"`
ManualRun bool `json:"manualRun,omitempty"`
TimeLimitSeconds int32 `json:"timeLimitSeconds"`
// Parts must all hold in the same run.
Parts []Part `json:"parts"`
}
Check is one check of a lab.
type ChecksDoc ¶
type ChecksDoc struct {
Checks []Check `json:"checks"`
}
ChecksDoc is the document in the lab's checks Secret.
type CustomPart ¶
type CustomPart struct {
Command []string `json:"command,omitempty"`
Script string `json:"script,omitempty"`
Interpreter string `json:"interpreter,omitempty"`
User string `json:"user,omitempty"`
// OutputContains and OutputMatches are optional additional expectations on the output.
OutputContains *string `json:"outputContains,omitempty"`
OutputMatches *string `json:"outputMatches,omitempty"`
}
CustomPart runs a command (or a script) in the device. Exit code 0 means passed.
type DirectoryPart ¶
type DirectoryPart struct {
Path string `json:"path"`
Exists *bool `json:"exists,omitempty"`
Mode *uint32 `json:"mode,omitempty"`
Owner *string `json:"owner,omitempty"`
Group *string `json:"group,omitempty"`
HasEntries []string `json:"hasEntries,omitempty"`
LacksEntries []string `json:"lacksEntries,omitempty"`
}
DirectoryPart: exists (default true), mode, owner, group, names that must be directly in the directory and names that must not.
type File ¶
type File struct {
Path string `json:"path"`
Content []byte `json:"content,omitempty"`
Owner string `json:"owner,omitempty"`
Group string `json:"group,omitempty"`
// Mode is the permission bits (for example 0o644); 0 means the default 0o644.
Mode uint32 `json:"mode,omitempty"`
}
File is a file to place on a device.
type FilePart ¶
type FilePart struct {
Path string `json:"path"`
// Exists true: the file exists; false: it is absent (and no other expectation may be set).
Exists *bool `json:"exists,omitempty"`
ContentContains *string `json:"contentContains,omitempty"`
ContentMatches *string `json:"contentMatches,omitempty"`
Mode *uint32 `json:"mode,omitempty"`
Owner *string `json:"owner,omitempty"`
Group *string `json:"group,omitempty"`
// Type is what the path itself is (it is not followed): file, directory or symlink. Checksum is the sha256 of the content in
// lower-case hex. Both need the file to exist; the checksum needs a regular file of at most MaxFileRead bytes.
Type *string `json:"type,omitempty"`
Checksum *string `json:"checksum,omitempty"`
}
FilePart reads a file of the device and compares. Every expectation is optional, at least one is required.
type KernelParamPart ¶
type KernelParamPart struct {
Name string `json:"name"`
Equals *string `json:"equals,omitempty"`
Matches *string `json:"matches,omitempty"`
}
KernelParamPart: the value of a sysctl; at least one of Equals and Matches.
type Part ¶
type Part struct {
File *FilePart `json:"file,omitempty"`
Custom *CustomPart `json:"custom,omitempty"`
Directory *DirectoryPart `json:"directory,omitempty"`
Process *ProcessPart `json:"process,omitempty"`
Port *PortPart `json:"port,omitempty"`
KernelParam *KernelParamPart `json:"kernelParam,omitempty"`
Request *RequestPart `json:"request,omitempty"`
Permission *PermissionPart `json:"permission,omitempty"`
}
Part is one observation: exactly one member is set.
type PermissionPart ¶
type PermissionPart struct {
User string `json:"user"`
Path string `json:"path"`
Read *bool `json:"read,omitempty"`
Write *bool `json:"write,omitempty"`
Execute *bool `json:"execute,omitempty"`
}
PermissionPart: whether a user may read, write or execute a path, tested without changing anything. Each given boolean must equal the real answer; at least one is required.
type PortPart ¶
type PortPart struct {
Port int32 `json:"port"`
Protocol string `json:"protocol,omitempty"`
Listening *bool `json:"listening,omitempty"`
Address *string `json:"address,omitempty"`
Process *string `json:"process,omitempty"`
}
PortPart: whether something listens on a port. Protocol defaults to tcp, Listening to true. A listener on the wildcard address counts for Address.
type ProcessPart ¶
type ProcessPart struct {
Name *string `json:"name,omitempty"`
Matches *string `json:"matches,omitempty"`
User *string `json:"user,omitempty"`
Running *bool `json:"running,omitempty"`
}
ProcessPart: a process by Name (the command without its directory) or by a regular expression on the command line; at least one. Running defaults to true (false: no such process may run).
type RequestPart ¶
type RequestPart struct {
Protocol string `json:"protocol"`
Host string `json:"host,omitempty"`
Port int32 `json:"port"`
Method string `json:"method,omitempty"`
Path string `json:"path,omitempty"`
Status *int32 `json:"status,omitempty"`
BodyContains *string `json:"bodyContains,omitempty"`
BodyMatches *string `json:"bodyMatches,omitempty"`
}
RequestPart: a connection from inside the device. Protocol is tcp, http or https; Host defaults to 127.0.0.1. For http and https: Method (GET by default, or HEAD), Path (/ by default), Status (200 by default), and rules on the body (GET only).