Inheriting FDs on restore - Revision history

Radostin: /* External TTYs */

2020-07-19T12:19:31Z

External TTYs

Radostin: /* External TTYs */

2020-07-19T12:19:07Z

External TTYs

Kir: /* External TTYs */ explain why mnt_id:inode is not used for TTYs

2016-11-01T06:26:56Z

External TTYs: explain why mnt_id:inode is not used for TTYs

Kir: formatting: use italic for replaceables

2016-11-01T04:49:54Z

formatting: use italic for replaceables

Kir: /* External files, FIFOs */ fix a typo

2016-11-01T04:47:39Z

External files, FIFOs: fix a typo

Xemul at 09:14, 21 September 2016

2016-09-21T09:14:33Z

Xemul at 19:16, 15 September 2016

2016-09-15T19:16:38Z

Kir: /* Regular files */ fix english

2016-09-14T21:45:13Z

Regular files: fix english

Kir: formatting fixes, slight rewording

2016-09-14T21:44:40Z

formatting fixes, slight rewording

Kir: added to cli category

2016-09-14T21:34:53Z

added to cli category

@@ Line 147: / Line 147: @@
      # criu dump -t `pgrep ipython` --external 'tty[8802:19]'
-     # criu restore --inherit-fd 'fd[1]:tty[8802:9]'
+     # criu restore --inherit-fd 'fd[1]:tty[8802:19]'
 </pre>

@@ Line 140: / Line 140: @@
 Here is an example of dumping and restoring an external TTY:
 <pre>
-     $ ipython
+     # setsid --ctty ipython
      In [1]: import os
      In [2]: st = os.stat("/proc/self/fd/0")
-     In [3]: print "tty[%x:%x]" % (st.st_rdev, st.st_dev)
+     In [3]: print("tty[%x:%x]" % (st.st_rdev, st.st_dev))
-     tty:[8800:d]
+     tty[8802:19]
-−
-    $ps -C sleep
+     # criu dump -t `pgrep ipython` --external 'tty[8802:19]'
-      PID TTY          TIME CMD
+     # criu restore --inherit-fd 'fd[1]:tty[8802:9]'
 </pre>

@@ Line 136: / Line 136: @@
 === External TTYs ===
-The format of tty id is <code>tty[''rdev'':''dev'']</code>. Why can we not use a pair of <code>mnt_id</code> and <code>inode</code> here?
+The format of tty id is <code>tty[''rdev'':''dev'']</code>. Note that a pair of <code>''mnt_id'':''inode''</code> is not used here, as there can be two device files with the same <code>''rdev''</code> but different inode numbers.
 <pre>
      $ ipython

@@ Line 127: / Line 127: @@
 === External files, FIFOs ===
-"criu dump" tries to resolve paths for each files, so the first example works only for files which can be resolved from dumped mount namespaces. If we have a file from another namespace, we call it as "external" and criu isn't able to restore it without external help. We need to enumerate all external files on dump and set inherit file descriptors on restore. This descriptors will be used only to open a file via <code>/proc/self/fd</code>, so it doesn't matter with which flags an inherited descriptor has been opened. The format of file id is <code>file[mnt_id:inode]</code>.
+"criu dump" tries to resolve paths for each files, so the first example works only for files which can be resolved from dumped mount namespaces. If we have a file from another namespace, we call it as "external" and criu isn't able to restore it without external help. We need to enumerate all external files on dump and set inherit file descriptors on restore. This descriptors will be used only to open a file via <code>/proc/self/fd</code>, so it doesn't matter with which flags an inherited descriptor has been opened. The format of file id is <code>file[''mnt_id'':''inode'']</code>.
 <pre>
@@ Line 136: / Line 136: @@
 === External TTYs ===
-The format of tty id is <code>tty[rdev:dev]</code>. Why can we not use a pair of <code>mnt_id</code> and <code>inode</code> here?
+The format of tty id is <code>tty[''rdev'':''dev'']</code>. Why can we not use a pair of <code>mnt_id</code> and <code>inode</code> here?
 <pre>

@@ Line 127: / Line 127: @@
 === External files, FIFOs ===
-"criu dump" tries to resolve paths for each files, so the first example works only for files which can be resolved from dumped mount namespaces. If we have a file from another namespace, we call it as "external" and criu isn't able to restore it without external help. We need to enumerate all external files on dump and set inherit file descriptors on restore. This descriptors will be used only to open a file via <code>/proc/self/fd</code>, so it doesn't metter with which flags an inherited descriptor has been opened. The format of file id is <code>file[mnt_id:inode]</code>.
+"criu dump" tries to resolve paths for each files, so the first example works only for files which can be resolved from dumped mount namespaces. If we have a file from another namespace, we call it as "external" and criu isn't able to restore it without external help. We need to enumerate all external files on dump and set inherit file descriptors on restore. This descriptors will be used only to open a file via <code>/proc/self/fd</code>, so it doesn't matter with which flags an inherited descriptor has been opened. The format of file id is <code>file[mnt_id:inode]</code>.
 <pre>

← Older revision		Revision as of 09:14, 21 September 2016
Line 1:		Line 1:
−	This article describes why and how to use the <code>--inherit-fd</code> command line ~~option~~.	+	This article describes why and how to use the <code>--external file[...]</code>, <code>--external tty[...]</code> and <code>--inherit-fd</code> command line options.

	== Background ==		== Background ==

@@ Line 156: / Line 156: @@
 [[Category:HOWTO]]
 [[Category:API]]
 [[Category:Files]]
 [[Category:External]]

