Problem scenario
You want to know the syntax of the runsc utility. How do you run "runsc kill" or other commands?
Prerequisite
This assumes you have runsc installed. On a Debian distribution of Linux, run this command:
sudo apt -y install runscSolution
Run "runsc ?" to learn more about different syntax.
Run "runsc flags" to learn about other options.
$ runsc ?
Usage: runsc <flags> <subcommand> <subcommand args>
Subcommands:
checkpoint checkpoint current state of container (experimental)
create create a secure container
delete delete resources held by a container
do Simplistic way to execute a command inside the sandbox. It's to be used for testing only.
events display container events such as OOM notifications, cpu, memory, and IO usage statistics
exec execute new process inside the container
flags describe all known top-level flags
help Print help documentation.
kill sends a signal to the container
list list containers started by runsc with the given root
pause pause suspends all processes in a container
port-forward port forward to a secure container
ps ps displays the processes running inside a container
restore restore a saved state of container (experimental)
resume Resume unpauses a paused container
run create and run a secure container
spec create a new OCI bundle specification file
start start a secure container
state get the state of a container
wait wait on a process inside a container
Subcommands for debug:
debug shows a variety of debug information
read-control read a cgroups control value inside the container
state shows information about a statefile
symbolize Convert synthetic instruction pointers from kcov into positions in the runsc source code. Only used when Go coverage is enabled.
usage Usage shows application memory usage across various categories in bytes.
write-control write a cgroups control value inside the container
Subcommands for helpers:
install adds a runtime to docker daemon configuration
mitigate mitigate mitigates the underlying system against side channel attacks
trace manages trace sessions for a given sandbox
uninstall removes a runtime from docker daemon configuration
Subcommands for internal use only:
boot launch a sandbox process
gofer launch a gofer process that proxies access to container files
umount umount the specified directory lazily when one byte is read from sync-fd
Subcommands for metrics:
export-metrics export metric data for the sandbox
metric-metadata export metric metadata of metrics registered in this build, in text proto format
metric-server implements Prometheus metrics HTTP endpoint
Use "runsc flags" for a list of top-level flags
$ runsc flags
-EXPERIMENTAL-afxdp
EXPERIMENTAL. Use an AF_XDP socket to receive packets.
-TESTONLY-afs-syscall-panic
TEST ONLY; do not ever use! Used for tests exercising gVisor panic reporting.
-TESTONLY-allow-packet-endpoint-write
TEST ONLY; do not ever use! Used for tests to allow writes on packet sockets.
-TESTONLY-test-name-env string
TEST ONLY; do not ever use! Used for automated tests to improve logging.
-TESTONLY-unsafe-nonroot
TEST ONLY; do not ever use! This skips many security measures that isolate the host from the sandbox.
-allow-flag-override
allow OCI annotations (dev.gvisor.flag.<name>) to override flags for debugging.
-alsologtostderr
send log messages to stderr.
-buffer-pooling
enable allocation of buffers from a shared pool instead of the heap. (default true)
-cgroupfs
Automatically mount cgroupfs.
-coverage-fd int
file descriptor to write Go coverage output. (default -1)
-coverage-report string
file path where Go coverage reports are written. Reports will only be generated if runsc is built with --collect_code_coverage and --instrumentation_filter Bazel flags.
-cpu-num-from-quota
set cpu number to cpu quota (least integer greater or equal to quota value, but not less than 2)
-dcache int
Set the global dentry cache size. This acts as a coarse-grained control on the number of host FDs simultaneously open by the sentry. If negative, per-mount caches are used. (default -1)
-debug
enable debug logging.
-debug-command string
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"
-debug-log string
additional location for logs. If it ends with '/', log files are created inside the directory with default names. The following variables are available: %TIMESTAMP%, %COMMAND%.
-debug-log-fd int
file descriptor to write debug logs to. If set, the 'debug-log-dir' flag is ignored. (default -1)
-debug-log-format string
log format: text (default), json, or json-k8s. (default "text")
-directfs
directly access the container filesystems from the sentry. Sentry runs with higher privileges. (default true)
-enable-core-tags
enables core tagging. Requires host linux kernel >= 5.14.
-fdlimit int
Specifies a limit on the number of host file descriptors that can be open. Applies separately to the sentry and gofer. Note: each file in the sandbox holds more than one host FD open. (default -1)
-file-access value
specifies which filesystem validation to use for the root mount: exclusive (default), shared.
-file-access-mounts value
specifies which filesystem validation to use for volumes other than the root mount: shared (default), exclusive. (default shared)
-fsgofer-host-uds
DEPRECATED: use host-uds=all
-fuse
DEPRECATED: this flag has no effect. (default true)
-gso
enable host segmentation offload if it is supported by a network device. (default true)
-gvisor-gro duration
(e.g. "20000ns" or "1ms") sets gVisor's generic receive offload timeout. Zero bypasses GRO.
-host-fifo value
controls permission to access host FIFOs (or named pipes). Values: none|open, default: none
-host-uds value
controls permission to access host Unix-domain sockets. Values: none|open|create|all, default: none
-ignore-cgroups
don't configure cgroups.
-iouring
TEST ONLY; Enables io_uring syscalls in the sentry. Support is experimental and very limited.
-lisafs
DEPRECATED: this flag has no effect. (default true)
-log string
file path where internal debug information is written, default is stdout.
-log-fd int
file descriptor to log to. If set, the 'log' flag is ignored. (default -1)
-log-format string
log format: text (default), json, or json-k8s. (default "text")
-log-packets
enable network packet logging.
-metric-server runsc metric-server
if set, export metrics on this address. This may either be 1) 'addr:port' to export metrics on a specific network interface address, 2) ':port' for exporting metrics on all interfaces, or 3) an absolute path to a Unix Domain Socket. The substring '%ID%' will be replaced by the container ID, and '%RUNTIME_ROOT%' by the root. This flag must be specified in both runsc metric-server and `runsc create`, and their values must match.
-net-raw runsc exec
enable raw sockets. When false, raw sockets are disabled by removing CAP_NET_RAW from containers (runsc exec will still be able to utilize raw sockets). Raw sockets allow malicious containers to craft packets and potentially attack the network.
-network value
specifies which network to use: sandbox (default), host, none. Using network inside the sandbox is more secure because it's isolated from the host network.
-num-network-channels int
number of underlying channels(FDs) to use for network link endpoints. (default 1)
-nvproxy
EXPERIMENTAL: enable support for Nvidia GPUs
-nvproxy-docker docker --gpus
Expose GPUs to containers based on NVIDIA_VISIBLE_DEVICES, as requested by the container or set by docker --gpus. Allows containers to self-serve GPU access and thus disabled by default for security. libnvidia-container must be installed on the host. No effect unless --nvproxy is enabled.
-oci-seccomp
Enables loading OCI seccomp filters inside the sandbox.
-overlay
DEPRECATED: use --overlay2=all:memory to achieve the same effect
-overlay2 value
wrap mounts with overlayfs. Format is {mount}:{medium}, where 'mount' can be 'root' or 'all' and medium can be 'memory', 'self' or 'dir=/abs/dir/path' in which filestore will be created. 'none' will turn overlay mode off. (default root:self)
-panic-log string
file path where panic reports and other Go's runtime messages are written.
-panic-log-fd int
file descriptor to write Go's runtime messages. (default -1)
-panic-signal int
register signal handling that panics. Usually set to SIGUSR2(12) to troubleshoot hangs. -1 disables it. (default -1)
-pcap-log string
location of PCAP log file.
-platform string
specifies which platform to use: systrap (default), ptrace, kvm. (default "systrap")
-platform_device_path string
path to a platform-specific device file (e.g. /dev/kvm for KVM platform). If unset, will use a sane platform-specific default.
-pod-init-config string
path to configuration file with additional steps to take during pod creation.
-profile
prepares the sandbox to use Golang profiler. Note that enabling profiler loosens the seccomp protection added to the sandbox (DO NOT USE IN PRODUCTION).
-profile-block string
collects a block profile to this file path for the duration of the container execution. Requires -profile=true.
-profile-cpu string
collects a CPU profile to this file path for the duration of the container execution. Requires -profile=true.
-profile-heap string
collects a heap profile to this file path for the duration of the container execution. Requires -profile=true.
-profile-mutex string
collects a mutex profile to this file path for the duration of the container execution. Requires -profile=true.
-qdisc value
specifies which queueing discipline to apply by default to the non loopback nics used by the sandbox. (default fifo)
-ref-leak-mode value
sets reference leak check mode: disabled (default), log-names, log-traces.
-root string
root directory for storage of container state.
-rootless
it allows the sandbox to be started with a user that is not root. Sandbox and Gofer processes may run with same privileges as current user.
-rx-checksum-offload
enable RX checksum offload. (default true)
-software-gso
enable gVisor segmentation offload when host offload can't be enabled. (default true)
-strace
enable strace.
-strace-event
send strace to event.
-strace-log-size uint
default size (in bytes) to log data argument blobs. (default 1024)
-strace-syscalls string
comma-separated list of syscalls to trace. If --strace is true and this list is empty, then all syscalls will be traced.
-systemd-cgroup
EXPERIMENTAL. Use systemd for cgroups.
-tpuproxy
EXPERIMENTAL: enable support for TPU device passthrough.
-trace string
collects a Go runtime execution trace to this file path for the duration of the container execution.
-traceback string
golang runtime's traceback level (default "system")
-tx-checksum-offload
enable TX checksum offload.
-version
show version and exit.
-vfs2
DEPRECATED: this flag has no effect. (default true)
-watchdog-action value
sets what action the watchdog takes when triggered: log (default), panic.FYI
runsc stands for Run Sandboxed Container.