criu man page

criu — checkpoint/restore in userspace


criu command [option ...]


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.


Common options

Common options are applicable to any command.


Set logging level to num. The higher 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.


Write separate logging files per each pid.

-D, --images-dir path

Use path as a base directory where to look for sets of image files.

--prev-images-dir path

Use path as a parent directory where to look for sets of image files. This option makes sense in case of incremental 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 descriptor fd before performing any actions.

-L, --libdir path

Path to plugins directory.

--action-script script

Add an external action script to be executed at certain stages. The environment variable CRTOOLS_SCRIPT_ACTION is available to the script to find out which action is being executed, and its value can be one of the following:

run prior to beginning a dump

run upon dump completion

run prior to beginning a restore

run upon restore completion

run to lock network in a target network namespace

run to unlock network in a target network namespace

run once root task just been created with required namespaces. Note it is an early stage of restore, when nothing is restored yet except for namespaces themselves

-V, --version

Print program version and exit.

-h, --help

Print some help and exit.


Performs the pre-dump procedure, during which criu creates a snapshot of memory changes since the previous pre-dump. Note that during this criu also creates the fsnotify cache which speeds up the restore procedure. pre-dump requires at least -t option (see dump below). In addition, page-server options may be specified.


Turn on memory changes tracker in the kernel. If the option is not passed the memory tracker get turned on implicitly.


Performs 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. This option is pretty dangerous and should be used only if you understand what you are doing.

Note if task is about to run after been checkpointed, it can modify TCP connections, delete files and do other dangerous actions. Therefore, criu can not guarantee that the next restore action will succeed. Most likely if this option is used, at least the file system snapshot must be made with the help of post-dump action script.

In other words, do not use it unless really needed.

-s, --leave-stopped

Leave tasks in stopped state after checkpoint, instead of killing.

-x, --ext-unix-sk [inode[,inode...]]

Dump external unix sockets. Optionally passing a comma-separated list of inodes to allow a one sided dump for those.


Use cgroup freezer to collect processes.


Collect cgroups into the image thus they gonna be restored then. Without this option, criu will not save cgroups configuration associated with a task.

--cgroup-props spec

Specify controllers and their properties to be saved into the image file. criu predefines specifications for common controllers, but since the kernel can add new controllers and modify their properties, there should be a way to specify ones matched the kernel.

spec argument describes the controller and properties specification in a simplified YAML form:

 - "strategy": "merge"
 - "properties": ["a", "b"]
 - "strategy": "replace"
 - "properties": ["c", "d"]

where c1 and c2 are controllers names, and a, b, c, d are their properties.

Note the format: double quotes, spaces and new lines are required. The strategy specifies what to do if a controller specified already exists as a built-in one: criu can either merge or replace such.

For example, the command line for the above example should look like this:

--cgroup-props "\"c1\":\n - \"strategy\": \"merge\"\n - \"properties\": [\"a\", \"b\"]\n \"c2\":\n - \"strategy\": \"replace\"\n - \"properties\": [\"c\", \"d\"]"

--cgroup-props-file file

Same as --cgroup-props, except the specification is read from the file.

--cgroup-dump-controller name

Dump a controller with name only, skipping anything else that was discovered automatically (usually via /proc). This option is useful when one needs criu to skip some controllers.


When combined with --cgroup-props, makes criu substitute a predefined controller property with the new one shipped. If the option is not used, the predefined properties are merged with the provided ones.


Checkpoint established TCP connections.


This option skips in-flight TCP connections. If any TCP connections that are not yet completely established are found, criu ignores these connections, rather than errors out. The TCP stack on the client side is expected to handle the re-connect gracefully.

--veth-pair IN=OUT

Relation between outside and inside names of veth devices.


Use any path to a device file if the original one is inaccessible.


Send pages to a page server (see the page-server command).


Force resolving names for inotify and fsnotify watches.


