Changes

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

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

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

end in the checkpointed process and the other end in a separate process

In these cases, criu's caller should set up a new file descriptor to be

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

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

Please note that inherit fd support breaks applications that depend

at a different seek offset.

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

for sure won't break the application.  In other words, use it at your

own risk.

own risk.

== Argument Format ==

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

handled specially by the command line shell, they might need to be properly escaped).

As a debugging aid, if the argument has the format debug[%d]:%s, criu

will just write out the string after colon to the file descriptor %d.

 

As a debugging aid, if the argument has the format <code>debug[%d]:%s</code>, criu

will just write out the string after colon to the file descriptor <code>%d</code>.

This can be used to leave a "restore marker" in the output stream of

This can be used to leave a "restore marker" in the output stream of

the process.

the process.

== Example 1 - Regular Files ==

== Examples ==

 

=== Regular files ===

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.

output file.

As you see below, we have used criu's file descriptor 7 (just as an

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>

<pre>

This is an example of an application that does not depend on the state

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,

If your application depends on a particular state, say the seek offset,

descriptor.

descriptor.

== Example 2 - External Unnamed Pipes ==

=== External unnamed pipes ===

To replace an external pipe that was connected to an external process

To replace an external pipe that was connected to an external process

simplicity, we're having the parent checkpoint the child.

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>

<pre>

</pre>

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

<pre>

</pre>

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

<pre>