From dfc0f0695acdd5ee3bf95e99d3acb88994c5fa17 Mon Sep 17 00:00:00 2001 From: Kir Kolyshkin Date: Tue, 15 Jun 2021 17:50:24 -0700 Subject: [PATCH] man/*: revamp Current runc man pages are ugly (no proper man page formatting) and very short (mostly just a copy-paste from the "runc --help" output. They are also somewhat obsoleted as not all CLI updates were propagated to man/*. This commits makes the first step to solving this. In short: - added some more information about some options; - lots of formatting fixes; - use references to other man pages and web pages; - fix SYNOPSYS (formatting, mostly); - removed the repeated description of from every page; - added SEE ALSO; - something else I forgot. Signed-off-by: Kir Kolyshkin --- man/runc-checkpoint.8.md | 88 ++++++++++++++++----- man/runc-create.8.md | 55 ++++++++----- man/runc-delete.8.md | 25 +++--- man/runc-events.8.md | 22 ++++-- man/runc-exec.8.md | 85 ++++++++++++++------ man/runc-kill.8.md | 29 ++++--- man/runc-list.8.md | 42 +++++++--- man/runc-pause.8.md | 18 +++-- man/runc-ps.8.md | 25 ++++-- man/runc-restore.8.md | 107 ++++++++++++++++--------- man/runc-resume.8.md | 18 +++-- man/runc-run.8.md | 60 ++++++++------ man/runc-spec.8.md | 95 +++++++++++++---------- man/runc-start.8.md | 15 ++-- man/runc-state.8.md | 14 ++-- man/runc-update.8.md | 129 +++++++++++++++++++----------- man/runc.8.md | 164 ++++++++++++++++++++++++++++++--------- 17 files changed, 674 insertions(+), 317 deletions(-) diff --git a/man/runc-checkpoint.8.md b/man/runc-checkpoint.8.md index 08e6b1fa68a..373259d4ccf 100644 --- a/man/runc-checkpoint.8.md +++ b/man/runc-checkpoint.8.md @@ -1,30 +1,76 @@ % runc-checkpoint "8" # NAME - runc checkpoint - checkpoint a running container +**runc-checkpoint** - checkpoint a running container # SYNOPSIS - runc checkpoint [command options] `` - -Where "``" is the name for the instance of the container to be -checkpointed. +**runc checkpoint** [_option_ ...] _container-id_ # DESCRIPTION - The checkpoint command saves the state of the container instance. +The **checkpoint** command saves the state of the running container instance +with the help of **criu**(8) tool, to be restored later. # 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** _path_ +: Set path for saving criu image files. The default is *./checkpoint*. + +**--work-path** _path_ +: Set path for saving criu work files and logs. The default is to reuse the +image files directory. + +**--parent-path** _path_ +: Set path for previous criu image files, in pre-dump. + +**--leave-running** +: Leave the process running after checkpointing. + +**--tcp-established** +: Allow checkpoint/restore of established TCP connections. See +[criu --tcp-establised option](https://criu.org/CLI/opt/--tcp-established). + +**--ext-unix-sk** +: Allow checkpoint/restore of external unix sockets. See +[criu --ext-unix-sk option](https://criu.org/CLI/opt/--ext-unix-sk). + +**--shell-job** +: Allow checkpoint/restore of shell jobs. + +**--lazy-pages** +: Use lazy migration mechanism. See +[criu --lazy-pages option](https://criu.org/CLI/opt/--lazy-pages). + +**--status-fd** _fd_ +: Pass a file descriptor _fd_ to **criu**. Once **lazy-pages** server is ready, +**criu** writes **\0** (a zero byte) to that _fd_. Used together with +**--lazy-pages**. + +**--page-server** _IP-address_:_port_ +: Start a page server at the specified _IP-address_ and _port_. This is used +together with **criu lazy-pages**. See +[criu lazy migration](https://criu.org/Lazy_migration). + +**--file-locks** +: Allow checkpoint/restore of file locks. See +[criu --file-locks option](https://criu.org/CLI/opt/--file-locks). + +**--pre-dump** +: Do a pre-dump, i.e. dump container's memory information only, leaving the +container running. See [criu iterative migration](https://criu.org/Iterative_migration). + +**--manage-cgroups-mode** **soft**|**full**|**strict**. +: Cgroups mode. Default is **soft**. See +[criu --manage-cgroups option](https://criu.org/CLI/opt/--manage-cgroups). + +**--empty-ns** _namespace_ +: Checkpoint a _namespace_, but don't save its properties. See +[criu --empty-ns option](https://criu.org/CLI/opt/--empty-ns). + +**--auto-dedup** +: Enable auto deduplication of memory images. See +[criu --auto-dedup option](https://criu.org/CLI/opt/--auto-dedup). + +# SEE ALSO +**criu**(8), +**runc-restore**(8), +**runc**(8), +**criu**(8). diff --git a/man/runc-create.8.md b/man/runc-create.8.md index 99c0a2c09f3..cfe6d17dc57 100644 --- a/man/runc-create.8.md +++ b/man/runc-create.8.md @@ -1,29 +1,44 @@ % runc-create "8" # NAME - runc create - create a container +**runc-create** - create a container # SYNOPSIS - runc create [command options] `` - -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. +**runc create** [_option_ ...] _container-id_ # DESCRIPTION - The create command creates an instance of a container for a bundle. The bundle -is a directory with a specification file named "config.json" and a root -filesystem. - -The specification file includes an args parameter. The args parameter is used -to specify command(s) that get run when the container is started. To change the -command(s) that get executed on start, edit the args parameter of the spec. See -"runc spec --help" for more explanation. +The **create** command creates an instance of a container from a bundle. +The bundle is a directory with a specification file named _config.json_, +and a root filesystem. # 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**|**-b** _path_ +: Path to the root of the bundle directory. Default is current directory. + +**--console-socket** _path_ +: Path to an **AF_UNIX** socket which will receive a file descriptor +referencing the master end of the console's pseudoterminal. See +[docs/terminals](https://github.com/opencontainers/runc/blob/master/docs/terminals.md). + +**--pid-file** _path_ +: Specify the file to write the initial container process' PID to. + +**--no-pivot** +: Do not use pivot root to jail process inside rootfs. This should not be used +except in exceptional circumstances, and may be unsafe from the security +standpoint. + +**--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** _N_ +: Pass _N_ additional file descriptors to the container (**stdio** + +**$LISTEN_FDS** + _N_ in total). Default is **0**. + +# SEE ALSO + +**runc-spec**(8), +**runc-start**(8), +**runc**(8). diff --git a/man/runc-delete.8.md b/man/runc-delete.8.md index 84922a0c08a..249528c197d 100644 --- a/man/runc-delete.8.md +++ b/man/runc-delete.8.md @@ -1,19 +1,24 @@ % runc-delete "8" # NAME - runc delete - delete any resources held by the container often used with detached container +**runc-delete** - delete any resources held by the container # SYNOPSIS - runc delete [command options] `` - -Where "``" is the name for the instance of the container. +**runc delete** [**--force**|**-f**] _container-id_ # OPTIONS - --force, -f Forcibly deletes the container if it is still running (uses SIGKILL) +**--force**|**-f** +: Forcibly delete the running container, using **SIGKILL** **signal**(7) +to stop it first. + +# EXAMPLES +If the container id is **ubuntu01** and **runc list** currently shows +its status as **stopped**, the following will delete resources held for +**ubuntu01**, removing it from the **runc list**: + + # runc delete ubuntu01 -# EXAMPLE -For example, if the container id is "ubuntu01" and runc list currently shows the -status of "ubuntu01" as "stopped" the following will delete resources held for -"ubuntu01" removing "ubuntu01" from the runc list of containers: +# SEE ALSO - # runc delete ubuntu01 +**runc-kill**(8), +**runc**(8). diff --git a/man/runc-events.8.md b/man/runc-events.8.md index d998a38ef90..eab7865f15a 100644 --- a/man/runc-events.8.md +++ b/man/runc-events.8.md @@ -1,17 +1,23 @@ % runc-events "8" # NAME - runc events - display container events such as OOM notifications, cpu, memory, and IO usage statistics +**runc-events** - display container events and statistics. # SYNOPSIS - runc events [command options] `` - -Where "``" is the name for the instance of the container. +**runc events** [_option_ ...] _container-id_ # DESCRIPTION - The events command displays information about the container. By default the -information is displayed once every 5 seconds. +The **events** command displays information about the container. By default, +it works continuously, displaying stats every 5 seconds, and container events +as they occur. # OPTIONS - --interval value set the stats collection interval (default: 5s) - --stats display the container's stats then exit +**--interval** _time_ +: Set the stats collection interval. Default is **5s**. + +**--stats** +: Show the container's stats once then exit. + +# SEE ALSO + +**runc**(8). diff --git a/man/runc-exec.8.md b/man/runc-exec.8.md index dbaaefec51e..dafd03dcb8c 100644 --- a/man/runc-exec.8.md +++ b/man/runc-exec.8.md @@ -1,33 +1,70 @@ % runc-exec "8" # NAME - runc exec - execute new process inside the container +**runc-exec** - execute new process inside the container # SYNOPSIS - runc exec [command options] `` -- `` [args...] +**runc exec** [_option_ ...] _container-id_ [--] _command_ [_arg_ ...] -Where "``" is the name for the instance of the container and -"``" is the command to be executed in the container. +**runc exec** [_option_ ...] **-p** _process.json_ _container-id_ -# EXAMPLE -For example, if the container is configured to run the linux ps command the -following will output a list of processes running in the container: +# OPTIONS +**--console-socket** _path_ +: Path to an **AF_UNIX** socket which will receive a file descriptor +referencing the master end of the console's pseudoterminal. See +[docs/terminals](https://github.com/opencontainers/runc/blob/master/docs/terminals.md). - # runc exec ps +**--cwd** _path_ +: Change to _path_ in the container before executing the command. -# 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) +**--env**|**-e** _name_=_value_ +: Set an environment variable _name_ to _value_. Can be specified multiple times. + +**--tty**|**-t** +: Allocate a pseudo-TTY. + +**--user**|**-u** _uid_[:_gid_] +: Run the _command_ as a user (and, optionally, group) specified by _uid_ (and +_gid_). + +**--additional-gids**|**-g** _gid_ +: Add additional group IDs. Can be specified multiple times. + +**--process**|**-p** _process.json_ +: Instead of specifying all the exec parameters directly on the command line, +get them from a _process.json_, a JSON file containing the process +specification as defined by the +[OCI runtime spec](https://github.com/opencontainers/runtime-spec/blob/master/config.md#process). + +**--detach**|**-d** +: Detach from the container's process. + +**--pid-file** _path_ +: Specify the file to write the container process' PID to. + +**--process-label** _label_ +: Set the asm process label for the process commonly used with **selinux**(7). + +**--apparmor** _profile_ +: Set the **apparmor**(7) _profile_ for the process. + +**--no-new-privs** +: Set the "no new privileges" value for the process. + +**--cap** _cap_ +: Add a capability to the bounding set for the process. Can be specified +multiple times. + +**--preserve-fds** _N_ +: Pass _N_ additional file descriptors to the container (**stdio** + +**$LISTEN_FDS** + _N_ in total). Default is **0**. + +# EXAMPLES +If the container can run **ps**(1) command, the following +will output a list of processes running in the container: + + # runc exec ps + +# SEE ALSO + +**runc**(8). diff --git a/man/runc-kill.8.md b/man/runc-kill.8.md index 1ea579a7861..c18fe9442da 100644 --- a/man/runc-kill.8.md +++ b/man/runc-kill.8.md @@ -1,20 +1,31 @@ % runc-kill "8" # NAME - runc kill - kill sends the specified signal (default: SIGTERM) to the container's init process +**runc-kill** - send a specified signal to container # SYNOPSIS - runc kill [command options] `` `` +**runc kill** [**--all**|**-a**] _container-id_ [_signal_] -Where "``" is the name for the instance of the container and -"``" is the signal to be sent to the init process. +# DESCRIPTION + +By default, **runc kill** sends **SIGTERM** to the container's initial process +only. + +A different signal can be specified either by its name (with or without the +**SIG** prefix), or its numeric value. Use **kill**(1) with **-l** option +to list available signals. # OPTIONS - --all, -a send the specified signal to all processes inside the container +**--all**|**-a** +: Send the signal to all processes inside the container. + +# EXAMPLES + +The following will send a **KILL** signal to the init process of the +**ubuntu01** container: -# EXAMPLE + # runc kill ubuntu01 KILL -For example, if the container id is "ubuntu01" the following will send a "KILL" -signal to the init process of the "ubuntu01" container: +# SEE ALSO - # runc kill ubuntu01 KILL +**runc**(1). diff --git a/man/runc-list.8.md b/man/runc-list.8.md index 46cd5d05e8d..43545d51982 100644 --- a/man/runc-list.8.md +++ b/man/runc-list.8.md @@ -1,21 +1,39 @@ % runc-list "8" # NAME - runc list - lists containers started by runc with the given root +**runc-list** - lists containers # SYNOPSIS - runc list [command options] +**runc list** [_option_ ...] -# EXAMPLE -Where the given root is specified via the global option "--root" -(default: "/run/runc"). +# DESCRIPTION -To list containers created via the default "--root": - # runc list - -To list containers created using a non-default value for "--root": - # runc --root value list +The **list** commands lists containers. Note that a global **--root** +option can be specified to change the default root. For the description +of **--root**, see **runc**(8). # OPTIONS - --format value, -f value select one of: table or json (default: "table") - --quiet, -q display only container IDs +**--format**|**-f** **table**|**json** +: Specify the format. Default is **table**. The **json** format provides +more details. + +**--quiet**|**-q** +: Only display container IDs. + +# EXAMPLES +To list containers created with the default root: + + # runc list + +To list containers in a human-readable JSON (with the help of **jq**(1) +utility): + + # runc list -f json | jq + +To list containers created with the root of **/tmp/myroot**: + + # runc --root /tmp/myroot + +# SEE ALSO + +**runc**(8). diff --git a/man/runc-pause.8.md b/man/runc-pause.8.md index 965f7dad823..e6e838189fa 100644 --- a/man/runc-pause.8.md +++ b/man/runc-pause.8.md @@ -1,14 +1,18 @@ % runc-pause "8" # NAME - runc pause - pause suspends all processes inside the container +**runc-pause** - suspend all processes inside the container # SYNOPSIS - runc pause `` - -Where "``" is the name for the instance of the container to be -paused. +**runc pause** _container-id_ # DESCRIPTION - The pause command suspends all processes in the instance of the container. -Use runc list to identify instances of containers and their current status. +The **pause** command suspends all processes in the instance of the container +identified by _container-id_. + +Use **runc list** to identify instances of containers and their current status. + +# SEE ALSO +**runc-list**(8), +**runc-resume**(8), +**runc**(8). diff --git a/man/runc-ps.8.md b/man/runc-ps.8.md index 1fad46749b2..9f6cf9632de 100644 --- a/man/runc-ps.8.md +++ b/man/runc-ps.8.md @@ -1,15 +1,26 @@ % runc-ps "8" # NAME - runc ps - ps displays the processes running inside a container +**runc-ps** - display the processes inside a container # SYNOPSIS - runc ps [command options] `` [ps options] +**runc ps** [_option_ ...] _container-id_ [_ps-option_ ...] -# OPTIONS - --format value, -f value select one of: table(default) or json +# DESCRIPTION +The command **ps** is a wrapper around the stock **ps**(1) utility, +which filters its output to only contain processes belonging to a specified +_container-id_. Therefore, the PIDs shown are the host PIDs. + +Any **ps**(1) options can be used, but some might break the filtering. +In particular, if PID column is not available, an error is returned, +and if there are columns with values containing spaces before the PID +column, the result is undefined. -The default format is table. The following will output the processes of a container -in json format: +# OPTIONS +**--format**|**-f** **table**|**json** +: Output format. Default is **table**. The **json** format shows a mere array +of PIDs belonging to a container; if used, all **ps** options are gnored. - # runc ps -f json +# SEE ALSO +**runc-list**(8), +**runc**(8). diff --git a/man/runc-restore.8.md b/man/runc-restore.8.md index 3af42b47250..f49aa62b7df 100644 --- a/man/runc-restore.8.md +++ b/man/runc-restore.8.md @@ -1,44 +1,81 @@ % runc-restore "8" # NAME - runc restore - restore a container from a previous checkpoint +**runc-restore** - restore a container from a previous checkpoint # SYNOPSIS - runc restore [command options] `` - -Where "``" is the name for the instance of the container to be -restored. +**runc restore** [_option_ ...] _container-id_ # DESCRIPTION - Restores the saved state of the container instance that was previously saved -using the runc checkpoint command. +Restores the container instance from a previously performed **runc checkpoint**. # 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 - --empty-ns value create a namespace, but don't restore its properties - --auto-dedup enable auto deduplication of memory images - --lazy-pages use userfaultfd to lazily restore memory pages - --lsm-profile value Specify an LSM profile to be used during restore in the form of TYPE:NAME. - -## OPTION DETAILS - -**--lsm-profile** - -Specify an LSM profile to be used during restore in the form of TYPE:NAME. - -`TYPE` can either be *apparamor* or *selinux* and is followed by *:* and a -valid LSM label. -``` -runc restore --lsm-profile "selinux:system_u:system_r:container_t:s0:c82,c137" -``` +**--console-socket** _path_ +: Path to an **AF_UNIX** socket which will receive a file descriptor +referencing the master end of the console's pseudoterminal. See +[docs/terminals](https://github.com/opencontainers/runc/blob/master/docs/terminals.md). + +**--image-path** _path_ +: Set path to get criu image files to restore from. + +**--work-path** _path_ +: Set path for saving criu work files and logs. The default is to reuse the +image files directory. + +**--tcp-established** +: Allow checkpoint/restore of established TCP connections. See +[criu --tcp-establised option](https://criu.org/CLI/opt/--tcp-established). + +**--ext-unix-sk** +: Allow checkpoint/restore of external unix sockets. See +[criu --ext-unix-sk option](https://criu.org/CLI/opt/--ext-unix-sk). + +**--shell-job** +: Allow checkpoint/restore of shell jobs. + +**--file-locks** +: Allow checkpoint/restore of file locks. See +[criu --file-locks option](https://criu.org/CLI/opt/--file-locks). + +**--manage-cgroups-mode** **soft**|**full**|**strict**. +: Cgroups mode. Default is **soft**. See +[criu --manage-cgroups option](https://criu.org/CLI/opt/--manage-cgroups). + +**--bundle**|**-b** _path_ +: Path to the root of the bundle directory. Default is current directory. + +**--detach**|**-d** +: Detach from the container's process. + +**--pid-file** _path_ +: Specify the file to write the initial container process' PID 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 not be used +except in exceptional circumstances, and may be unsafe from the security +standpoint. + +**--empty-ns** _namespace_ +: Create a _namespace_, but don't restore its properties. See +[criu --empty-ns option](https://criu.org/CLI/opt/--empty-ns). + +**--auto-dedup** +: Enable auto deduplication of memory images. See +[criu --auto-dedup option](https://criu.org/CLI/opt/--auto-dedup). + +**--lazy-pages** +: Use lazy migration mechanism. This requires a running **criu lazy-pages** +daemon. See [criu --lazy-pages option](https://criu.org/CLI/opt/--lazy-pages). + +**--lsm-profile** _type_:_label_ +: Specify an LSM profile to be used during restore. Here _type_ can either be +**apparamor** or **selinux**, and _label_ is a valid LSM label. For example, +**--lsm-profile "selinux:system_u:system_r:container_t:s0:c82,c137"**. + +# SEE ALSO +**criu**(8), +**runc-checkpoint**(8), +**runc**(8). diff --git a/man/runc-resume.8.md b/man/runc-resume.8.md index 25d342f9260..cb809d0c37c 100644 --- a/man/runc-resume.8.md +++ b/man/runc-resume.8.md @@ -1,14 +1,18 @@ % runc-resume "8" # NAME - runc resume - resumes all processes that have been previously paused +**runc-resume** - resume all processes that have been previously paused # SYNOPSIS - runc resume `` - -Where "``" is the name for the instance of the container to be -resumed. +**runc resume** _container-id_ # DESCRIPTION - The resume command resumes all processes in the instance of the container. -Use runc list to identify instances of containers and their current status. +The **resume** command resumes all processes in the instance of the container +identified by _container-id_. + +Use **runc list** to identify instances of containers and their current status. + +# SEE ALSO +**runc-list**(8), +**runc-pause**(8), +**runc**(8). diff --git a/man/runc-run.8.md b/man/runc-run.8.md index ad2b8b28764..216649ae4b5 100644 --- a/man/runc-run.8.md +++ b/man/runc-run.8.md @@ -1,31 +1,47 @@ % runc-run "8" # NAME - runc run - create and run a container +**runc-run** - create and start a container # SYNOPSIS - runc run [command options] `` - -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. +**runc run** [_option_ ...] _container-id_ # DESCRIPTION - The run command creates an instance of a container for a bundle. The bundle -is a directory with a specification file named "config.json" and a root -filesystem. - -The specification file includes an args parameter. The args parameter is used -to specify command(s) that get run when the container is started. To change the -command(s) that get executed on start, edit the args parameter of the spec. See -"runc spec --help" for more explanation. +The **run** command creates an instance of a container from a bundle, and +starts it. You can think of **run** as a shortcut for **create** followed by +**start**. # 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**|**-b** _path_ +: Path to the root of the bundle directory. Default is current directory. + +**--console-socket** _path_ +: Path to an **AF_UNIX** socket which will receive a file descriptor +referencing the master end of the console's pseudoterminal. See +[docs/terminals](https://github.com/opencontainers/runc/blob/master/docs/terminals.md). + +**--detach**|**-d** +: Detach from the container's process. + +**--pid-file** _path_ +: Specify the file to write the initial container process' PID 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 not be used +except in exceptional circumstances, and may be unsafe from the security +standpoint. + +**--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** _N_ +: Pass _N_ additional file descriptors to the container (**stdio** + +**$LISTEN_FDS** + _N_ in total). Default is **0**. + +# SEE ALSO + +**runc**(8). diff --git a/man/runc-spec.8.md b/man/runc-spec.8.md index 6a181cde49d..8e7dbfc1908 100644 --- a/man/runc-spec.8.md +++ b/man/runc-spec.8.md @@ -1,56 +1,71 @@ % runc-spec "8" # NAME - runc spec - create a new specification file +**runc-spec** - create a new specification file # SYNOPSIS - runc spec [command options] [arguments...] +**runc spec** [_option_ ...] # DESCRIPTION - The spec command creates the new specification file named "config.json" for +The **spec** command creates the new specification file named _config.json_ for the bundle. The spec generated is just a starter file. Editing of the spec is required to -achieve desired results. For example, the newly generated spec includes an args -parameter that is initially set to call the "sh" command when the container is -started. Calling "sh" may work for an ubuntu container or busybox, but will not -work for containers that do not include the "sh" program. - -# EXAMPLE - To run docker's hello-world container one needs to set the args parameter -in the spec to call hello. This can be done using the sed command or a text -editor. The following commands create a bundle for hello-world, change the -default args parameter in the spec from "sh" to "/hello", then run the hello -command in a new hello-world container named container1: - - mkdir hello - cd hello - docker pull hello-world - docker export $(docker create hello-world) > hello-world.tar - mkdir rootfs - tar -C rootfs -xf hello-world.tar - runc spec - sed -i 's;"sh";"/hello";' config.json - runc start container1 - -In the start command above, "container1" is the name for the instance of the +achieve desired results. For example, the newly generated spec includes an +**args** parameter that is initially set to call the **sh** command when the +container is started. Calling **sh** may work for an ubuntu container or busybox, +but will not work for containers that do not include the **sh** binary. + +# OPTIONS +**--bundle**|**-b** _path_ +: Set _path_ to the root of the bundle directory. + +**--rootless** +: Generate a configuration for a rootless container. Note this option +is entirely different from the global **--rootless** option. + +# EXAMPLES +To run a simple "hello-world" container, one needs to set the **args** +parameter in the spec to call hello. This can be done using **sed**(1), +**jq**(1), or a text editor. + +The following commands will: + - create a bundle for hello-world; + - change the command to run in a container to **/hello** using **jq**(1); + - run the **hello** command in a new hello-world container named **container1**. + + mkdir hello + cd hello + docker pull hello-world + docker export $(docker create hello-world) > hello-world.tar + mkdir rootfs + tar -C rootfs -xf hello-world.tar + runc spec + jq '.process.args |= ["/hello"]' < config.json > new.json + mv -f new.json config.json + runc run container1 + +In the **run** command above, **container1** is the 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. -An alternative for generating a customized spec config is to use "oci-runtime-tool", the -sub-command "oci-runtime-tool generate" has lots of options that can be used to do any -customizations as you want, see [runtime-tools](https://github.com/opencontainers/runtime-tools) -to get more information. +An alternative for generating a customized spec config is to use +**oci-runtime-tool**; its sub-command **oci-runtime-tool generate** has lots of +options that can be used to do any customizations as you want. See +[runtime-tools](https://github.com/opencontainers/runtime-tools) to get more +information. -When starting a container through runc, runc needs root privilege. If not -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. +When starting a container through **runc**, the latter usually needs root +privileges. If not already running as root, you can use **sudo**(8), for +example: -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. + sudo runc start container1 -# OPTIONS - --bundle value, -b value path to the root of the bundle directory - --rootless generate a configuration for a rootless container +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 **--rootless** option to this command +to generate a proper rootless spec file. + +# SEE ALSO +**runc-run**(8), +**runc**(8). diff --git a/man/runc-start.8.md b/man/runc-start.8.md index e4bbacc3f87..fa72ca5b775 100644 --- a/man/runc-start.8.md +++ b/man/runc-start.8.md @@ -1,14 +1,15 @@ % runc-start "8" # NAME - runc start - start executes the user defined process in a created container +**runc start** - start a previously created container # SYNOPSIS - runc start `` - -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. +**runc start** _container-id_ # DESCRIPTION - The start command executes the user defined process in a created container. +The **start** command executes the process defined in _config.json_ in a +container previously created by **runc-create**(8). + +# SEE ALSO +**runc-create**(8), +**runc**(8). diff --git a/man/runc-state.8.md b/man/runc-state.8.md index 768f79f8b54..727b80aa131 100644 --- a/man/runc-state.8.md +++ b/man/runc-state.8.md @@ -1,13 +1,15 @@ % runc-state "8" # NAME - runc state - output the state of a container +**runc-state** - show the state of a container # SYNOPSIS - runc state `` - -Where "``" is your name for the instance of the container. +**runc state** _container-id_ # DESCRIPTION - The state command outputs current state information for the -instance of a container. +The **state** command outputs current state information for the specified +_container-id_ in a JSON format. + +# SEE ALSO + +**runc**(8). diff --git a/man/runc-update.8.md b/man/runc-update.8.md index 5c02e451cb8..8ceaa386fe8 100644 --- a/man/runc-update.8.md +++ b/man/runc-update.8.md @@ -1,53 +1,94 @@ % runc-update "8" # NAME - runc update - update container resource constraints +**runc-update** - update running container resource constraints # SYNOPSIS - runc update [command options] `` +**runc update** [_option_ ...] _container-id_ + +**runc update** **-r** _resources.json_|**-** _container-id_ # DESCRIPTION - The data can be read from a file or the standard input, the -accepted format is as follow (unchanged values can be omitted): - - { - "memory": { - "limit": 0, - "reservation": 0, - "swap": 0, - "kernel": 0, - "kernelTCP": 0 - }, - "cpu": { - "shares": 0, - "quota": 0, - "period": 0, - "realtimeRuntime": 0, - "realtimePeriod": 0, - "cpus": "", - "mems": "" - }, - "blockIO": { - "blkioWeight": 0 - } - } - -Note: if data is to be read from a file or the standard input, all -other options are ignored. +The **update** command change the resource constraints of a running container +instance. + +The resources can be set using options, or, if **-r** is used, parsed from JSON +provided as a file or from stdin. + +In case **-r** is used, the JSON format is like this: + + { + "memory": { + "limit": 0, + "reservation": 0, + "swap": 0, + "kernel": 0, + "kernelTCP": 0 + }, + "cpu": { + "shares": 0, + "quota": 0, + "period": 0, + "realtimeRuntime": 0, + "realtimePeriod": 0, + "cpus": "", + "mems": "" + }, + "blockIO": { + "blkioWeight": 0 + } + } # 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 - --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**|**-r** _resources.json_ +: Read the new resource limtis from _resources.json_. Use **-** to read from +stdin. If this option is used, all other options are ignored. + +**--blkio-weight** _weight_ +: Set a new io weight. + +**--cpu-period** _num_ +: Set CPU CFS period to be used for hardcapping (in microseconds) + +**--cpu-quota** _num_ +: Set CPU usage limit within a given period (in microseconds). + +**--cpu-rt-period** _num_ +: Set CPU realtime period to be used for hardcapping (in microseconds). + +**--cpu-rt-runtime** _num_ +: Set CPU realtime hardcap limit (in usecs). Allowed cpu time in a given period. + +**--cpu-share** _num_ +: Set CPU shares (relative weight vs. other containers). + +**--cpuset-cpus** _list_ +: Set CPU(s) to use. The _list_ can contain commas and ranges. For example: +**0-3,7**. + +**--cpuset-mems** _list_ +: Set memory node(s) to use. The _list_ format is the same as for +**--cpuset-cpus**. + +**--memory** _num_ +: Set memory limit to _num_ bytes. + +**--memory-reservation** _num_ +: Set memory reservation, or soft limit, to _num_ bytes. + +**--memory-swap** _num_ +: Set total memory + swap usage to _num_ bytes. Use **-1** to unset the limit +(i.e. use unlimited swap). + +**--pids-limit** _num_ +: Set the maximum number of processes allowed in the container. + +**--l3-cache-schema** _value_ +: Set the value for Intel RDT/CAT L3 cache schema. + +**--mem-bw-schema** _value_ +: Set the Intel RDT/MBA memory bandwidth schema. + +# SEE ALSO + +**runc**(8). diff --git a/man/runc.8.md b/man/runc.8.md index 49df5254331..09db1ef023e 100644 --- a/man/runc.8.md +++ b/man/runc.8.md @@ -1,11 +1,12 @@ % runc "8" # NAME - runc - Open Container Initiative runtime +**runc** - Open Container Initiative runtime # SYNOPSIS - runc [global options] command [command options] [arguments...] - + +**runc** [_global-option_ ...] _command_ [_command-option_ ...] [_argument_ ...] + # DESCRIPTION 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 @@ -17,45 +18,132 @@ existing process monitoring tools and the container will be spawned as a direct child of the process supervisor. Containers are configured using bundles. A bundle for a container is a directory -that includes a specification file named "config.json" and a root filesystem. -The root filesystem contains the contents of the container. +that includes a specification file named _config.json_ and a root filesystem. +The root filesystem contains the contents of the container. -To start a new instance of a container: +To run a new instance of a container: - # runc start [ -b bundle ] + # runc run [ -b bundle ] container-id -Where "``" is your name for the instance of the container that you +Where _container-id_ 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. +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. See **runc-checkpoint**(8). + +**create** +: Create a container. See **runc-create**(8). + +**delete** +: Delete any resources held by the container often used with detached +containers. See **runc-delete**(8). + +**events** +: Display container events such as OOM notifications, cpu, memory, IO and +network stats. See **runc-events**(8). + +**exec** +: Execute a new process inside the container. See **runc-exec**(8). + +**init** +: Initialize the namespaces and launch the container init process. This command +is not supposed to be used directly. + +**kill** +: Send a specified signal to the container's init process. See +**runc-kill**(8). + +**list** +: List containers started by runc with the given **--root**. See +**runc-list**(8). + +**pause** +: Suspend all processes inside the container. See **runc-pause**(8). + +**ps** +: Show processes running inside the container. See **runc-ps**(8). + +**restore** +: Restore a container from a previous checkpoint. See **runc-restore**(8). + +**resume** +: Resume all processes that have been previously paused. See **runc-resume**(8). + +**run** +: Create and start a container. See **runc-run**(8). + +**spec** +: Create a new specification file (_config.json_). See **runc-spec**(8). + +**start** +: Start a container previously created by **runc create**. See **runc-start**(8). + +**state** +: Show the container state. See **runc-state**(8). + +**update** +: Update container resource constraints. See **runc-update**(8). + +**help**, **h** +: Show a list of commands or help for a particular 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 + +These options can be used with any command, and must precede the **command**. + +**--debug** +: Enable debug logging. + +**--log** _path_ +: Set the log destination to _path_. The default is to log to stderr. + +**--log-format** **text**|**json** +: Set the log format (default is **text**). + +**--root** _path_ +: Set the root directory to store containers' state. The _path_ should be +located on tmpfs. Default is */run/runc*, or *$XDG_RUNTIME_DIR/runc* for +rootless containers. + +**--criu** _path_ +: Set the path to the **criu**(8) binary used for checkpoint and restore. +Default is **criu**. + +**--systemd-cgroup** +: Enable systemd cgroup support. If this is set, the container spec +(_config.json_) is expected to have **cgroupsPath** value in the +*slice:prefix:name* form (e.g. **system.slice:runc:434234**). + +**--rootless** **true**|**false**|**auto** +: Enable or disable rootless mode. Default is **auto**, meaning to auto-detect +whether rootless should be enabled. + +**--help**|**-h** +: Show help. + +**--version**|**-v** +: Show version. + +# SEE ALSO + +**runc-checkpoint**(8), +**runc-create**(8), +**runc-delete**(8), +**runc-events**(8), +**runc-exec**(8), +**runc-kill**(8), +**runc-list**(8), +**runc-pause**(8), +**runc-ps**(8), +**runc-restore**(8), +**runc-resume**(8), +**runc-run**(8), +**runc-spec**(8), +**runc-start**(8), +**runc-state**(8), +**runc-update**(8).