docs: Rework the manual, v2
I think this might be more readable if we group options by the commands. So here is the result. Please read and tell me what you think. I put formatted manual here because read diff itself is almost impossible. v2: - update description - use </> for commands - various formatting and text nitpicks | CRIU(8) CRIU Manual CRIU(8) | | | | NAME | criu - checkpoint/restore in userspace | | SYNOPSIS | criu <command> [options] | | DESCRIPTION | criu is a tool for checkpointing and restoring running applications. It | does this by saving their state as a collection of files (see the dump | command) and creating equivalent processes from those files (see the | restore command). The restore operation can be performed at a later | time, on a different system, or both. | | OPTIONS | The options are depending on the <command> criu run with. | | Common options | Common options are applied to any <command>. | | -v[<num>|v...] | Set logging level to <num>. The higer the level, the more output is | produced. Either numeric values or multiple v can be used. | | The following levels are available: | | · -v1, -v only messages and errors; | | · -v2, -vv also warnings (default level); | | · -v3, -vvv also information messages and timestamps; | | · -v4, -vvvv lots of debug. | | --pidfile <file> | Write root task, service or page-server pid into a <file>. | | -o, --log-file <file> | Write logging messages to <file>. | | --log-pid | Write separate logging files per each pid. | | -D, --images-dir <path> | Use path <path> as a base directory where to look for dump files | set. | | --prev-images-dir <path> | Use path <path> as a parent directory where to look for dump files | set. This make sence in case of increment dumps. | | -W, --work-dir <dir> | Use directory <dir> for putting logs, pidfiles and statistics. If | not specified, <path> from -D option is taken. | | --close <fd> | Close file with descriptor <fd> before any actions. | | -L, --libdir <path> | Path to a plugins directory. | | --action-script <SCRIPT> | Add an external action script. The environment variable | CRTOOLS_SCRIPT_ACTION contains one of the actions: | | · post-dump run an action upon dump completion; | | · post-restore run an action upon restore completion; | | · network-lock lock network in a target network namespace; | | · network-unlock unlock network in a target network namespace; | | · setup-namespaces run an action once root task just been created | with required namespaces, note it is early stage on restore | nothing were restored yet except namespaces themselves. | | -V, --version | Print program version and exit. | | -h, --help | Print a commands list and exit. The commands list is very short one | just for overview and does not match this manual. | | pre-dump | Launches that named pre-dump procedure, where criu does snapshot of | memory changes since previous pre-dump. Also criu forms fsnotify cache | which speedup restore procedure. pre-dump requires at least -t option | (see dump below). Optionally page-server options may be specified. | | --track-mem | Turn on memory changes tracker in the kernel. If the option is not | passed the memory tracker get turned on implicitly. | | dump | Starts a checkpoint procedure. | | -t, --tree <pid> | Checkpoint the whole process tree starting from <pid>. | | -R, --leave-running | Leave tasks in running state after checkpoint instead of killing | them. This option is pretty dangerous and should be used if and | only if you understand what you are doing. | | If task is about to run after been checkpointed it can modify TCP | connections, delete files and do other dangerous actions. So that | criu itself can not guarantee that the next restore action will not | fail. Most likely if a user starts criu with this option passed at | least the file system snapshot must be done with help of post-dump | script. | | In other words, do not use it until really needed. | | -s, --leave-stopped | Leave tasks in stopped state after checkpoint instead of killing | them. | | -x, --ext-unix-sk | Dump external unix sockets. | | -n, --namespaces <ns>[,<ns>...] | Checkpoint namespaces. Namespaces must be separated by comma. | Currently supported namespaces: uts, ipc, mnt, pid, net. | | --manage-cgroups | Collect cgroups into the image thus they gonna be restored then. | Without this argument criu will not save cgroups configuration | associated with a task. | | --tcp-established | Checkpoint established TCP connections. | | --veth-pair <IN>=<OUT> | Correspondence between outside and inside names of veth devices. | | --evasive-devices | Use any path to a device file if the original one is inaccessible. | | --page-server | Send pages to a page server (see page-server command). | | --force-irmap | Force resolving names for inotify and fsnotify watches. | | --auto-dedup | Deduplicate "old" data in pages images of previous dump. Which | implies incremental dump mode (see pre-dump command). | | -l, --file-locks | Dump file locks. It is necessary to make sure that all file lock | users are taken into dump, so it is only safe to use this for | enclojured containers where locks are not holed by someone outside | of it. | | -M, --ext-mount-map <KEY>:<VAL> | Setup mapping for external mounts. <KEY> is a mountpoint inside | container and corresponding <VAL> is a string that will be written | into the image as mountpoint's root value. | | --link-remap | Allow to link unlinked files back when possible (modifies FS till | restore). | | -j, --shell-job | Allow to dump shell jobs. This implies the restored task will | inherit session and process group ID from the criu itself. Also | this option allows one to migrate a single external tty connection, | in other words this option allows one to migrate such application | as "top" and friends. If passed on dump it must be specified on | restore as well. | | --cpu-cap [,<cap>] | Specify cap CPU capability to be written into an image file. | Basically if <cap> is one of all, cpu or ins, then criu writes CPU | related information into image file. If the option is omitted or | set to none then image will not be written. By default criu do not | write this image. | | restore | Restores previously checkpointed processes. | | --inherit-fd fd[<num>]:<existing> | Inherit file descriptors. This allows to treat file descriptor | <num> as being already opened via <existing> one and instead of | trying to open we inherit it. | | -d, --restore-detached | Detach criu itself once restore is complete. | | -S, --restore-sibling | Restore root task as a sibling (make sense with --restore-detached) | only. | | -r, --root <path> | Change the root filesystem to <path> (when run in mount namespace). | | --manage-cgroups | Restore cgroups configuration associated with a task from the | image. | | --cgroup-root [<controller>:]/<newroot> | Change the root cgroup the controller will be installed into. No | controller means that root is the default for all controllers not | specified. | | --tcp-established | Restore previously dumped established TCP connections. This implies | that the network has been locked between dump and restore phases so | other side of a connection simply notice a kind of lag. | | --veth-pair <IN>=<OUT> | Correspondence between outside and inside names of veth devices. | | -l, --file-locks | Restore file locks from the image. | | -M, --ext-mount-map <KEY>:<VAL> | Setup mapping for external mounts. <KEY> is the value from the | image (<VAL> from dump) and the <VAL> is the path on host that will | be bind-mounted into container (to the mountpoint path from image). | | --ext-mount-map auto | This is a special case. If this flag is passed, when an external | mount is missing from the command line --ext-mount-map <KEY>:<VAL> | syntax, criu attempts to automatically resolve this mount from its | namespace. | | --enable-external-sharing, --enable-external-masters | These flags enable external shared or slave mounts to be resolved | automatically when --ext-mount-map auto is passed. | | --auto-dedup | As soon as a page is restored it get punched out from image. | | -j, --shell-job | Restore shell jobs, in other words inherit session and process | group ID from the criu itself. | | --cpu-cap [<cap>,<cap>] | Specify <cap> CPU capability to be present on the CPU the process | is restoring. To inverse capability prefix it with ^. This option | implies that --cpu-cap has been passed on dump as well, except fpu | option case. | | · all. Require all capabilities. This is default mode if | --cpu-cap is passed without arguments. Most safe mode. | | · cpu. Require the CPU to have all capabilities in image to match | runtime CPU. | | · fpu. Requre the CPU to have comaptible FPU. For example the | process might be dumped with xsave capability but attempted to | restore without it present on target CPU. In such case we | refuse to procceed. This is default mode if --cpu-cap is not | present in command line. Note this argument might be passed | even if on the dump no --cpu-cap have been specified becase FPU | frames are always encoded into images. | | · ins. Require CPU compatibility on instructions level. | | · none. Ignore capabilities. Most dangerous mode. The behaviour | is implementation dependent. Try to not use it until really | required. | | One possible need of using this option is when --cpu-cap=cpu | has been passed on dump then images are migrated to a less | capable processor and one need to restore this application, by | default criu will refuse to proceed without relaxing capability | with --cpu-cap=none parameter. | | check | Tests wheter the kernel support is up to date. | | --ms | Do not check not yet merged features. | | --feature <name> | Check a particular feature. Instead of checking everything one may | specify which exactly feature is to be tested. The <name> may be: | mnt_id, aio_remap, timerfd, tun, userns. | | page-server | Launches criu in page server mode. | | --daemon | Runs page server as a daemon (background process). | | --address <address> | Page server IP address. | | --port <number> | Page server port number. | | exec | Executes a system call inside a destination task's context. | | service | Launches criu in RPC daemon mode where criu is listeninп for RPC | commands over socket to perform. This is convenient for the case where | daemon itself is running in a privilege (superuser) mode but clients | are not. | | dedup | Starts pagemap data deduplication procedure, where criu scans over all | pagemap files and tries to minimalize the number of pagemap entries by | obtaining the references from a parent pagemap image. | | cpuinfo dump | Fetches current CPU features and write them into an image file. | | cpuinfo check | Fetches current CPU features (ie CPU the criu is running on) and test | if they are compatible with ones present in image file. | | SYSCALLS EXECUTION | To run a system call in another task's context use | | criu exec -t pid syscall-string | | command. The syscall-string should look like | | syscall-name syscall-arguments ... | | Each command line argument is transformed into the system call argument | by the following rules: | | · If one starts with &, the rest of it gets copied to the target | task's address space and the respective syscall argument is the | pointer to this string; | | · Otherwise it is treated as a number (converted with strtol) and is | directly passed into the system call. | | EXAMPLES | To checkpoint a program with pid of 1234 and write all image files into | directory checkpoint: | | criu dump -D checkpoint -t 1234 | | To restore this program detaching criu itself: | | criu restore -d -D checkpoint | | To close a file descriptor number 1 in task with pid 1234: | | criu exec -t 1234 close 1 | | To open a file named /foo/bar for read-write in the task with pid 1234: | | criu exec -t 1234 open '&/foo/bar' 2 | | AUTHOR | OpenVZ team. | | COPYRIGHT | Copyright (C) 2011-2015, Parallels Inc. | | | | criu 0.0.3 05/06/2015 CRIU(8) Signed-off-by:Cyrill Gorcunov <gorcunov@openvz.org> Signed-off-by:
Pavel Emelyanov <xemul@parallels.com>
Showing
Please
register
or
sign in
to comment