Advanced usage - Revision history

Xemul: /* Restoring a VETH pair of devices */

2016-09-26T10:47:32Z

Restoring a VETH pair of devices

Kir: /* External bind mounts / links to lxc/docker, add / See also */

2016-09-21T19:13:21Z

External bind mounts: links to lxc/docker, add See also

Kir: it's -> its, other fixes, formatting improvements

2016-09-21T19:10:22Z

it's -> its, other fixes, formatting improvements

Kir: rm extra vertical whitespace

2016-09-21T19:06:37Z

rm extra vertical whitespace

Kir: Use template:opt, also NO LINKS IN HEADERS

2016-09-21T19:02:24Z

Use template:opt, also NO LINKS IN HEADERS

Xemul at 07:04, 21 September 2016

2016-09-21T07:04:52Z

Kir: /* Restoring a veth pair of devices */ use italic for variables

2016-09-20T23:23:50Z

Restoring a veth pair of devices: use italic for variables

Xemul: /* File locks C/R */

2016-09-17T14:11:59Z

File locks C/R

Xemul: /* Shell jobs C/R */

2016-09-08T23:17:31Z

Shell jobs C/R

Xemul: /* Restoring a veth pair of devices */

2016-09-08T23:11:52Z

Restoring a veth pair of devices

@@ Line 27: / Line 27: @@
 == Restoring a VETH pair of devices ==
-When you restore a net namespace with a VETH device end in it, CRIU will create the other end of the pair in the net namespace you launch CRIU from. By default its name will be the one generated by the <code>veth</code> kernel driver. Not to scan through all the net devices trying to find one, you can use the {{Opt|--veth-pair|ns-dev'':''host-dev}} option. When used a device named <code>''ns-dev''</code> in a newly restored namespace will be linked with the <code>''host-dev''</code> one in the CRIU namespace.
+When you restore a net namespace with a VETH device end in it, CRIU will create the other end of the pair in the net namespace you launch CRIU from. By default its name will be the one generated by the <code>veth</code> kernel driver. Not to scan through all the net devices trying to find one, you can use the {{Opt|--external}} option. For more details see the article about [[VETH device]].
 == Action scripts ==

@@ Line 54: / Line 54: @@
 == External bind mounts ==
-When dumping LXC or Docker container you will likely meet those. The {{Opt|--ext-mount-map}} option should be used for such situations.
+When dumping [[LXC]] or [[Docker]] container, one will likely meet those. The {{Opt|--ext-mount-map}} option should be used for such situations.
 [[Category:API]]

@@ Line 19: / Line 19: @@
 == Per-task logging on restore ==
-By default criu puts all logs into one log file specified by {{Opt|--log-file}} option. If you want to split restoration logs on per-pid basis you can use the {{Opt|--log-pid}} option. The logs of a <code>''pid''</code> task will appear in a <code>''logfile''.''pid''</code> file.
+By default criu puts all logs into one log file specified by {{Opt|--log-file|file}} option. If you want to split restoration logs on per-PID basis you can use the {{Opt|--log-pid}} option. The logs of a task having PID of N will appear in a <code>''file''.''N''</code> file.
 == Knowing a new PID of restored task ==
-When you restore a process tree that lives inside a PID namespace, the pid of a new task will be generated by the system (since the pids sitting in image files are treated as virtual, i.e. seen in namespace ones). To find this pid out you can use the {{Opt|--pidfile|file}} option to make criu put the new PID into <code>''file''</code>.
+When you restore a process tree that lives inside a PID namespace, the PID of a new task will be generated by the system (since the PIDs sitting in image files are treated as virtual, i.e. as seen in a PID namespace). To find out the PID, one can use the {{Opt|--pidfile|file}} option to make CRIU put the new PID into <code>''file''</code>.
-== Restoring a veth pair of devices ==
+== Restoring a VETH pair of devices ==
-When you restore a net namespace with a veth device end in it, criu will create the other end of the pair in the net namespace you launch criu from. By default it's name will be the one generated by veth kernel driver. Not to scan through all the net devices trying to fine one you can use the {{Opt|--veth-pair|ns-dev:host-dev}} option. When used a device named <code>''ns-dev''</code> in a newly restored namespace will be linked with the <code>''host-dev''</code> one in the criu namespace.
+When you restore a net namespace with a VETH device end in it, CRIU will create the other end of the pair in the net namespace you launch CRIU from. By default its name will be the one generated by the <code>veth</code> kernel driver. Not to scan through all the net devices trying to find one, you can use the {{Opt|--veth-pair|ns-dev'':''host-dev}} option. When used a device named <code>''ns-dev''</code> in a newly restored namespace will be linked with the <code>''host-dev''</code> one in the CRIU namespace.
 == Action scripts ==

