man/*: revamp

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>

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] `<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

@@ -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

@@ -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.
+
+# 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).

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] `<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

@@ -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.
+**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 <container-id> 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: <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)
+**--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

@@ -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.
+
+# 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).