@@ Line 51: / Line 51: @@
 === Regular files ===
-Let's redirect the output of <code>test.sh</code> from [[Simple loop]]
+Let's redirect the output of <code>test.sh</code> from the [[simple loop]] example
 to <code>/tmp/old</code>, checkpoint it, and restore it to use <code>/tmp/new</code> as its
 output file.

@@ Line 1: / Line 1: @@
-This HOWTO page describes how to use the --inherit-fd command line option.
+This article describes why and how to use the <code>--inherit-fd</code> command line option.
 == Background ==
-There are cases where a process's file descriptor cannot be restored
+There are cases where a process' file descriptor cannot be restored
 from the checkpoint images.  For example, a pipe file descriptor with one
 end in the checkpointed process and the other end in a separate process
@@ Line 16: / Line 16: @@
 In these cases, criu's caller should set up a new file descriptor to be
 inherited by the restored process and specify the file descriptor with
-the --inherit-fd command line option.
+the <code>--inherit-fd</code> command line option.
-== Warning ==
+== Limitations ==
 Please note that inherit fd support breaks applications that depend
@@ Line 26: / Line 26: @@
 at a different seek offset.
-You should consider inherit fd only for specific use cases that you know
+You should consider using this feature only for specific use cases that you know
 for sure won't break the application.  In other words, use it at your
 own risk.
@@ Line 32: / Line 32: @@
 == Argument Format ==
-The argument of --inherit-fd has the format fd[%d]:%s, where %d tells
+The argument of <code>--inherit-fd</code> has the format <code>fd[%d]:%s</code>,
-criu which of its own file descriptors to use for restoring the file
+where <code>%d</code> tells criu which of its own file descriptors to use
-identified by %s.
+for restoring the file identified by <code>%s</code>. Note that the file descriptor
-== Debugging Aid ==
+Example: <code>criu restore ... --inherit-fd 'fd[7]:tmp/old' ...</code>
-As a debugging aid, if the argument has the format debug[%d]:%s, criu
+== Debugging aid ==
 will just write out the string after colon to the file descriptor %d.
 This can be used to leave a "restore marker" in the output stream of
 the process.
-== Example 1 - Regular Files ==
+== Examples ==
-Let's redirect the output of test.sh from [[Simple loop]]
+Let's redirect the output of <code>test.sh</code> from [[Simple loop]]
-to /tmp/old, checkpoint it, and restore it to use /tmp/new as its
+to <code>/tmp/old</code>, checkpoint it, and restore it to use <code>/tmp/new</code> as its
 output file.
 As you see below, we have used criu's file descriptor 7 (just as an
-arbitrary descriptor) with the --inherit-fd option.  Notice that the path
+arbitrary descriptor) with the <code>--inherit-fd</code> option. Note that the file path
-in the argument of --inherit-fd is relative to the root of the process
+in the argument of <code>--inherit-fd</code> is relative to the root of the process
-(i.e., tmp/old).
+(i.e., <code>tmp/old</code>).
 <pre>
@@ Line 62: / Line 68: @@
 This is an example of an application that does not depend on the state
-of its output file, so --inherit-fd wouldn't break it.
+of its output file, so <code>--inherit-fd</code> wouldn't break it.
 If your application depends on a particular state, say the seek offset,
@@ Line 68: / Line 74: @@
 descriptor.
-== Example 2 - External Unnamed Pipes ==
+=== External unnamed pipes ===
 To replace an external pipe that was connected to an external process
@@ Line 88: / Line 94: @@
 simplicity, we're having the parent checkpoint the child.
-The source code for pipe.c can be found in criu source tree under
+The source code for <code>pipe.c</code> can be found in criu source tree under
-test/pipes.  Each output line is preceded by the process that has
+<code>test/pipes</code>.  Each output line is preceded by the process that has
-generated it.  Notice pipe:[472728] is replaced with pipe:[474324]
+generated it.  Notice <code>pipe:[472728]</code> is replaced with <code>pipe:[474324]</code>
-passed through criu's fd[3].
+passed through criu's <code>fd[3]</code>.
 <pre>
@@ Line 120: / Line 126: @@
 </pre>
-== Example 3 - External files, FIFO-s ==
+=== External files, FIFOs ===
-"criu dump" tries to resolve paths for each files, so the first example works only for files which can be resolved from dumped mount namespaces. If we have a file from another namespace, we call it as "external" and criu isn't able to restore it without external help. We need to enumerate all external files on dump and set inherit file descriptors on restore. This descriptors will be used only to open a file via /proc/self/fd, so it doesn't metter with which flags an inherited descriptor has been opened. The format of file id is file[mnt_id:inode].
+"criu dump" tries to resolve paths for each files, so the first example works only for files which can be resolved from dumped mount namespaces. If we have a file from another namespace, we call it as "external" and criu isn't able to restore it without external help. We need to enumerate all external files on dump and set inherit file descriptors on restore. This descriptors will be used only to open a file via <code>/proc/self/fd</code>, so it doesn't metter with which flags an inherited descriptor has been opened. The format of file id is <code>file[mnt_id:inode]</code>.
 <pre>
@@ Line 128: / Line 134: @@
 </pre>
-== Example 4 - External TTY-s ==
+=== External TTYs ===
-The format of tty id is tty[rdev:dev]. Why can we not use a pair of mnt_id and inode here?
+The format of tty id is <code>tty[rdev:dev]</code>. Why can we not use a pair of <code>mnt_id</code> and <code>inode</code> here?
 <pre>