Documentation
¶
Overview ¶
Package config provides basic infrastructure to set configuration settings for runsc. The configuration is set by flags to the command line. They can also propagate to a different process using the same flags.
Index ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func RegisterFlags ¶
RegisterFlags registers flags used to populate Config.
Types ¶
type Config ¶
type Config struct {
// RootDir is the runtime root directory.
RootDir string `flag:"root"`
// Traceback changes the Go runtime's traceback level.
Traceback string `flag:"traceback"`
// Debug indicates that debug logging should be enabled.
Debug bool `flag:"debug"`
// LogFilename is the filename to log to, if not empty.
LogFilename string `flag:"log"`
// LogFormat is the log format.
LogFormat string `flag:"log-format"`
// DebugLog is the path to log debug information to, if not empty.
DebugLog string `flag:"debug-log"`
// DebugCommand is a comma-separated list of commands to be debugged if
// --debug-log is also set. Empty means debug all. "!" negates the expression.
// E.g. "create,start" or "!boot,events".
DebugCommand string `flag:"debug-command"`
// PanicLog is the path to log GO's runtime messages, if not empty.
PanicLog string `flag:"panic-log"`
// CoverageReport is the path to write Go coverage information, if not empty.
CoverageReport string `flag:"coverage-report"`
// DebugLogFormat is the log format for debug.
DebugLogFormat string `flag:"debug-log-format"`
// FileAccess indicates how the root filesystem is accessed.
FileAccess FileAccessType `flag:"file-access"`
// FileAccessMounts indicates how non-root volumes are accessed.
FileAccessMounts FileAccessType `flag:"file-access-mounts"`
// Overlay is whether to wrap all mounts in an overlay. The upper tmpfs layer
// will be backed by application memory.
Overlay bool `flag:"overlay"`
// Overlay2 holds configuration about wrapping mounts in overlayfs.
// DO NOT call it directly, use GetOverlay2() instead.
Overlay2 Overlay2 `flag:"overlay2"`
// FSGoferHostUDS is deprecated: use host-uds=all.
FSGoferHostUDS bool `flag:"fsgofer-host-uds"`
// HostUDS controls permission to access host Unix-domain sockets.
// DO NOT call it directly, use GetHostUDS() instead.
HostUDS HostUDS `flag:"host-uds"`
// HostFifo controls permission to access host FIFO (or named pipes).
HostFifo HostFifo `flag:"host-fifo"`
// Network indicates what type of network to use.
Network NetworkType `flag:"network"`
// EnableRaw indicates whether raw sockets should be enabled. Raw
// sockets are disabled by stripping CAP_NET_RAW from the list of
// capabilities.
EnableRaw bool `flag:"net-raw"`
// AllowPacketEndpointWrite enables write operations on packet endpoints.
AllowPacketEndpointWrite bool `flag:"TESTONLY-allow-packet-endpoint-write"`
// HostGSO indicates that host segmentation offload is enabled.
HostGSO bool `flag:"gso"`
// GvisorGSO indicates that gVisor segmentation offload is enabled. The flag
// retains its old name of "software" GSO for API consistency.
GvisorGSO bool `flag:"software-gso"`
// GvisorGROTimeout sets gVisor's generic receive offload timeout. Zero
// bypasses GRO.
GvisorGROTimeout time.Duration `flag:"gvisor-gro"`
// TXChecksumOffload indicates that TX Checksum Offload is enabled.
TXChecksumOffload bool `flag:"tx-checksum-offload"`
// RXChecksumOffload indicates that RX Checksum Offload is enabled.
RXChecksumOffload bool `flag:"rx-checksum-offload"`
// QDisc indicates the type of queuening discipline to use by default
// for non-loopback interfaces.
QDisc QueueingDiscipline `flag:"qdisc"`
// LogPackets indicates that all network packets should be logged.
LogPackets bool `flag:"log-packets"`
// PCAP is a file to which network packets should be logged in PCAP format.
PCAP string `flag:"pcap-log"`
// Platform is the platform to run on.
Platform string `flag:"platform"`
// PlatformDevicePath is the path to the device file used by the platform.
// e.g. "/dev/kvm" for the KVM platform.
// If unset, a sane platform-specific default will be used.
PlatformDevicePath string `flag:"platform_device_path"`
// Strace indicates that strace should be enabled.
Strace bool `flag:"strace"`
// StraceSyscalls is the set of syscalls to trace (comma-separated values).
// If StraceEnable is true and this string is empty, then all syscalls will
// be traced.
StraceSyscalls string `flag:"strace-syscalls"`
// StraceLogSize is the max size of data blobs to display.
StraceLogSize uint `flag:"strace-log-size"`
// StraceEvent indicates sending strace to events if true. Strace is
// sent to log if false.
StraceEvent bool `flag:"strace-event"`
// DisableSeccomp indicates whether seccomp syscall filters should be
// disabled. Pardon the double negation, but default to enabled is important.
DisableSeccomp bool
// EnableCoreTags indicates whether the Sentry process and children will be
// run in a core tagged process. This isolates the sentry from sharing
// physical cores with other core tagged processes. This is useful as a
// mitigation for hyperthreading side channel based attacks. Requires host
// linux kernel >= 5.14.
EnableCoreTags bool `flag:"enable-core-tags"`
// WatchdogAction sets what action the watchdog takes when triggered.
WatchdogAction watchdog.Action `flag:"watchdog-action"`
// PanicSignal registers signal handling that panics. Usually set to
// SIGUSR2(12) to troubleshoot hangs. -1 disables it.
PanicSignal int `flag:"panic-signal"`
// ProfileEnable is set to prepare the sandbox to be profiled.
ProfileEnable bool `flag:"profile"`
// ProfileBlock collects a block profile to the passed file for the
// duration of the container execution. Requires ProfileEnabled.
ProfileBlock string `flag:"profile-block"`
// ProfileCPU collects a CPU profile to the passed file for the
// duration of the container execution. Requires ProfileEnabled.
ProfileCPU string `flag:"profile-cpu"`
// ProfileHeap collects a heap profile to the passed file for the
// duration of the container execution. Requires ProfileEnabled.
ProfileHeap string `flag:"profile-heap"`
// ProfileMutex collects a mutex profile to the passed file for the
// duration of the container execution. Requires ProfileEnabled.
ProfileMutex string `flag:"profile-mutex"`
// TraceFile collects a Go runtime execution trace to the passed file
// for the duration of the container execution.
TraceFile string `flag:"trace"`
// RestoreFile is the path to the saved container image.
RestoreFile string
// NumNetworkChannels controls the number of AF_PACKET sockets that map
// to the same underlying network device. This allows netstack to better
// scale for high throughput use cases.
NumNetworkChannels int `flag:"num-network-channels"`
// Rootless allows the sandbox to be started with a user that is not root.
// Defense in depth measures are weaker in rootless mode. Specifically, the
// sandbox and Gofer process run as root inside a user namespace with root
// mapped to the caller's user. When using rootless, the container root path
// should not have a symlink.
Rootless bool `flag:"rootless"`
// AlsoLogToStderr allows to send log messages to stderr.
AlsoLogToStderr bool `flag:"alsologtostderr"`
// ReferenceLeakMode sets reference leak check mode
ReferenceLeak refs.LeakMode `flag:"ref-leak-mode"`
// CPUNumFromQuota sets CPU number count to available CPU quota, using
// least integer value greater than or equal to quota.
//
// E.g. 0.2 CPU quota will result in 1, and 1.9 in 2.
CPUNumFromQuota bool `flag:"cpu-num-from-quota"`
// Enable lisafs.
Lisafs bool `flag:"lisafs"`
// Allows overriding of flags in OCI annotations.
AllowFlagOverride bool `flag:"allow-flag-override"`
// Enables seccomp inside the sandbox.
OCISeccomp bool `flag:"oci-seccomp"`
// Mounts the cgroup filesystem backed by the sentry's cgroupfs.
Cgroupfs bool `flag:"cgroupfs"`
// Don't configure cgroups.
IgnoreCgroups bool `flag:"ignore-cgroups"`
// Use systemd to configure cgroups.
SystemdCgroup bool `flag:"systemd-cgroup"`
// PodInitConfig is the path to configuration file with additional steps to
// take during pod creation.
PodInitConfig string `flag:"pod-init-config"`
// Use pools to manage buffer memory instead of heap.
BufferPooling bool `flag:"buffer-pooling"`
// AFXDP defines whether to use an AF_XDP socket to receive packets
// (rather than AF_PACKET). Enabling it disables RX checksum offload.
AFXDP bool `flag:"EXPERIMENTAL-afxdp"`
// FDLimit specifies a limit on the number of host file descriptors that can
// be open simultaneously by the sentry and gofer. It applies separately to
// each.
FDLimit int `flag:"fdlimit"`
// DCache sets the global dirent cache size. If zero, per-mount caches are
// used.
DCache int `flag:"dcache"`
// TestOnlyAllowRunAsCurrentUserWithoutChroot should only be used in
// tests. It allows runsc to start the sandbox process as the current
// user, and without chrooting the sandbox process. This can be
// necessary in test environments that have limited capabilities. When
// disabling chroot, the container root path should not have a symlink.
TestOnlyAllowRunAsCurrentUserWithoutChroot bool `flag:"TESTONLY-unsafe-nonroot"`
// TestOnlyTestNameEnv should only be used in tests. It looks up for the
// test name in the container environment variables and adds it to the debug
// log file name. This is done to help identify the log with the test when
// multiple tests are run in parallel, since there is no way to pass
// parameters to the runtime from docker.
TestOnlyTestNameEnv string `flag:"TESTONLY-test-name-env"`
}
Config holds configuration that is not part of the runtime spec.
Follow these steps to add a new flag:
- Create a new field in Config.
- Add a field tag with the flag name
- Register a new flag in flags.go, with same name and add a description
- Add any necessary validation into validate()
- If adding an enum, follow the same pattern as FileAccessType
- Evaluate if the flag can be changed with OCI annotations. See overrideAllowlist for more details
func NewFromFlags ¶
NewFromFlags creates a new Config with values coming from command line flags.
func (*Config) GetHostUDS ¶
GetHostUDS returns the FS gofer communication that is allowed, taking into consideration all flags what affect the result.
func (*Config) GetOverlay2 ¶
GetOverlay2 returns the overlay configuration, taking into consideration all flags that affect the result.
type FileAccessType ¶
type FileAccessType int
FileAccessType tells how the filesystem is accessed.
const ( // FileAccessExclusive gives the sandbox exclusive access over files and // directories in the filesystem. No external modifications are permitted and // can lead to undefined behavior. // // Exclusive filesystem access enables more aggressive caching and offers // significantly better performance. This is the default mode for the root // volume. FileAccessExclusive FileAccessType = iota // requires revalidation on every filesystem access to detect external // changes, and reduces the amount of caching that can be done. This is the // default mode for non-root volumes. FileAccessShared )
func (*FileAccessType) Set ¶
func (f *FileAccessType) Set(v string) error
Set implements flag.Value.
func (FileAccessType) String ¶
func (f FileAccessType) String() string
String implements flag.Value.
type HostFifo ¶
type HostFifo int
HostFifo tells how much of the host FIFO (or named pipes) the file system has access to.
type HostUDS ¶
type HostUDS int
HostUDS tells how much of the host UDS the file system has access to.
const ( // HostUDSNone doesn't allows UDS from the host to be manipulated. HostUDSNone HostUDS = 0x0 // HostUDSOpen allows UDS from the host to be opened, e.g. connect(2). HostUDSOpen HostUDS = 0x1 // HostUDSCreate allows UDS from the host to be created, e.g. bind(2). HostUDSCreate HostUDS = 0x2 // HostUDSAll allows all form of communication with the host through UDS. HostUDSAll = HostUDSOpen | HostUDSCreate )
func (HostUDS) AllowCreate ¶
AllowCreate returns true if it can create UDS in the host.
type NetworkType ¶
type NetworkType int
NetworkType tells which network stack to use.
const ( // NetworkSandbox uses internal network stack, isolated from the host. NetworkSandbox NetworkType = iota // NetworkHost redirects network related syscalls to the host network. NetworkHost // NetworkNone sets up just loopback using netstack. NetworkNone )
type Overlay2 ¶
Overlay2 holds the configuration for setting up overlay filesystems for the container.
type QueueingDiscipline ¶
type QueueingDiscipline int
QueueingDiscipline is used to specify the kind of Queueing Discipline to apply for a give FDBasedLink.
const ( // QDiscNone disables any queueing for the underlying FD. QDiscNone QueueingDiscipline = iota // QDiscFIFO applies a simple fifo based queue to the underlying FD. QDiscFIFO )
func (*QueueingDiscipline) Set ¶
func (q *QueueingDiscipline) Set(v string) error
Set implements flag.Value.
func (QueueingDiscipline) String ¶
func (q QueueingDiscipline) String() string
String implements flag.Value.
Source Files
Click to show internal directories.
Click to hide internal directories.