← Older revision		Revision as of 19:06, 21 September 2016
Line 28:		Line 28:

	When you restore a net namespace with a veth device end in it, criu will create the other end of the pair in the net namespace you launch criu from. By default it's name will be the one generated by veth kernel driver. Not to scan through all the net devices trying to fine one you can use the {{Opt\|--veth-pair\|ns-dev:host-dev}} option. When used a device named <code>''ns-dev''</code> in a newly restored namespace will be linked with the <code>''host-dev''</code> one in the criu namespace.		When you restore a net namespace with a veth device end in it, criu will create the other end of the pair in the net namespace you launch criu from. By default it's name will be the one generated by veth kernel driver. Not to scan through all the net devices trying to fine one you can use the {{Opt\|--veth-pair\|ns-dev:host-dev}} option. When used a device named <code>''ns-dev''</code> in a newly restored namespace will be linked with the <code>''host-dev''</code> one in the criu namespace.
−

	== Action scripts ==		== Action scripts ==

@@ Line 3: / Line 3: @@
 == Evasive devices ==
-Sometimes an application opens a device file and then somehow the path by which it was opened becomes inaccessible (e.g. overmounted or unlinked). In that case criu cannot easily dump and restore such a process. If you consider that the path doesn't really matter when dumping your apps state you can tell criu that a device file can be opened by '''any''' name, even if the original one is no longer accessible. The option for that is <code>--evasive-devices</code>
+Sometimes an application opens a device file and then somehow the path by which it was opened becomes inaccessible (e.g. overmounted or unlinked). In that case criu cannot easily dump and restore such a process. If you consider that the path doesn't really matter when dumping your apps state you can tell criu that a device file can be opened by '''any''' name, even if the original one is no longer accessible. The option for that is {{Opt|--evasive-devices}}.
 == External UNIX sockets ==
-Consider an application opens a datagram UNIX socket and connects it to some address. If you will try to dump such app and the server socket for some reason will '''not''' be taken in the dumped state (e.g. -- a task holding it is not dumped) the dump will fail. You can override this behavior by allowing criu to disconnect the client after dump and re-connecting it back on restore by the server socket path using the <code>--ext-unix-sk</code> option.
+Consider an application opens a datagram UNIX socket and connects it to some address. If you will try to dump such app and the server socket for some reason will '''not''' be taken in the dumped state (e.g. -- a task holding it is not dumped) the dump will fail. You can override this behavior by allowing criu to disconnect the client after dump and re-connecting it back on restore by the server socket path using the {{Opt|--ext-unix-sk}} option.
 == Link unlinked files back ==
-When an app opens a file and then unlinks it we take this file with us into image. However, we do so only if the file is ''really'' unlinked, i.e. its n_link is zero. Otherwise we cannot take file with us and should somehow open the inode. To do so we should create a temporary hardlink on it during dump, open it on restore and unlink again. The <code>--link-remap</code> option allows criu to create this temporary hard links on FS.
+When an app opens a file and then unlinks it we take this file with us into image. However, we do so only if the file is ''really'' unlinked, i.e. its n_link is zero. Otherwise we cannot take file with us and should somehow open the inode. To do so we should create a temporary hardlink on it during dump, open it on restore and unlink again. The {{Opt|--link-remap}} option allows criu to create this temporary hard links on FS.
 == TCP connections ==
-When dumping and restoring an application having an opened TCP connection you should use the <code>--tcp-established</code> option. When this option is in use criu will leave the connection(s) locked after dump and will require it(them) to be still locked before restore. Article [[Simple TCP pair]] describes how to play with this option.
+When dumping and restoring an application having an opened TCP connection you should use the {{Opt|--tcp-established}} option. When this option is in use criu will leave the connection(s) locked after dump and will require it(them) to be still locked before restore. Article [[Simple TCP pair]] gives an example of using this option.
 == Per-task logging on restore ==
-By default criu puts all logs into one log file specified by <code>-o/--log-file</code> option. If you want to split restoration logs on per-pid basis you can use the <code>--log-pid</code> option. The <code>${pid}</code> task's logs will appear in a <code>${log-file}.pid</code>
+By default criu puts all logs into one log file specified by {{Opt|--log-file}} option. If you want to split restoration logs on per-pid basis you can use the {{Opt|--log-pid}} option. The logs of a <code>''pid''</code> task will appear in a <code>''logfile''.''pid''</code> file.
-''See also [[CLI/opt/--log-pid]]''
+== Knowing a new PID of restored task ==
-== Knowing a new pid of restored task ==
+When you restore a process tree that lives inside a PID namespace, the pid of a new task will be generated by the system (since the pids sitting in image files are treated as virtual, i.e. seen in namespace ones). To find this pid out you can use the {{Opt|--pidfile|file}} option to make criu put the new PID into <code>''file''</code>.
 == Restoring a veth pair of devices ==
-When you restore a net namespace with a veth device end in it, criu will create the other end of the pair in the net namespace you launch criu from. By default it's name will be the one generated by veth kernel driver. Not to scan through all the net devices trying to fine one you can use the <code>--veth-pair ''ns-dev'':''host-dev''</code> option. When used a device named <code>''ns-dev''</code> in a newly restored namespace will be linked with the <code>''host-dev''</code> one in the criu namespace.
+When you restore a net namespace with a veth device end in it, criu will create the other end of the pair in the net namespace you launch criu from. By default it's name will be the one generated by veth kernel driver. Not to scan through all the net devices trying to fine one you can use the {{Opt|--veth-pair|ns-dev:host-dev}} option. When used a device named <code>''ns-dev''</code> in a newly restored namespace will be linked with the <code>''host-dev''</code> one in the criu namespace.
 == Action scripts ==
-The '''criu''' can call your hooks on various stages of dumping/restoring. These hooks are added with the <code>--action-script ''shell-code-to-execute''</code> option. When called, the <code>CRTOOLS_SCRIPT_ACTION</code> environment is set to a value determining which type of action is performed. See [[Action scripts]] for more details.
+CRIU can call your hooks on various stages of dumping/restoring. These hooks are added with the {{Opt|--action-script|shell-code-to-execute}} option. When called, the <code>CRTOOLS_SCRIPT_ACTION</code> environment is set to a value determining which type of action is performed.
 == Shell jobs C/R ==
-When you run some app directly from shell (e.g. -- just launch top) it inherits session ID from bash and uses pty whose other end sits somewhere outside this shell session (e.g. in sshd or xterm). Strictly speaking this app cannot be checkpointed (since session leader, which is bash, is left outside the image, and so is the pty master). Nor it can be restored easily. But sometimes it might make sense to migrate such app by moving it to other session and attaching to different pty slave "on the fly". For such cases the <code>--shell-job</code> option should be used on both stages -- dump and restore. On dump it will allow criu to ignore the "leaked" session leader and pty master, on restore it will tell criu to change session, group and attach to existing pty slave.
+When you run some app directly from the shell (e.g. <code>top</code>), it inherits session ID from bash and uses PTY whose other end sits somewhere outside this shell session (e.g. in sshd or xterm). Strictly speaking this app cannot be checkpointed (since session leader, which is bash, is left outside the image, and so is the pty master). Nor it can be restored easily. But sometimes it might make sense to migrate such app by moving it to other session and attaching to different pty slave "on the fly". For such cases the {{Opt|--shell-job}} option should be used on both dump and restore. On dump, it will allow CRIU to ignore the "leaked" session leader and pty master. On restore, it will tell CRIU to change session, group and attach to existing pty slave.
 == File locks C/R ==
-Some app may use file locks for synchronization. Generally they will use flock or posix file locks, which were achieved by flock or fcntl system calls. For dump/restore, it is hard to be handled perfectly, because we can't guarantee all potential users are dumped for a specific file lock. Right now, we assume that all file lock users are taken into dump, and we should use the --file-locks option on both dump and restore stages if our app may use any file locks. Remember that file locks dump/restore is only safe for container dumping in theory.
+Some app may use file locks for synchronization. Generally they will use flock or posix file locks, which were achieved by flock or fcntl system calls. For dump/restore, it is hard to be handled perfectly, because we can't guarantee all potential users are dumped for a specific file lock. Right now, we assume that all file lock users are taken into dump, and we should use the {{Opt|--file-locks}} option on both dump and restore stages if our app may use any file locks. Remember that file locks dump/restore is only safe for container dumping in theory.
 == Leave task running after checkpoint ==
-In some scenarios a user might want to leave program in a running state once checkpoint complete. For this sake '''criu''' has <code>--leave-running</code> command line option. We strongly encourage '''NOT''' to use it, until you understand what you are doing. Leaving task in a running state may lead to inconsistency between task images and external resources such as opened files, TCP connections.
+In some scenarios a user might want to leave program in a running state once checkpoint complete. To do that, criu has {{Opt|--leave-running}} command line option. We strongly encourage NOT to use it, until you understand what you are doing. Leaving task in a running state may lead to inconsistency between task images and external resources such as opened files, TCP connections.
-* No established TCP connections are present
+Imagine a task been dumped and then continue execution, for some reason the task close and delete a file which has been checkpointed — any attempt to restore such task will simply fail because CRIU wont be able to open deleted file. Situation become more drastic if TCP connections are checkpointed — during execution the internal state of connections is changed inside kernel and restore then fail as well.
-''See also [[CLI/opt/--leave-running]]''
+Still, leaving task running might be helpful but it is up to a user to make sure that:
-== [[External bind mounts]] ==
+* no established TCP connections are present;
-When dumping LXC or Docker container you will likely meet those. The <code>--ext-mount-map</code> option is to handle ones.
+== External bind mounts ==
-''See also [[CLI/opt/--ext-mount-map]]''
+When dumping LXC or Docker container you will likely meet those. The {{Opt|--ext-mount-map}} option should be used for such situations.
 [[Category:API]]

@@ Line 29: / Line 29: @@
 == Restoring a veth pair of devices ==
-When you restore a net namespace with a veth device end in it, criu will create the other end of the pair in the net namespace you launch criu from. By default it's name will be the one generated by veth kernel driver. Not to scan through all the net devices trying to fine one you can use the <code>--veth-pair <ns-dev>:<host-dev></code> option. When used a device named <code><ns-dev></code> in a newly restored namespace will be linked with the <code><host-dev></code> one in the criu namespace.
+When you restore a net namespace with a veth device end in it, criu will create the other end of the pair in the net namespace you launch criu from. By default it's name will be the one generated by veth kernel driver. Not to scan through all the net devices trying to fine one you can use the <code>--veth-pair ''ns-dev'':''host-dev''</code> option. When used a device named <code>''ns-dev''</code> in a newly restored namespace will be linked with the <code>''host-dev''</code> one in the criu namespace.
 ''See also: [[VETH device]]''

← Older revision		Revision as of 14:11, 17 September 2016
Line 46:		Line 46:

	Some app may use file locks for synchronization. Generally they will use flock or posix file locks, which were achieved by flock or fcntl system calls. For dump/restore, it is hard to be handled perfectly, because we can't guarantee all potential users are dumped for a specific file lock. Right now, we assume that all file lock users are taken into dump, and we should use the --file-locks option on both dump and restore stages if our app may use any file locks. Remember that file locks dump/restore is only safe for container dumping in theory.		Some app may use file locks for synchronization. Generally they will use flock or posix file locks, which were achieved by flock or fcntl system calls. For dump/restore, it is hard to be handled perfectly, because we can't guarantee all potential users are dumped for a specific file lock. Right now, we assume that all file lock users are taken into dump, and we should use the --file-locks option on both dump and restore stages if our app may use any file locks. Remember that file locks dump/restore is only safe for container dumping in theory.
		+
		+	''See also: [[File locks]]''

	== Leave task running after checkpoint ==		== Leave task running after checkpoint ==

@@ Line 41: / Line 41: @@
 When you run some app directly from shell (e.g. -- just launch top) it inherits session ID from bash and uses pty whose other end sits somewhere outside this shell session (e.g. in sshd or xterm). Strictly speaking this app cannot be checkpointed (since session leader, which is bash, is left outside the image, and so is the pty master). Nor it can be restored easily. But sometimes it might make sense to migrate such app by moving it to other session and attaching to different pty slave "on the fly". For such cases the <code>--shell-job</code> option should be used on both stages -- dump and restore. On dump it will allow criu to ignore the "leaked" session leader and pty master, on restore it will tell criu to change session, group and attach to existing pty slave.
-If you want to see how it works, check [[Simple loop]].
+''See also: [[Simple loop]], [[Shell jobs]]
 == File locks C/R ==

← Older revision		Revision as of 23:11, 8 September 2016
Line 30:		Line 30:

	When you restore a net namespace with a veth device end in it, criu will create the other end of the pair in the net namespace you launch criu from. By default it's name will be the one generated by veth kernel driver. Not to scan through all the net devices trying to fine one you can use the <code>--veth-pair <ns-dev>:<host-dev></code> option. When used a device named <code><ns-dev></code> in a newly restored namespace will be linked with the <code><host-dev></code> one in the criu namespace.		When you restore a net namespace with a veth device end in it, criu will create the other end of the pair in the net namespace you launch criu from. By default it's name will be the one generated by veth kernel driver. Not to scan through all the net devices trying to fine one you can use the <code>--veth-pair <ns-dev>:<host-dev></code> option. When used a device named <code><ns-dev></code> in a newly restored namespace will be linked with the <code><host-dev></code> one in the criu namespace.
		+
		+	''See also: [[VETH device]]''

	== Action scripts ==		== Action scripts ==