Deduplicate "old" data in pages images of previous dump. This option implies incremental dump mode (see the 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 enclosed containers where locks are not held by any processes outside of dumped process tree.

-M, --ext-mount-map KEY:VAL

Setup mapping for external mounts. Here KEY is a mountpoint inside a container, and corresponding VAL is a string to be written into the image as the mountpoint's root value.


Allows to link unlinked files back, if possible (modifies filesystem during restore).

--ghost-limit size

Set the maximum size of deleted file to be carried inside image. By default, up to 1M file is allowed. Using this option allows to not put big deleted files inside images. Argument size may be postfixed with a K, M or G, which stands for kilo-, mega, and gigabytes, accordingly.

-j, --shell-job

Allow one to dump shell jobs. This implies the restored task will inherit session and process group ID from the criu itself. This option also allows to migrate a single external tty connection, to migrate applications like top. If used with dump command, it must be specified with restore as well.

--cpu-cap [cap[,cap...]]

Specify CPU capabilities to write to an image file. The argument is a comma-separated list of none, fpu, cpu, ins, all. If the argument is omitted or set to none, capabilities will not be written, which is the default behavior.

--cgroup-root [controller:]/newroot

Change the root for the controller that will be dumped. By default, criu simply dumps everything below where any of the tasks live. However, if a container moves all of its tasks into a cgroup directory below the container engine’s default directory for tasks, permissions will not be preserved on the upper directories with no tasks in them, which may cause problems.


Restores previously checkpointed processes.

--inherit-fd fd[N]:path

Inherit file descriptors. This asks criu to use an already opened file descriptor N for restoring a file indentified by path. Note that the N must be enclosed in a literal square brackets, that usually needs to be escaped from shell.

-d, --restore-detached

Detach criu itself once restore is complete.

-S, --restore-sibling

Restore root task as a sibling (makes sense only with --restore-detached).

-r, --root path

Change the root filesystem to path (when run in a mount namespace).

--manage-cgroups [mode]

Restore cgroups configuration associated with a task from the image. Controllers are always restored in an optimistic way — if already present in system, criu reuses it, otherwise it will be created.

The mode may be one of the following:


Do not restore cgroup properties but require cgroup to pre-exist at the moment of restore procedure.


Restore cgroup properties and require cgroup to pre-exist.


Restore cgroup properties if only cgroup has been created by criu, otherwise do not restore properties. This is the default if mode is unspecified.


Always restore all cgroups and their properties.


Restore all cgroups and their properties from the scratch, requiring them to not present in the system.

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

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.

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 CPU capabilities to be present on the CPU the process is restoring. To inverse a capability, prefix it with ^. This option implies that --cpu-cap has been passed on dump as well, except fpu option case. The cap argument can be the following (or a set of comma-separated values):


Require all capabilities. This is default mode if --cpu-cap is passed without arguments. Most safe mode.


Require the CPU to have all capabilities in image to match runtime CPU.


Require the CPU to have compatible 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 proceed. 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 because FPU frames are always encoded into images.


Require CPU compatibility on instructions level.


Ignore capabilities. Most dangerous mode. The behaviour is implementation dependent. Try to not use it until really required.

For example, this option can be used in case --cpu-cap=cpu was used during dump, and images are migrated to a less capable CPU and are to be restored. By default, criu shows an error that CPU capabilities are not adequate, but this can be suppressed by using --cpu-cap=none.


Checks whether the kernel supports the features needed by criu to dump and restore a process tree.

There are three categories of kernel support, as described below. criu check always checks Category 1 features unless --feature is specified which only checks a specified feature.

Category 1

Absolutely required. These are features like support for /proc/PID/map_files, NETLINK_SOCK_DIAG socket monitoring, /proc/sys/kernel/ns_last_pid etc.

Category 2

Required only for specific cases. These are features like AIO remap, /dev/net/tun and others that are only required if a process being dumped or restored is using those.

Category 3

Experimental. These are features like task-diag that are used for experimental purposes (mostly during development).

If there are no errors or warnings, criu prints "Looks good." and its exit code is 0.

A missing Category 1 feature causes criu to print "Does not look good." and its exit code is non-zero.

Missing Category 2 and 3 features cause criu to print "Looks good but ..." and its exit code is be non-zero.

Without any options, criu check checks Category 1 features. This behavior can be changed by using the following options:


Check kernel support for Category 2 features.


Check kernel support for Category 3 features.


Check kernel support for Category 1, 2, and 3 features.

--feature name

Check a specific feature. If name is list, a list of valid kernel feature names that can be checked will be printed.


Launches criu in page server mode.


Runs page server as a daemon (background process).

--address address

Page server IP address.

--port number

Page server port number.


Executes a system call inside a destination task's context. This functionality is depreated; please use Compel instead.


Launches criu in RPC daemon mode, where criu is listening for RPC commands over socket to perform. This is convenient for a case where daemon itself is running in a privileged (superuser) mode but clients are not.


Starts pagemap data deduplication procedure, where criu scans over all pagemap files and tries to minimize 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 (i.e. CPU the criu is running on) and test if they are compatible with the ones present in an image file.


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


The CRIU team.


criu 2.7 10/19/2016