From 1712af0e80eecf17be40d0417bc5f22491d4c54b Mon Sep 17 00:00:00 2001 From: Adrian Reber Date: Tue, 6 Aug 2019 18:11:13 +0000 Subject: [PATCH] man: fix man-pages The man-pages are using pre-formatted section to display the options for all commands. The result on my system never looked correct: OPTIONS --bundle value, -b value path to the root [...] --console-socket value path to an AF_UNIX [...] The first line was always indented less than the other lines. This commit makes the option block a pre-formatted block (as intended???) by using 4 spaces instead of 3 spaces. In addition the man-pages did not specify their name and section correctly. This adds something like '% runc-run "8"' to all man-pages to have correct title 'runc-run(8)' instead of 'NAME()' and it also adds the section to the title: 'System Manager's Manual'. This also fixes the use of '>' and '<' at multiple places. The markdown source files were using "" and similar which was (most of the time) rendered as '""'. On some systems it was rendered correctly. Signed-off-by: Adrian Reber --- man/runc-checkpoint.8.md | 36 +++++++++++++------------ man/runc-create.8.md | 18 +++++++------ man/runc-delete.8.md | 8 +++--- man/runc-events.8.md | 10 ++++--- man/runc-exec.8.md | 38 +++++++++++++------------- man/runc-kill.8.md | 10 ++++--- man/runc-list.8.md | 6 +++-- man/runc-pause.8.md | 6 +++-- man/runc-ps.8.md | 8 +++--- man/runc-restore.8.md | 30 +++++++++++---------- man/runc-resume.8.md | 6 +++-- man/runc-run.8.md | 22 ++++++++------- man/runc-spec.8.md | 10 ++++--- man/runc-start.8.md | 6 +++-- man/runc-state.8.md | 6 +++-- man/runc-update.8.md | 38 +++++++++++++------------- man/runc.8.md | 58 +++++++++++++++++++++------------------- 17 files changed, 176 insertions(+), 140 deletions(-) diff --git a/man/runc-checkpoint.8.md b/man/runc-checkpoint.8.md index ffffa4e3..08e6b1fa 100644 --- a/man/runc-checkpoint.8.md +++ b/man/runc-checkpoint.8.md @@ -1,28 +1,30 @@ +% runc-checkpoint "8" + # NAME runc checkpoint - checkpoint a running container # SYNOPSIS - runc checkpoint [command options] + runc checkpoint [command options] `` -Where "" is the name for the instance of the container to be +Where "``" is the name for the instance of the container to be checkpointed. # DESCRIPTION The checkpoint command saves the state of the container instance. # OPTIONS - --image-path value path for saving criu image files - --work-path value path for saving work files and logs - --parent-path value path for previous criu image files in pre-dump - --leave-running leave the process running after checkpointing - --tcp-established allow open tcp connections - --ext-unix-sk allow external unix sockets - --shell-job allow shell jobs - --lazy-pages use userfaultfd to lazily restore memory pages - --status-fd value criu writes \0 to this FD once lazy-pages is ready - --page-server value ADDRESS:PORT of the page server - --file-locks handle file locks, for safety - --pre-dump dump container's memory information only, leave the container running after this - --manage-cgroups-mode value cgroups mode: 'soft' (default), 'full' and 'strict' - --empty-ns value create a namespace, but don't restore its properties - --auto-dedup enable auto deduplication of memory images + --image-path value path for saving criu image files + --work-path value path for saving work files and logs + --parent-path value path for previous criu image files in pre-dump + --leave-running leave the process running after checkpointing + --tcp-established allow open tcp connections + --ext-unix-sk allow external unix sockets + --shell-job allow shell jobs + --lazy-pages use userfaultfd to lazily restore memory pages + --status-fd value criu writes \0 to this FD once lazy-pages is ready + --page-server value ADDRESS:PORT of the page server + --file-locks handle file locks, for safety + --pre-dump dump container's memory information only, leave the container running after this + --manage-cgroups-mode value cgroups mode: 'soft' (default), 'full' and 'strict' + --empty-ns value create a namespace, but don't restore its properties + --auto-dedup enable auto deduplication of memory images diff --git a/man/runc-create.8.md b/man/runc-create.8.md index b4a3508c..99c0a2c0 100644 --- a/man/runc-create.8.md +++ b/man/runc-create.8.md @@ -1,10 +1,12 @@ +% runc-create "8" + # NAME runc create - create a container # SYNOPSIS - runc create [command options] + runc create [command options] `` -Where "" is your name for the instance of the container that you +Where "``" is your name for the instance of the container that you are starting. The name you provide for the container instance must be unique on your host. @@ -19,9 +21,9 @@ command(s) that get executed on start, edit the args parameter of the spec. See "runc spec --help" for more explanation. # OPTIONS - --bundle value, -b value path to the root of the bundle directory, defaults to the current directory - --console-socket value path to an AF_UNIX socket which will receive a file descriptor referencing the master end of the console's pseudoterminal - --pid-file value specify the file to write the process id to - --no-pivot do not use pivot root to jail process inside rootfs. This should be used whenever the rootfs is on top of a ramdisk - --no-new-keyring do not create a new session keyring for the container. This will cause the container to inherit the calling processes session key - --preserve-fds value Pass N additional file descriptors to the container (stdio + $LISTEN_FDS + N in total) (default: 0) + --bundle value, -b value path to the root of the bundle directory, defaults to the current directory + --console-socket value path to an AF_UNIX socket which will receive a file descriptor referencing the master end of the console's pseudoterminal + --pid-file value specify the file to write the process id to + --no-pivot do not use pivot root to jail process inside rootfs. This should be used whenever the rootfs is on top of a ramdisk + --no-new-keyring do not create a new session keyring for the container. This will cause the container to inherit the calling processes session key + --preserve-fds value Pass N additional file descriptors to the container (stdio + $LISTEN_FDS + N in total) (default: 0) diff --git a/man/runc-delete.8.md b/man/runc-delete.8.md index 42235e39..84922a0c 100644 --- a/man/runc-delete.8.md +++ b/man/runc-delete.8.md @@ -1,13 +1,15 @@ +% runc-delete "8" + # NAME runc delete - delete any resources held by the container often used with detached container # SYNOPSIS - runc delete [command options] + runc delete [command options] `` -Where "" is the name for the instance of the container. +Where "``" is the name for the instance of the container. # OPTIONS - --force, -f Forcibly deletes the container if it is still running (uses SIGKILL) + --force, -f Forcibly deletes the container if it is still running (uses SIGKILL) # EXAMPLE For example, if the container id is "ubuntu01" and runc list currently shows the diff --git a/man/runc-events.8.md b/man/runc-events.8.md index 2f7bb0ea..d998a38e 100644 --- a/man/runc-events.8.md +++ b/man/runc-events.8.md @@ -1,15 +1,17 @@ +% runc-events "8" + # NAME runc events - display container events such as OOM notifications, cpu, memory, and IO usage statistics # SYNOPSIS - runc events [command options] + runc events [command options] `` -Where "" is the name for the instance of the container. +Where "``" is the name for the instance of the container. # DESCRIPTION The events command displays information about the container. By default the information is displayed once every 5 seconds. # OPTIONS - --interval value set the stats collection interval (default: 5s) - --stats display the container's stats then exit + --interval value set the stats collection interval (default: 5s) + --stats display the container's stats then exit diff --git a/man/runc-exec.8.md b/man/runc-exec.8.md index 91bb0289..dbaaefec 100644 --- a/man/runc-exec.8.md +++ b/man/runc-exec.8.md @@ -1,11 +1,13 @@ +% runc-exec "8" + # NAME runc exec - execute new process inside the container # SYNOPSIS - runc exec [command options] -- [args...] + runc exec [command options] `` -- `` [args...] -Where "" is the name for the instance of the container and -"" is the command to be executed in the container. +Where "``" is the name for the instance of the container and +"``" is the command to be executed in the container. # EXAMPLE For example, if the container is configured to run the linux ps command the @@ -14,18 +16,18 @@ following will output a list of processes running in the container: # runc exec ps # OPTIONS - --console value specify the pty slave path for use with the container - --cwd value current working directory in the container - --env value, -e value set environment variables - --tty, -t allocate a pseudo-TTY - --user value, -u value UID (format: [:]) - --additional-gids value, -g value additional gids - --process value, -p value path to the process.json - --detach, -d detach from the container's process - --pid-file value specify the file to write the process id to - --process-label value set the asm process label for the process commonly used with selinux - --apparmor value set the apparmor profile for the process - --no-new-privs set the no new privileges value for the process - --cap value, -c value add a capability to the bounding set for the process - --no-subreaper disable the use of the subreaper used to reap reparented processes - --preserve-fds value pass N additional file descriptors to the container (stdio + $LISTEN_FDS + N in total) (default: 0) + --console value specify the pty slave path for use with the container + --cwd value current working directory in the container + --env value, -e value set environment variables + --tty, -t allocate a pseudo-TTY + --user value, -u value UID (format: [:]) + --additional-gids value, -g value additional gids + --process value, -p value path to the process.json + --detach, -d detach from the container's process + --pid-file value specify the file to write the process id to + --process-label value set the asm process label for the process commonly used with selinux + --apparmor value set the apparmor profile for the process + --no-new-privs set the no new privileges value for the process + --cap value, -c value add a capability to the bounding set for the process + --no-subreaper disable the use of the subreaper used to reap reparented processes + --preserve-fds value pass N additional file descriptors to the container (stdio + $LISTEN_FDS + N in total) (default: 0) diff --git a/man/runc-kill.8.md b/man/runc-kill.8.md index 3566e5f3..1ea579a7 100644 --- a/man/runc-kill.8.md +++ b/man/runc-kill.8.md @@ -1,14 +1,16 @@ +% runc-kill "8" + # NAME runc kill - kill sends the specified signal (default: SIGTERM) to the container's init process # SYNOPSIS - runc kill [command options] + runc kill [command options] `` `` -Where "" is the name for the instance of the container and -"" is the signal to be sent to the init process. +Where "``" is the name for the instance of the container and +"``" is the signal to be sent to the init process. # OPTIONS - --all, -a send the specified signal to all processes inside the container + --all, -a send the specified signal to all processes inside the container # EXAMPLE diff --git a/man/runc-list.8.md b/man/runc-list.8.md index f7374244..46cd5d05 100644 --- a/man/runc-list.8.md +++ b/man/runc-list.8.md @@ -1,3 +1,5 @@ +% runc-list "8" + # NAME runc list - lists containers started by runc with the given root @@ -15,5 +17,5 @@ To list containers created using a non-default value for "--root": # runc --root value list # OPTIONS - --format value, -f value select one of: table or json (default: "table") - --quiet, -q display only container IDs + --format value, -f value select one of: table or json (default: "table") + --quiet, -q display only container IDs diff --git a/man/runc-pause.8.md b/man/runc-pause.8.md index ccd2a2fc..965f7dad 100644 --- a/man/runc-pause.8.md +++ b/man/runc-pause.8.md @@ -1,10 +1,12 @@ +% runc-pause "8" + # NAME runc pause - pause suspends all processes inside the container # SYNOPSIS - runc pause + runc pause `` -Where "" is the name for the instance of the container to be +Where "``" is the name for the instance of the container to be paused. # DESCRIPTION diff --git a/man/runc-ps.8.md b/man/runc-ps.8.md index 49a2d56c..1fad4674 100644 --- a/man/runc-ps.8.md +++ b/man/runc-ps.8.md @@ -1,13 +1,15 @@ +% runc-ps "8" + # NAME runc ps - ps displays the processes running inside a container # SYNOPSIS - runc ps [command options] [ps options] + runc ps [command options] `` [ps options] # OPTIONS - --format value, -f value select one of: table(default) or json + --format value, -f value select one of: table(default) or json -The default format is table. The following will output the processes of a container +The default format is table. The following will output the processes of a container in json format: # runc ps -f json diff --git a/man/runc-restore.8.md b/man/runc-restore.8.md index 1793fb55..e475bd57 100644 --- a/man/runc-restore.8.md +++ b/man/runc-restore.8.md @@ -1,10 +1,12 @@ +% runc-restore "8" + # NAME runc restore - restore a container from a previous checkpoint # SYNOPSIS - runc restore [command options] + runc restore [command options] `` -Where "" is the name for the instance of the container to be +Where "``" is the name for the instance of the container to be restored. # DESCRIPTION @@ -12,15 +14,15 @@ restored. using the runc checkpoint command. # OPTIONS - --image-path value path to criu image files for restoring - --work-path value path for saving work files and logs - --tcp-established allow open tcp connections - --ext-unix-sk allow external unix sockets - --shell-job allow shell jobs - --file-locks handle file locks, for safety - --manage-cgroups-mode value cgroups mode: 'soft' (default), 'full' and 'strict' - --bundle value, -b value path to the root of the bundle directory - --detach, -d detach from the container's process - --pid-file value specify the file to write the process id to - --no-subreaper disable the use of the subreaper used to reap reparented processes - --no-pivot do not use pivot root to jail process inside rootfs. This should be used whenever the rootfs is on top of a ramdisk + --image-path value path to criu image files for restoring + --work-path value path for saving work files and logs + --tcp-established allow open tcp connections + --ext-unix-sk allow external unix sockets + --shell-job allow shell jobs + --file-locks handle file locks, for safety + --manage-cgroups-mode value cgroups mode: 'soft' (default), 'full' and 'strict' + --bundle value, -b value path to the root of the bundle directory + --detach, -d detach from the container's process + --pid-file value specify the file to write the process id to + --no-subreaper disable the use of the subreaper used to reap reparented processes + --no-pivot do not use pivot root to jail process inside rootfs. This should be used whenever the rootfs is on top of a ramdisk diff --git a/man/runc-resume.8.md b/man/runc-resume.8.md index 75f49238..25d342f9 100644 --- a/man/runc-resume.8.md +++ b/man/runc-resume.8.md @@ -1,10 +1,12 @@ +% runc-resume "8" + # NAME runc resume - resumes all processes that have been previously paused # SYNOPSIS - runc resume + runc resume `` -Where "" is the name for the instance of the container to be +Where "``" is the name for the instance of the container to be resumed. # DESCRIPTION diff --git a/man/runc-run.8.md b/man/runc-run.8.md index c54e3486..ad2b8b28 100644 --- a/man/runc-run.8.md +++ b/man/runc-run.8.md @@ -1,10 +1,12 @@ +% runc-run "8" + # NAME runc run - create and run a container # SYNOPSIS - runc run [command options] + runc run [command options] `` -Where "" is your name for the instance of the container that you +Where "``" is your name for the instance of the container that you are starting. The name you provide for the container instance must be unique on your host. @@ -19,11 +21,11 @@ command(s) that get executed on start, edit the args parameter of the spec. See "runc spec --help" for more explanation. # OPTIONS - --bundle value, -b value path to the root of the bundle directory, defaults to the current directory - --console-socket value path to an AF_UNIX socket which will receive a file descriptor referencing the master end of the console's pseudoterminal - --detach, -d detach from the container's process - --pid-file value specify the file to write the process id to - --no-subreaper disable the use of the subreaper used to reap reparented processes - --no-pivot do not use pivot root to jail process inside rootfs. This should be used whenever the rootfs is on top of a ramdisk - --no-new-keyring do not create a new session keyring for the container. This will cause the container to inherit the calling processes session key - --preserve-fds value Pass N additional file descriptors to the container (stdio + $LISTEN_FDS + N in total) (default: 0) + --bundle value, -b value path to the root of the bundle directory, defaults to the current directory + --console-socket value path to an AF_UNIX socket which will receive a file descriptor referencing the master end of the console's pseudoterminal + --detach, -d detach from the container's process + --pid-file value specify the file to write the process id to + --no-subreaper disable the use of the subreaper used to reap reparented processes + --no-pivot do not use pivot root to jail process inside rootfs. This should be used whenever the rootfs is on top of a ramdisk + --no-new-keyring do not create a new session keyring for the container. This will cause the container to inherit the calling processes session key + --preserve-fds value Pass N additional file descriptors to the container (stdio + $LISTEN_FDS + N in total) (default: 0) diff --git a/man/runc-spec.8.md b/man/runc-spec.8.md index 4f8e9bb9..6a181cde 100644 --- a/man/runc-spec.8.md +++ b/man/runc-spec.8.md @@ -1,3 +1,5 @@ +% runc-spec "8" + # NAME runc spec - create a new specification file @@ -45,8 +47,10 @@ already running as root, you can use sudo to give runc root privilege. For example: "sudo runc start container1" will give runc root privilege to start the container on your host. -Alternatively, you can start a rootless container, which has the ability to run without root privileges. For this to work, the specification file needs to be adjusted accordingly. You can pass the parameter --rootless to this command to generate a proper rootless spec file. +Alternatively, you can start a rootless container, which has the ability to run without root privileges. +For this to work, the specification file needs to be adjusted accordingly. +You can pass the parameter **--rootless** to this command to generate a proper rootless spec file. # OPTIONS - --bundle value, -b value path to the root of the bundle directory - --rootless generate a configuration for a rootless container + --bundle value, -b value path to the root of the bundle directory + --rootless generate a configuration for a rootless container diff --git a/man/runc-start.8.md b/man/runc-start.8.md index 89bb3ccb..e4bbacc3 100644 --- a/man/runc-start.8.md +++ b/man/runc-start.8.md @@ -1,10 +1,12 @@ +% runc-start "8" + # NAME runc start - start executes the user defined process in a created container # SYNOPSIS - runc start + runc start `` -Where "" is your name for the instance of the container that you +Where "``" is your name for the instance of the container that you are starting. The name you provide for the container instance must be unique on your host. diff --git a/man/runc-state.8.md b/man/runc-state.8.md index 80f43426..768f79f8 100644 --- a/man/runc-state.8.md +++ b/man/runc-state.8.md @@ -1,10 +1,12 @@ +% runc-state "8" + # NAME runc state - output the state of a container # SYNOPSIS - runc state + runc state `` -Where "" is your name for the instance of the container. +Where "``" is your name for the instance of the container. # DESCRIPTION The state command outputs current state information for the diff --git a/man/runc-update.8.md b/man/runc-update.8.md index 3ca0dcd2..fa269d62 100644 --- a/man/runc-update.8.md +++ b/man/runc-update.8.md @@ -1,8 +1,10 @@ +% runc-update "8" + # NAME runc update - update container resource constraints # SYNOPSIS - runc update [command options] + runc update [command options] `` # DESCRIPTION The data can be read from a file or the standard input, the @@ -34,20 +36,20 @@ Note: if data is to be read from a file or the standard input, all other options are ignored. # OPTIONS - --resources value, -r value path to the file containing the resources to update or '-' to read from the standard input - --blkio-weight value Specifies per cgroup weight, range is from 10 to 1000 (default: 0) - --cpu-period value CPU CFS period to be used for hardcapping (in usecs). 0 to use system default - --cpu-quota value CPU CFS hardcap limit (in usecs). Allowed cpu time in a given period - --cpu-rt-period value CPU realtime period to be used for hardcapping (in usecs). 0 to use system default - --cpu-rt-runtime value CPU realtime hardcap limit (in usecs). Allowed cpu time in a given period - --cpu-share value CPU shares (relative weight vs. other containers) - --cpuset-cpus value CPU(s) to use - --cpuset-mems value Memory node(s) to use - --kernel-memory value Kernel memory limit (in bytes) - --kernel-memory-tcp value Kernel memory limit (in bytes) for tcp buffer - --memory value Memory limit (in bytes) - --memory-reservation value Memory reservation or soft_limit (in bytes) - --memory-swap value Total memory usage (memory + swap); set '-1' to enable unlimited swap - --pids-limit value Maximum number of pids allowed in the container (default: 0) - --l3-cache-schema The string of Intel RDT/CAT L3 cache schema - --mem-bw-schema The string of Intel RDT/MBA memory bandwidth schema + --resources value, -r value path to the file containing the resources to update or '-' to read from the standard input + --blkio-weight value Specifies per cgroup weight, range is from 10 to 1000 (default: 0) + --cpu-period value CPU CFS period to be used for hardcapping (in usecs). 0 to use system default + --cpu-quota value CPU CFS hardcap limit (in usecs). Allowed cpu time in a given period + --cpu-rt-period value CPU realtime period to be used for hardcapping (in usecs). 0 to use system default + --cpu-rt-runtime value CPU realtime hardcap limit (in usecs). Allowed cpu time in a given period + --cpu-share value CPU shares (relative weight vs. other containers) + --cpuset-cpus value CPU(s) to use + --cpuset-mems value Memory node(s) to use + --kernel-memory value Kernel memory limit (in bytes) + --kernel-memory-tcp value Kernel memory limit (in bytes) for tcp buffer + --memory value Memory limit (in bytes) + --memory-reservation value Memory reservation or soft_limit (in bytes) + --memory-swap value Total memory usage (memory + swap); set '-1' to enable unlimited swap + --pids-limit value Maximum number of pids allowed in the container (default: 0) + --l3-cache-schema The string of Intel RDT/CAT L3 cache schema + --mem-bw-schema The string of Intel RDT/MBA memory bandwidth schema diff --git a/man/runc.8.md b/man/runc.8.md index 6d0ddff6..49df5254 100644 --- a/man/runc.8.md +++ b/man/runc.8.md @@ -1,3 +1,5 @@ +% runc "8" + # NAME runc - Open Container Initiative runtime @@ -22,38 +24,38 @@ To start a new instance of a container: # runc start [ -b bundle ] -Where "" is your name for the instance of the container that you +Where "``" is your name for the instance of the container that you are starting. The name you provide for the container instance must be unique on your host. Providing the bundle directory using "-b" is optional. The default value for "bundle" is the current directory. # COMMANDS - checkpoint checkpoint a running container - create create a container - delete delete any resources held by the container often used with detached containers - events display container events such as OOM notifications, cpu, memory, IO and network stats - exec execute new process inside the container - init initialize the namespaces and launch the process (do not call it outside of runc) - kill kill sends the specified signal (default: SIGTERM) to the container's init process - list lists containers started by runc with the given root - pause pause suspends all processes inside the container - ps displays the processes running inside a container - restore restore a container from a previous checkpoint - resume resumes all processes that have been previously paused - run create and run a container - spec create a new specification file - start executes the user defined process in a created container - state output the state of a container - update update container resource constraints - help, h Shows a list of commands or help for one command + checkpoint checkpoint a running container + create create a container + delete delete any resources held by the container often used with detached containers + events display container events such as OOM notifications, cpu, memory, IO and network stats + exec execute new process inside the container + init initialize the namespaces and launch the process (do not call it outside of runc) + kill kill sends the specified signal (default: SIGTERM) to the container's init process + list lists containers started by runc with the given root + pause pause suspends all processes inside the container + ps displays the processes running inside a container + restore restore a container from a previous checkpoint + resume resumes all processes that have been previously paused + run create and run a container + spec create a new specification file + start executes the user defined process in a created container + state output the state of a container + update update container resource constraints + help, h Shows a list of commands or help for one command # GLOBAL OPTIONS - --debug enable debug output for logging - --log value set the log file path where internal debug information is written (default: "/dev/null") - --log-format value set the format used by logs ('text' (default), or 'json') (default: "text") - --root value root directory for storage of container state (this should be located in tmpfs) (default: "/run/runc" or $XDG_RUNTIME_DIR/runc for rootless containers) - --criu value path to the criu binary used for checkpoint and restore (default: "criu") - --systemd-cgroup enable systemd cgroup support, expects cgroupsPath to be of form "slice:prefix:name" for e.g. "system.slice:runc:434234" - --rootless value enable rootless mode ('true', 'false', or 'auto') (default: "auto") - --help, -h show help - --version, -v print the version + --debug enable debug output for logging + --log value set the log file path where internal debug information is written (default: "/dev/null") + --log-format value set the format used by logs ('text' (default), or 'json') (default: "text") + --root value root directory for storage of container state (this should be located in tmpfs) (default: "/run/runc" or $XDG_RUNTIME_DIR/runc for rootless containers) + --criu value path to the criu binary used for checkpoint and restore (default: "criu") + --systemd-cgroup enable systemd cgroup support, expects cgroupsPath to be of form "slice:prefix:name" for e.g. "system.slice:runc:434234" + --rootless value enable rootless mode ('true', 'false', or 'auto') (default: "auto") + --help, -h show help + --version, -v print the version