'\" t

.\"     Title: criu

.\"    Author: [see the "AUTHOR" section]

.\" Generator: DocBook XSL Stylesheets vsnapshot <http://docbook.sf.net/>

.\"      Date: 04/23/2019

.\"    Manual: CRIU Manual

.\"    Source: criu 3.12

.\"  Language: English

.\"

.TH "CRIU" "8" "04/23/2019" "criu 3\&.12" "CRIU Manual"

.\" -----------------------------------------------------------------

.\" * Define some portability stuff

.\" -----------------------------------------------------------------

.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

.\" http://bugs.debian.org/507673

.\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html

.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

.ie \n(.g .ds Aq \(aq

.el       .ds Aq '

.\" -----------------------------------------------------------------

.\" * (re)Define some macros

.\" -----------------------------------------------------------------

.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

.\" toupper - uppercase a string (locale-aware)

.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

.de toupper

.tr aAbBcCdDeEfFgGhHiIjJkKlLmMnNoOpPqQrRsStTuUvVwWxXyYzZ

\\$*

.tr aabbccddeeffgghhiijjkkllmmnnooppqqrrssttuuvvwwxxyyzz

..

.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

.\" SH-xref - format a cross-reference to an SH section

.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

.de SH-xref

.ie n \{\

.\}

.toupper \\$*

.el \{\

\\$*

.\}

..

.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

.\" SH - level-one heading that works better for non-TTY output

.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

.de1 SH

.\" put an extra blank line of space above the head in non-TTY output

.if t \{\

.sp 1

.\}

.sp \\n[PD]u

.nr an-level 1

.set-an-margin

.nr an-prevailing-indent \\n[IN]

.fi

.in \\n[an-margin]u

.ti 0

.HTML-TAG ".NH \\n[an-level]"

.it 1 an-trap

.nr an-no-space-flag 1

.nr an-break-flag 1

\." make the size of the head bigger

.ps +3

.ft B

.ne (2v + 1u)

.ie n \{\

.\" if n (TTY output), use uppercase

.toupper \\$*

.\}

.el \{\

.nr an-break-flag 0

.\" if not n (not TTY), use normal case (not uppercase)

\\$1

.in \\n[an-margin]u

.ti 0

.\" if not n (not TTY), put a border/line under subheading

.sp -.6

\l'\n(.lu'

.\}

..

.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

.\" SS - level-two heading that works better for non-TTY output

.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

.de1 SS

.sp \\n[PD]u

.nr an-level 1

.set-an-margin

.nr an-prevailing-indent \\n[IN]

.fi

.in \\n[IN]u

.ti \\n[SN]u

.it 1 an-trap

.nr an-no-space-flag 1

.nr an-break-flag 1

.ps \\n[PS-SS]u

\." make the size of the head bigger

.ps +2

.ft B

.ne (2v + 1u)

.if \\n[.$] \&\\$*

..

.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

.\" BB/EB - put background/screen (filled box) around block of text

.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

.de BB

.if t \{\

.sp -.5

.br

.in +2n

.ll -2n

.gcolor red

.di BX

.\}

..

.de EB

.if t \{\

.if "\\$2"adjust-for-leading-newline" \{\

.sp -1

.\}

.br

.di

.in

.ll

.gcolor

.nr BW \\n(.lu-\\n(.i

.nr BH \\n(dn+.5v

.ne \\n(BHu+.5v

.ie "\\$2"adjust-for-leading-newline" \{\

\M[\\$1]\h'1n'\v'+.5v'\D'P \\n(BWu 0 0 \\n(BHu -\\n(BWu 0 0 -\\n(BHu'\M[]

.\}

.el \{\

\M[\\$1]\h'1n'\v'-.5v'\D'P \\n(BWu 0 0 \\n(BHu -\\n(BWu 0 0 -\\n(BHu'\M[]

.\}

.in 0

.sp -.5v

.nf

.BX

.in

.sp .5v

.fi

.\}

..

.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

.\" BM/EM - put colored marker in margin next to block of text

.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

.de BM

.if t \{\

.br

.ll -2n

.gcolor red

.di BX

.\}

..

.de EM

.if t \{\

.br

.di

.ll

.gcolor

.nr BH \\n(dn

.ne \\n(BHu

\M[\\$1]\D'P -.75n 0 0 \\n(BHu -(\\n[.i]u - \\n(INu - .75n) 0 0 -\\n(BHu'\M[]

.in 0

.nf

.BX

.in

.fi

.\}

..

.\" -----------------------------------------------------------------

.\" * set default formatting

.\" -----------------------------------------------------------------

.\" -----------------------------------------------------------------

.\" * MAIN CONTENT STARTS HERE *

.\" -----------------------------------------------------------------

.SH "Name"

criu \- checkpoint/restore in userspace

.SH "Synopsis"

.sp

\fBcriu\fR \fIcommand\fR [\fIoption\fR \&...]

.SH "DESCRIPTION"

.sp

\fBcriu\fR is a tool for checkpointing and restoring running applications\&. It does this by saving their state as a collection of files (see the \fBdump\fR command) and creating equivalent processes from those files (see the \fBrestore\fR command)\&. The restore operation can be performed at a later time, on a different system, or both\&.

.SH "OPTIONS"

.sp

Most of the true / false long options (the ones without arguments) can be prefixed with \fB\-\-no\-\fR to negate the option (example: \fB\-\-display\-stats\fR and \fB\-\-no\-display\-stats\fR)\&.

.SS "Common options"

.sp

Common options are applicable to any \fIcommand\fR\&.

.PP

\fB\-v\fR[\fBv\fR\&...], \fB\-\-verbosity\fR

.RS 4

Increase verbosity up from the default level\&. Multiple

\fBv\fR

can be used, each increasing verbosity by one level\&. Using long option without argument increases verbosity by one level\&.

.RE

.PP

\fB\-v\fR\fInum\fR, \fB\-\-verbosity\fR=\fInum\fR

.RS 4

Set verbosity level to

\fInum\fR\&. The higher the level, the more output is produced\&.

The following levels are available:

.sp

.RS 4

.ie n \{\

\h'-04'\(bu\h'+03'\c

.\}

.el \{\

.sp -1

.IP \(bu 2.3

.\}

\fB\-v0\fR

no output;

.RE

.sp

.RS 4

.ie n \{\

\h'-04'\(bu\h'+03'\c

.\}

.el \{\

.sp -1

.IP \(bu 2.3

.\}

\fB\-v1\fR

only errors;

.RE

.sp

.RS 4

.ie n \{\

\h'-04'\(bu\h'+03'\c

.\}

.el \{\

.sp -1

.IP \(bu 2.3

.\}

\fB\-v2\fR

above plus warnings (this is the default level);

.RE

.sp

.RS 4

.ie n \{\

\h'-04'\(bu\h'+03'\c

.\}

.el \{\

.sp -1

.IP \(bu 2.3

.\}

\fB\-v3\fR

above plus information messages and timestamps;

.RE

.sp

.RS 4

.ie n \{\

\h'-04'\(bu\h'+03'\c

.\}

.el \{\

.sp -1

.IP \(bu 2.3

.\}

\fB\-v4\fR

above plus lots of debug\&.

.RE

.RE

.PP

\fB\-\-config\fR \fIfile\fR

.RS 4

Pass a specific configuration file to criu\&.

.RE

.PP

\fB\-\-no\-default\-config\fR

.RS 4

Forbid parsing of default configuration files\&.

.RE

.PP

\fB\-\-pidfile\fR \fIfile\fR

.RS 4

Write root task, service or page\-server pid into a

\fIfile\fR\&.

.RE

.PP

\fB\-o\fR, \fB\-\-log\-file\fR \fIfile\fR

.RS 4

Write logging messages to

\fIfile\fR\&.

.RE

.PP

\fB\-\-display\-stats\fR

.RS 4

During dump as well as during restore

\fBcriu\fR

collects information like the time required to dump or restore the process or the number of pages dumped or restored\&. This information is always written to the files

\fIstats\-dump\fR

and

\fIstats\-restore\fR

and can be easily displayed using

\fBcrit\fR\&. The option

\fB\-\-display\-stats\fR

additionally prints out this information on the console at the end of a dump or a restore\&.

.RE

.PP

\fB\-D\fR, \fB\-\-images\-dir\fR \fIpath\fR

.RS 4

Use

\fIpath\fR

as a base directory where to look for sets of image files\&.

.RE

.PP

\fB\-\-prev\-images\-dir\fR \fIpath\fR

.RS 4

Use

\fIpath\fR

as a parent directory where to look for sets of image files\&. This option makes sense in case of incremental dumps\&.

.RE

.PP

\fB\-W\fR, \fB\-\-work\-dir\fR \fIdir\fR

.RS 4

Use directory

\fIdir\fR

for putting logs, pidfiles and statistics\&. If not specified,

\fIpath\fR

from

\fB\-D\fR

option is taken\&.

.RE

.PP

\fB\-\-close\fR \fIfd\fR

.RS 4

Close file descriptor

\fIfd\fR

before performing any actions\&.

.RE

.PP

\fB\-L\fR, \fB\-\-libdir\fR \fIpath\fR

.RS 4

Path to plugins directory\&.

.RE

.PP

\fB\-\-action\-script\fR \fIscript\fR

.RS 4

Add an external action script to be executed at certain stages\&. The environment variable

\fBCRTOOLS_SCRIPT_ACTION\fR

is available to the script to find out which action is being executed, and its value can be one of the following:

.PP

\fBpre\-dump\fR

.RS 4

run prior to beginning a

\fBdump\fR

.RE

.PP

\fBpost\-dump\fR

.RS 4

run upon

\fBdump\fR

completion

.RE

.PP

\fBpre\-restore\fR

.RS 4

run prior to beginning a

\fBrestore\fR

.RE

.PP

\fBpost\-restore\fR

.RS 4

run upon

\fBrestore\fR

completion

.RE

.PP

\fBpre\-resume\fR

.RS 4

run when all processes and resources are restored but tasks are stopped waiting for final kick to run\&. Must not fail\&.

.RE

.PP

\fBpost\-resume\fR

.RS 4

called at the very end, when everything is restored and processes were resumed

.RE

.PP

\fBnetwork\-lock\fR

.RS 4

run to lock network in a target network namespace

.RE

.PP

\fBnetwork\-unlock\fR

.RS 4

run to unlock network in a target network namespace

.RE

.PP

\fBsetup\-namespaces\fR

.RS 4

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

.RE

.PP

\fBpost\-setup\-namespaces\fR

.RS 4

called after the namespaces are configured

.RE

.PP

\fBorphan\-pts\-master\fR

.RS 4

called after master pty is opened and unlocked\&. This hook can be used only in the RPC mode, and the notification message contains a file descriptor for the master pty

.RE

.RE

.PP

\fB\-V\fR, \fB\-\-version\fR

.RS 4

Print program version and exit\&.

.RE

.PP

\fB\-h\fR, \fB\-\-help\fR

.RS 4

Print some help and exit\&.

.RE

.SS "pre\-dump"

.sp

Performs the pre\-dump procedure, during which \fBcriu\fR creates a snapshot of memory changes since the previous \fBpre\-dump\fR\&. Note that during this \fBcriu\fR also creates the fsnotify cache which speeds up the \fBrestore\fR procedure\&. \fBpre\-dump\fR requires at least \fB\-t\fR option (see \fBdump\fR below)\&. In addition, \fBpage\-server\fR options may be specified\&.

.PP

\fB\-\-track\-mem\fR

.RS 4

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

.RE

.SS "dump"

.sp

Performs a checkpoint procedure\&.

.PP

\fB\-t\fR, \fB\-\-tree\fR \fIpid\fR

.RS 4

Checkpoint the whole process tree starting from

\fIpid\fR\&.

.RE

.PP

\fB\-R\fR, \fB\-\-leave\-running\fR

.RS 4

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

.sp

Note if task is about to run after been checkpointed, it can modify TCP connections, delete files and do other dangerous actions\&. Therefore,

\fBcriu\fR

can not guarantee that the next

\fBrestore\fR

action will succeed\&. Most likely if this option is used, at least the file system snapshot must be made with the help of

\fBpost\-dump\fR

action script\&.

.sp

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

.RE

.PP

\fB\-s\fR, \fB\-\-leave\-stopped\fR

.RS 4

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

.RE

.PP

\fB\-\-external\fR \fItype\fR\fB[\fR\fIid\fR\fB]:\fR\fIvalue\fR

.RS 4

Dump an instance of an external resource\&. The generic syntax is

\fItype\fR

of resource, followed by resource

\fIid\fR

(enclosed in literal square brackets), and optional

\fIvalue\fR

(prepended by a literal colon)\&. The following resource types are currently supported:

\fBmnt\fR,

\fBdev\fR,

\fBfile\fR,

\fBtty\fR,

\fBunix\fR\&. Syntax depends on type\&. Note to restore external resources, either

\fB\-\-external\fR

or

\fB\-\-inherit\-fd\fR

is used, depending on resource type\&.

.RE

.PP

\fB\-\-external mnt[\fR\fImountpoint\fR\fB]:\fR\fIname\fR

.RS 4

Dump an external bind mount referenced by

\fImountpoint\fR, saving it to image under the identifier

\fIname\fR\&.

.RE

.PP

\fB\-\-external mnt[]:\fR\fIflags\fR

.RS 4

Dump all external bind mounts, autodetecting those\&. Optional

\fIflags\fR

can contain

\fBm\fR

to also dump external master mounts,

\fBs\fR

to also dump external shared mounts (default behavior is to abort dumping if such mounts are found)\&. If

\fIflags\fR

are not provided, colon is optional\&.

.RE

.PP

\fB\-\-external dev[\fR\fImajor\fR\fB/\fR\fIminor\fR\fB]:\fR\fIname\fR

.RS 4

Allow to dump a mount namespace having a real block device mounted\&. A block device is identified by its

\fImajor\fR

and

\fIminor\fR

numbers, and

\fBcriu\fR

saves its information to image under the identifier

\fIname\fR\&.

.RE

.PP

\fB\-\-external file[\fR\fImnt_id\fR\fB:\fR\fIinode\fR\fB]\fR

.RS 4

Dump an external file, i\&.e\&. an opened file that is can not be resolved from the current mount namespace, which can not be dumped without using this option\&. The file is identified by

\fImnt_id\fR

(a field obtained from

\fB/proc/\fR\fIpid\fR\fB/fdinfo/\fR\fIN\fR) and

\fIinode\fR

(as returned by

\fBstat\fR(2))\&.

.RE

.PP

\fB\-\-external tty[\fR\fIrdev\fR\fB:\fR\fIdev\fR\fB]\fR

.RS 4

Dump an external TTY, identified by

\fBst_rdev\fR

and

\fBst_dev\fR

fields returned by

\fBstat\fR(2)\&.

.RE

.PP

\fB\-\-external unix[\fR\fIid\fR\fB]\fR

.RS 4

Tell

\fBcriu\fR

that one end of a pair of UNIX sockets (created by

\fBsocketpair\fR(2)) with

\fIid\fR

is OK to be disconnected\&.

.RE

.PP

\fB\-\-freeze\-cgroup\fR

.RS 4

Use cgroup freezer to collect processes\&.

.RE

.PP

\fB\-\-manage\-cgroups\fR

.RS 4

Collect cgroups into the image thus they gonna be restored then\&. Without this option,

\fBcriu\fR

will not save cgroups configuration associated with a task\&.

.RE

.PP

\fB\-\-cgroup\-props\fR \fIspec\fR

.RS 4

Specify controllers and their properties to be saved into the image file\&.

\fBcriu\fR

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

.sp

\fIspec\fR

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

.sp

.if n \{\

.RS 4

.\}

.fam C

.ps -1

.nf

.BB lightgray

"c1":

 \- "strategy": "merge"

 \- "properties": ["a", "b"]

"c2":

 \- "strategy": "replace"

 \- "properties": ["c", "d"]

.EB lightgray

.fi

.fam

.ps +1

.if n \{\

.RE

.\}

.sp

where

\fIc1\fR

and

\fIc2\fR

are controllers names, and

\fIa\fR,

\fIb\fR,

\fIc\fR,

\fId\fR

are their properties\&.

.sp

Note the format: double quotes, spaces and new lines are required\&. The

\fIstrategy\fR

specifies what to do if a controller specified already exists as a built\-in one:

\fBcriu\fR

can either

\fBmerge\fR

or

\fBreplace\fR

such\&.

.sp

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

.sp

.if n \{\

.RS 4

.\}

.fam C

.ps -1

.nf

.BB lightgray

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

.EB lightgray

.fi

.fam

.ps +1

.if n \{\

.RE

.\}

.RE

.PP

\fB\-\-cgroup\-props\-file\fR \fIfile\fR

.RS 4

Same as

\fB\-\-cgroup\-props\fR, except the specification is read from the

\fIfile\fR\&.

.RE

.PP

\fB\-\-cgroup\-dump\-controller\fR \fIname\fR

.RS 4

Dump a controller with

\fIname\fR

only, skipping anything else that was discovered automatically (usually via

\fB/proc\fR)\&. This option is useful when one needs

\fBcriu\fR

to skip some controllers\&.

.RE

.PP

\fB\-\-cgroup\-props\-ignore\-default\fR

.RS 4

When combined with

\fB\-\-cgroup\-props\fR, makes

\fBcriu\fR

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

.RE

.PP

\fB\-\-tcp\-established\fR

.RS 4

Checkpoint established TCP connections\&.

.RE

.PP

\fB\-\-skip\-in\-flight\fR

.RS 4

This option skips in\-flight TCP connections\&. If any TCP connections that are not yet completely established are found,

\fBcriu\fR

ignores these connections, rather than errors out\&. The TCP stack on the client side is expected to handle the re\-connect gracefully\&.

.RE

.PP

\fB\-\-evasive\-devices\fR

.RS 4

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

.RE

.PP

\fB\-\-page\-server\fR

.RS 4

Send pages to a page server (see the

\fBpage\-server\fR

command)\&.

.RE

.PP

\fB\-\-force\-irmap\fR

.RS 4

Force resolving names for inotify and fsnotify watches\&.

.RE

.PP

\fB\-\-auto\-dedup\fR

.RS 4

Deduplicate "old" data in pages images of previous

\fBdump\fR\&. This option implies incremental

\fBdump\fR

mode (see the

\fBpre\-dump\fR

command)\&.

.RE

.PP

\fB\-l\fR, \fB\-\-file\-locks\fR

.RS 4

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

.RE

.PP

\fB\-\-link\-remap\fR

.RS 4

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

\fBrestore\fR)\&.

.RE

.PP

\fB\-\-ghost\-limit\fR \fIsize\fR

.RS 4

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

\fIsize\fR

may be postfixed with a

\fBK\fR,

\fBM\fR

or

\fBG\fR, which stands for kilo\-, mega, and gigabytes, accordingly\&.

.RE

.PP

\fB\-j\fR, \fB\-\-shell\-job\fR

.RS 4

Allow one to dump shell jobs\&. This implies the restored task will inherit session and process group ID from the

\fBcriu\fR

itself\&. This option also allows to migrate a single external tty connection, to migrate applications like

\fBtop\fR\&. If used with

\fBdump\fR

command, it must be specified with

\fBrestore\fR

as well\&.

.RE

.PP

\fB\-\-cpu\-cap\fR [\fIcap\fR[,\fIcap\fR\&...]]

.RS 4

Specify CPU capabilities to write to an image file\&. The argument is a comma\-separated list of: