merge #4904 into opencontainers/runc:main

cyphar · cyphar · commit 984b35389c4c · 2025-10-03T16:21:42.000+10:00
Aleksa Sarai (1):
  lint/revive: add package doc comments

LGTMs: lifubang kolyshkin
diff --git 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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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 <stdlib.h>
 // extern char *escape_json_string(char *str);
 // #cgo CFLAGS: -DESCAPE_TEST=1
diff --git a/libcontainer/seccomp/doc.go 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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -1,3 +1,4 @@
+// Package utils provides general helper utilities used in libcontainer.
 package utils
 
 import (
diff --git 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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -1,3 +1,5 @@
+// Package types defines the types used for the cgroup-related events APIs
+// provided by "runc events".
 package types
 
 import (

Original file line number	Diff line number	Diff line change
`@@ -0,0 +1,3 @@`
	`1`	`+// Package linux provides minimal wrappers around Linux system calls, primarily`
	`2`	`+// to provide support for automatic EINTR-retries.`
	`3`	`+package linux`
Original file line number	Diff line number	Diff line change
`@@ -0,0 +1,3 @@`
	`1`	`+// Package exeseal provides mechanisms for sealing /proc/self/exe and thus`
	`2`	`+// protecting the runc binary against CVE-2019-5736-style attacks.`
	`3`	`+package exeseal`
Original file line number	Diff line number	Diff line change
`@@ -1,2 +1,2 @@`
`1`		`-// integration is used for integration testing of libcontainer`
	`1`	`+// Package integration is used for integration testing of libcontainer.`
`2`	`2`	`package integration`
Original file line number	Diff line number	Diff line change
`@@ -0,0 +1,2 @@`
	`1`	`+// Package userns provides helpers for interacting with Linux user namespaces.`
	`2`	`+package userns`
Original file line number	Diff line number	Diff line change
`@@ -1,3 +1,4 @@`
	`1`	`+// Package keys provides helpers for Linux keyrings.`
`1`	`2`	`package keys`
`2`	`3`
`3`	`4`	`import (`
Original file line number	Diff line number	Diff line change
`@@ -1,3 +1,5 @@`
	`1`	`+// Package logs provides helpers for logging used within runc (specifically for`
	`2`	`+// forwarding logs from "runc init" to the main runc process).`
`1`	`3`	`package logs`
`2`	`4`
`3`	`5`	`import (`