Documentation
¶
Overview ¶
Package supervisor runs a candidate and reference service behind the SPECTRE proxies, sandboxing the candidate's egress and splitting host resources with cgroups.
Index ¶
Constants ¶
const SandboxArg = "__spectre_sandbox__"
SandboxArg is the first argument that re-execs the supervisor as the egress sandbox launcher for a child command.
Variables ¶
This section is empty.
Functions ¶
func ExecSandbox ¶
ExecSandbox installs the egress seccomp filter then replaces the process with command, so the filter guards it. It returns only when the filter or exec fails.
Types ¶
type Config ¶
type Config struct {
// Candidate is the shell command for the sandboxed candidate service.
Candidate string `required:"" help:"Shell command for the candidate service. $SPECTRE_LISTEN and $SPECTRE_EGRESS are exported to it."`
// Reference is the shell command for the authoritative reference service.
Reference string `required:"" help:"Shell command for the reference service. $SPECTRE_LISTEN and $SPECTRE_EGRESS are exported to it."`
// CandidateProtocol is the protocol the ingress uses to reach the candidate.
CandidateProtocol string `` /* 157-byte string literal not displayed */
// ReferenceProtocol is the protocol the ingress uses to reach the reference.
ReferenceProtocol string `` /* 157-byte string literal not displayed */
// Reflection loads and compares both backends' descriptors via gRPC reflection.
Reflection bool `` /* 179-byte string literal not displayed */
// Listen is the public ingress address that clients send traffic to.
Listen string `default:"127.0.0.1:50050" help:"Public ingress address: host:port, or unix:<path|@abstract> for a unix socket."`
// SocketDir holds the unix sockets wiring the proxies to the services.
SocketDir string `default:"dist/sockets" help:"Directory for the unix sockets wiring the proxies to the services."`
// Destinations maps each request host to its upstream URL for egress.
Destinations map[string]string `` /* 139-byte string literal not displayed */
// ScriptsDir holds the comparison scripts passed to both proxies.
ScriptsDir string `type:"existingdir" placeholder:"DIR" help:"Directory of comparison scripts passed to both proxies."`
// SchemaDir holds the TypeScript schema passed to both proxies.
SchemaDir string `type:"existingdir" placeholder:"DIR" help:"Directory of TypeScript schema passed to both proxies."`
// MatchWindow bounds how long a candidate call waits for a matching reference call.
MatchWindow time.Duration `default:"5s" help:"Maximum time a candidate egress call waits for an equivalent reference call before a 502."`
// Descriptors supplies protobuf descriptors to both proxies.
Descriptors descriptors.Config `embed:""`
// Limits configures the cgroup resource split between the services.
Limits LimitConfig `embed:""`
// Sandbox configures the candidate egress sandbox.
Sandbox SandboxConfig `embed:""`
// StartupTimeout bounds how long each process has to start listening.
StartupTimeout time.Duration `default:"30s" help:"Maximum time for each process to begin accepting connections."`
// ShutdownTimeout bounds graceful shutdown before processes are killed.
ShutdownTimeout time.Duration `default:"10s" help:"Maximum time for processes to exit after a termination signal."`
}
Config contains the command-line configuration for the supervisor.
type LimitConfig ¶
type LimitConfig struct {
// Enabled applies the cgroup split; disable it where cgroups are unavailable.
Enabled bool `name:"limits" negatable:"" default:"true" help:"Apply a cgroup v2 CPU and memory split to the services."`
// Parent is the cgroup v2 path hosting the service cgroups.
Parent string `` /* 167-byte string literal not displayed */
// MemoryMax is the total memory in bytes split between the services.
MemoryMax int64 `name:"memory-max" default:"0" help:"Total memory in bytes split between the services. 0 detects the system memory."`
// CandidateCPUWeight is the candidate cpu.weight, 1-10000.
CandidateCPUWeight uint `` /* 143-byte string literal not displayed */
// ReferenceCPUWeight is the reference cpu.weight, 1-10000.
ReferenceCPUWeight uint `name:"reference-cpu-weight" default:"100" help:"Reference cpu.weight (1-10000)."`
CandidateMemoryShare uint `name:"candidate-memory-share" default:"1" help:"Candidate share of the memory budget, relative to the reference share."`
ReferenceMemoryShare uint `name:"reference-memory-share" default:"1" help:"Reference share of the memory budget."`
}
LimitConfig contains the cgroup v2 resource split between the services.
func (LimitConfig) Validate ¶
func (c LimitConfig) Validate() error
Validate checks that the cgroup weights and shares are usable.
type SandboxConfig ¶
type SandboxConfig struct {
// EgressEnabled blocks the candidate from opening IP sockets with seccomp,
// so it can only reach dependencies through the egress proxy.
EgressEnabled bool `` /* 179-byte string literal not displayed */
}
SandboxConfig contains the candidate egress sandbox configuration.
type Supervisor ¶
type Supervisor struct {
// contains filtered or unexported fields
}
Supervisor runs the candidate and reference services behind the SPECTRE proxies, with the candidate's egress sandboxed and host resources split.