lint/revive: add package doc comments

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 (

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

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"

libcontainer/capabilities/capabilities.go

@@ -1,5 +1,6 @@
 //go:build linux
 
+// Package capabilities provides helpers for managing Linux capabilities.
 package capabilities
 
 import (

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

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

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

libcontainer/internal/userns/doc.go

@@ -0,0 +1,2 @@
+// Package userns provides helpers for interacting with Linux user namespaces.
+package userns

libcontainer/keys/keyctl.go

@@ -1,3 +1,4 @@
+// Package keys provides helpers for Linux keyrings.
 package keys
 
 import (

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 (

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
 
 /*

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

libcontainer/seccomp/doc.go

@@ -0,0 +1,3 @@
+// Package seccomp provides runc-specific helpers for loading and managing
+// seccomp profiles.
+package seccomp

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

libcontainer/system/doc.go

@@ -0,0 +1,2 @@
+// Package system provides wrappers for Linux system operations.
+package system

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 (

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
 

libcontainer/utils/utils.go

@@ -1,3 +1,4 @@
+// Package utils provides general helper utilities used in libcontainer.
 package utils
 
 import (

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

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 (

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 {

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 (

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 (

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 (

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 (

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 (

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 (