mirror/runc
1
0
Fork 0
mirror of https://github.com/opencontainers/runc.git synced 2026-07-11 06:03:57 +08:00
Code Issues Packages Projects Releases Wiki Activity

man/*: revamp

Browse Source 
Current runc man pages are ugly (no proper man page formatting)
and very short (mostly just a copy-paste from the "runc <command>
--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 <container_id> from every page;
 - added SEE ALSO;
 - something else I forgot.

Signed-off-by: Kir Kolyshkin <kolyshkin@gmail.com>
This commit is contained in:
Kir Kolyshkin
2021-06-15 17:50:24 -07:00
parent e8bd33ae28
commit dfc0f0695a
17 changed files with 666 additions and 309 deletions
Download Patch File Download Diff File Expand all files Collapse all files
man/runc-checkpoint.8.md
+67 -21
View File
@@ -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] `<container-id>`
Where "`<container-id>`" 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).
man/runc-create.8.md
+35 -20
View File
@@ -1,29 +1,44 @@
% runc-create "8"
# NAME
runc create - create a container
**runc-create** - create a container
# SYNOPSIS
runc create [command options] `<container-id>`
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.
**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).
man/runc-delete.8.md
+15 -10
View File
@@ -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] `<container-id>`
Where "`<container-id>`" 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.
# 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:
# 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
# runc delete ubuntu01
# SEE ALSO
**runc-kill**(8),
**runc**(8).
man/runc-events.8.md
+14 -8
View File
@@ -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] `<container-id>`
Where "`<container-id>`" 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).
man/runc-exec.8.md
+62 -25
View File
@@ -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] `<container-id>` -- `<container command>` [args...]
**runc exec** [_option_ ...] _container-id_ [--] _command_ [_arg_ ...]
Where "`<container-id>`" is the name for the instance of the container and
"`<container command>`" is the command to be executed in the container.
# 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:
# runc exec <container-id> ps
**runc exec** [_option_ ...] **-p** _process.json_ _container-id_
# 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: <uid>[:<gid>])
--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-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).
**--cwd** _path_
: Change to _path_ in the container before executing the command.
**--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 <container-id> ps
# SEE ALSO
**runc**(8).
man/runc-kill.8.md
+20 -9
View File
@@ -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] `<container-id>` `<signal>`
**runc kill** [**--all**|**-a**] _container-id_ [_signal_]
Where "`<container-id>`" is the name for the instance of the container and
"`<signal>`" 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.
# EXAMPLE
# EXAMPLES
For example, if the container id is "ubuntu01" the following will send a "KILL"
signal to the init process of the "ubuntu01" container:
The following will send a **KILL** signal to the init process of the
**ubuntu01** container:
# runc kill ubuntu01 KILL
# runc kill ubuntu01 KILL
# SEE ALSO
**runc**(1).
man/runc-list.8.md
+30 -12
View File
@@ -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).
man/runc-pause.8.md
+11 -7
View File
@@ -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 `<container-id>`
Where "`<container-id>`" 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).
man/runc-ps.8.md
+18 -7
View File
@@ -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] `<container-id>` [ps options]
**runc ps** [_option_ ...] _container-id_ [_ps-option_ ...]
# 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.
# OPTIONS
--format value, -f value select one of: table(default) or json
**--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.
The default format is table. The following will output the processes of a container
in json format:
# runc ps -f json <container-id>
# SEE ALSO
**runc-list**(8),
**runc**(8).
man/runc-restore.8.md
+68 -31
View File
@@ -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] `<container-id>`
Where "`<container-id>`" 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.
**--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).
## OPTION DETAILS
**--image-path** _path_
: Set path to get criu image files to restore from.
**--lsm-profile**
**--work-path** _path_
: Set path for saving criu work files and logs. The default is to reuse the
image files directory.
Specify an LSM profile to be used during restore in the form of TYPE:NAME.
**--tcp-established**
: Allow checkpoint/restore of established TCP connections. See
[criu --tcp-establised option](https://criu.org/CLI/opt/--tcp-established).
`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" <container-id>
```
**--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).
man/runc-resume.8.md
+11 -7
View File
@@ -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 `<container-id>`
Where "`<container-id>`" 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).
man/runc-run.8.md
+38 -22
View File
@@ -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] `<container-id>`
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.
**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).
man/runc-spec.8.md
+52 -37
View File
@@ -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.
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.
# 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:
# OPTIONS
**--bundle**|**-b** _path_
: Set _path_ to the root of the bundle directory.
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
**--rootless**
: Generate a configuration for a rootless container. Note this option
is entirely different from the global **--rootless** option.
In the start command above, "container1" is the name for the instance of the
# 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).
man/runc-start.8.md
+8 -7
View File
@@ -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 `<container-id>`
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.
**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).
man/runc-state.8.md
+8 -6
View File
@@ -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 `<container-id>`
Where "`<container-id>`" 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).
man/runc-update.8.md
+83 -42
View File
@@ -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] `<container-id>`
**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):
The **update** command change the resource constraints of a running container
instance.
{
"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
}
}
The resources can be set using options, or, if **-r** is used, parsed from JSON
provided as a file or from stdin.
Note: if data is to be read from a file or the standard input, all
other options are ignored.
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).
man/runc.8.md
+126 -38
View File
@@ -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 ] <container-id>
# runc run [ -b bundle ] container-id
Where "`<container-id>`" 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).