diff --git a/contrib/cmd/memfd-bind/memfd-bind.go b/contrib/cmd/memfd-bind/memfd-bind.go index c01aad74241..7bc57b0b38d 100644 --- a/contrib/cmd/memfd-bind/memfd-bind.go +++ b/contrib/cmd/memfd-bind/memfd-bind.go @@ -15,6 +15,17 @@ * limitations under the License. */ +// memfd-bind is a command-line tool to construct a persistent +// sealed-memfd-copy of a binary, to allow administrators to amortise the cost +// of memfd cloning for runc. runc will not make its own copy of the binary if +// it detects that the binary is already a sealed-memfd-copy. +// +// Usage of this tool has a lot of caveats -- see this package's README for +// more details on what restrictions apply when using this tool. +// +// Deprecated: runc 1.2 and later use a different mechanism for protecting the +// runc binary that obviates the need for this tool. Unless you are on an old +// kernel or need to use an older runc version, this tool is no longer needed. package main import ( diff --git a/internal/linux/doc.go b/internal/linux/doc.go new file mode 100644 index 00000000000..4d1eb900108 --- /dev/null +++ b/internal/linux/doc.go @@ -0,0 +1,3 @@ +// Package linux provides minimal wrappers around Linux system calls, primarily +// to provide support for automatic EINTR-retries. +package linux diff --git a/libcontainer/apparmor/apparmor.go b/libcontainer/apparmor/apparmor.go index e2a26488e03..e58f22825f1 100644 --- a/libcontainer/apparmor/apparmor.go +++ b/libcontainer/apparmor/apparmor.go @@ -1,3 +1,6 @@ +// Package apparmor provides a minimal set of helpers to configure the AppArmor +// profile of the current process, effectively acting as a very stripped-down +// version of libapparmor. package apparmor import "errors" diff --git a/libcontainer/capabilities/capabilities.go b/libcontainer/capabilities/capabilities.go index b5963a32816..6ac6dc9663a 100644 --- a/libcontainer/capabilities/capabilities.go +++ b/libcontainer/capabilities/capabilities.go @@ -1,5 +1,6 @@ //go:build linux +// Package capabilities provides helpers for managing Linux capabilities. package capabilities import ( diff --git a/libcontainer/devices/doc.go b/libcontainer/devices/doc.go new file mode 100644 index 00000000000..a590f4495a2 --- /dev/null +++ b/libcontainer/devices/doc.go @@ -0,0 +1,4 @@ +// Package devices provides some helper functions for constructing device +// configurations for runc. These are exclusively used by higher-level runtimes +// that need to configure runc's device list based on existing devices. +package devices diff --git a/libcontainer/exeseal/doc.go b/libcontainer/exeseal/doc.go new file mode 100644 index 00000000000..56fe697a64e --- /dev/null +++ b/libcontainer/exeseal/doc.go @@ -0,0 +1,3 @@ +// Package exeseal provides mechanisms for sealing /proc/self/exe and thus +// protecting the runc binary against CVE-2019-5736-style attacks. +package exeseal diff --git a/libcontainer/integration/doc.go b/libcontainer/integration/doc.go index 87545bc99c3..843e4c9edaa 100644 --- a/libcontainer/integration/doc.go +++ b/libcontainer/integration/doc.go @@ -1,2 +1,2 @@ -// integration is used for integration testing of libcontainer +// Package integration is used for integration testing of libcontainer. package integration diff --git a/libcontainer/internal/userns/doc.go b/libcontainer/internal/userns/doc.go new file mode 100644 index 00000000000..431d65cd5ab --- /dev/null +++ b/libcontainer/internal/userns/doc.go @@ -0,0 +1,2 @@ +// Package userns provides helpers for interacting with Linux user namespaces. +package userns diff --git a/libcontainer/keys/keyctl.go b/libcontainer/keys/keyctl.go index f3a6c5343fa..ea3ee9f97f6 100644 --- a/libcontainer/keys/keyctl.go +++ b/libcontainer/keys/keyctl.go @@ -1,3 +1,4 @@ +// Package keys provides helpers for Linux keyrings. package keys import ( diff --git a/libcontainer/logs/logs.go b/libcontainer/logs/logs.go index 95deb0d6ca7..db12b851820 100644 --- a/libcontainer/logs/logs.go +++ b/libcontainer/logs/logs.go @@ -1,3 +1,5 @@ +// Package logs provides helpers for logging used within runc (specifically for +// forwarding logs from "runc init" to the main runc process). package logs import ( diff --git a/libcontainer/nsenter/nsenter.go b/libcontainer/nsenter/nsenter.go index f767864c3ff..6df410f835f 100644 --- a/libcontainer/nsenter/nsenter.go +++ b/libcontainer/nsenter/nsenter.go @@ -1,5 +1,10 @@ //go:build linux && !gccgo +// Package nsenter implements the namespace creation and joining logic of runc. +// +// This package registers a special CGo constructor that will run before the Go +// runtime boots in order to provide a mechanism for runc to operate on +// namespaces that require single-threaded program execution to work. package nsenter /* diff --git a/libcontainer/nsenter/test/escape.go b/libcontainer/nsenter/test/escape.go index f85d9e211fe..c8fffa95102 100644 --- a/libcontainer/nsenter/test/escape.go +++ b/libcontainer/nsenter/test/escape.go @@ -1,9 +1,8 @@ +// Package escapetest is part of the escape_json_string unit test. It is in a +// separate package so cgo can be used together with go test. Do not use this +// package. package escapetest -// This file is part of escape_json_string unit test. -// It is in a separate package so cgo can be used together -// with go test. - // #include // extern char *escape_json_string(char *str); // #cgo CFLAGS: -DESCAPE_TEST=1 diff --git a/libcontainer/seccomp/doc.go b/libcontainer/seccomp/doc.go new file mode 100644 index 00000000000..4e71750a3fc --- /dev/null +++ b/libcontainer/seccomp/doc.go @@ -0,0 +1,3 @@ +// Package seccomp provides runc-specific helpers for loading and managing +// seccomp profiles. +package seccomp diff --git a/libcontainer/seccomp/patchbpf/doc.go b/libcontainer/seccomp/patchbpf/doc.go new file mode 100644 index 00000000000..f2bf6e69fa9 --- /dev/null +++ b/libcontainer/seccomp/patchbpf/doc.go @@ -0,0 +1,3 @@ +// Package patchbpf provides utilities for patching libseccomp-generated cBPF +// programs in order to handle unknown syscalls and ENOSYS more gracefully. +package patchbpf diff --git a/libcontainer/system/doc.go b/libcontainer/system/doc.go new file mode 100644 index 00000000000..0326601f472 --- /dev/null +++ b/libcontainer/system/doc.go @@ -0,0 +1,2 @@ +// Package system provides wrappers for Linux system operations. +package system diff --git a/libcontainer/system/kernelversion/kernel_linux.go b/libcontainer/system/kernelversion/kernel_linux.go index ca5d4130d0c..dfbc38505b4 100644 --- a/libcontainer/system/kernelversion/kernel_linux.go +++ b/libcontainer/system/kernelversion/kernel_linux.go @@ -20,6 +20,8 @@ https://github.com/containerd/containerd/blob/v1.7.5/contrib/seccomp/kernelversion/kernel_linux.go */ +// Package kernelversion provides a method to check whether the running kernel +// version is at least a minimum kernel version. package kernelversion import ( diff --git a/libcontainer/userns/userns_deprecated.go b/libcontainer/userns/userns_deprecated.go index 31107f87295..4d328d0f254 100644 --- a/libcontainer/userns/userns_deprecated.go +++ b/libcontainer/userns/userns_deprecated.go @@ -1,3 +1,5 @@ +// Package userns provides tools for dealing with user namespaces. +// // Deprecated: use github.com/moby/sys/userns package userns diff --git a/libcontainer/utils/utils.go b/libcontainer/utils/utils.go index 442c02685bf..ee9e255e7e2 100644 --- a/libcontainer/utils/utils.go +++ b/libcontainer/utils/utils.go @@ -1,3 +1,4 @@ +// Package utils provides general helper utilities used in libcontainer. package utils import ( diff --git a/main.go b/main.go index eb64ee9b314..e9ed5a47ded 100644 --- a/main.go +++ b/main.go @@ -1,3 +1,6 @@ +// runc is a command line client for running applications packaged according to +// the Open Container Initiative (OCI) format and is a compliant implementation +// of the Open Container Initiative specification. package main import ( @@ -55,8 +58,8 @@ const ( usage = `Open Container Initiative runtime runc is a command line client for running applications packaged according to -the Open Container Initiative (OCI) format and is a compliant implementation of the -Open Container Initiative specification. +the Open Container Initiative (OCI) format and is a compliant implementation of +the Open Container Initiative specification. runc integrates well with existing process supervisors to provide a production container runtime environment for applications. It can be used with your diff --git a/tests/cmd/fs-idmap/fs-idmap.go b/tests/cmd/fs-idmap/fs-idmap.go index 4593490f371..70068bc09f7 100644 --- a/tests/cmd/fs-idmap/fs-idmap.go +++ b/tests/cmd/fs-idmap/fs-idmap.go @@ -1,3 +1,7 @@ +// fs-idmap is a command-line tool to detect if a filesystem associated with a +// given path supports id-mapped mounts. +// +// This tool is only intended to be used within runc's integration tests. package main import ( diff --git a/tests/cmd/key_label/key_label.go b/tests/cmd/key_label/key_label.go index e12deca53f7..bd1ba7d1503 100644 --- a/tests/cmd/key_label/key_label.go +++ b/tests/cmd/key_label/key_label.go @@ -1,3 +1,10 @@ +// key_label is a simple program to print the current session keyring name and +// its security label, to be run inside container (see selinux.bats). Can be +// thought of poor man's keyctl. Written in Go so we can have a static binary +// (a program in C would require libkeyutils which is usually provided only as +// a dynamic library). +// +// This tool is only intended to be used within runc's integration tests. package main import ( @@ -7,11 +14,6 @@ import ( "golang.org/x/sys/unix" ) -// This is a simple program to print the current session keyring name and its -// security label, to be run inside container (see selinux.bats). Can be -// thought of poor man's keyctl. Written in Go so we can have a static binary -// (a program in C would require libkeyutils which is usually provided only as -// a dynamic library). func main() { id, err := unix.KeyctlGetKeyringID(unix.KEY_SPEC_SESSION_KEYRING, false) if err != nil { diff --git a/tests/cmd/pidfd-kill/pidfd-kill.go b/tests/cmd/pidfd-kill/pidfd-kill.go index 764fa883a2e..f609ee272a6 100644 --- a/tests/cmd/pidfd-kill/pidfd-kill.go +++ b/tests/cmd/pidfd-kill/pidfd-kill.go @@ -1,3 +1,7 @@ +// pidfd-kill is a command-line tool to send signals to processes using pidfds +// passed through a unix socket. +// +// This tool is only intended to be used within runc's integration tests. package main import ( diff --git a/tests/cmd/recvtty/recvtty.go b/tests/cmd/recvtty/recvtty.go index 5e5720cc521..135ad2290c9 100644 --- a/tests/cmd/recvtty/recvtty.go +++ b/tests/cmd/recvtty/recvtty.go @@ -14,6 +14,14 @@ * limitations under the License. */ +// recvtty is a sample implementation of the consumer side of the +// --console-socket interface for runc. It supports forwarding console events +// to and from the container process, as well as acting like a /dev/null +// black-hole. +// +// This tool is only really intended to be used within runc's integration +// tests, but can be used as an example of how the --console-socket protocol +// works. package main import ( diff --git a/tests/cmd/remap-rootfs/remap-rootfs.go b/tests/cmd/remap-rootfs/remap-rootfs.go index b0bfebfba94..a9439b70cbc 100644 --- a/tests/cmd/remap-rootfs/remap-rootfs.go +++ b/tests/cmd/remap-rootfs/remap-rootfs.go @@ -1,3 +1,8 @@ +// remap-rootfs is a command-line tool to remap the ownership of an OCI +// bundle's rootfs to match the user namespace id-mapping of the bundle's +// config.json. +// +// This tool is only intended to be used within runc's integration tests. package main import ( diff --git a/tests/cmd/sd-helper/helper.go b/tests/cmd/sd-helper/helper.go index 0820c2ef9d0..ee24f4eb869 100644 --- a/tests/cmd/sd-helper/helper.go +++ b/tests/cmd/sd-helper/helper.go @@ -1,3 +1,7 @@ +// sd-helper is a command-line tool to provide some very minimal helpers to +// communicate with systemd. +// +// This tool is only intended to be used within runc's integration tests. package main import ( diff --git a/tests/cmd/seccompagent/seccompagent.go b/tests/cmd/seccompagent/seccompagent.go index e9cc72303b3..eeb00e82563 100644 --- a/tests/cmd/seccompagent/seccompagent.go +++ b/tests/cmd/seccompagent/seccompagent.go @@ -1,5 +1,10 @@ //go:build linux && seccomp +// seccompagent is an example implementation of a seccomp-agent for the seccomp +// user notification feature. It intercepts a handful of system calls and +// emulates them. +// +// This tool is only intended to be used within runc's integration tests. package main import ( diff --git a/types/events.go b/types/events.go index 4d8782782ec..9dac1cd5d77 100644 --- a/types/events.go +++ b/types/events.go @@ -1,3 +1,5 @@ +// Package types defines the types used for the cgroup-related events APIs +// provided by "runc events". package types import (