Line 1: |
Line 1: |
− | This explains the meaning of "external socket is used" error message, and the purpose of <code>--ext-unix-sk</code> option. | + | This explains the meaning of '''external socket is used''' error message, and the purpose of '''<code>--external unix[...]</code>''' option. |
| | | |
− | == Unix socket consistency check == | + | == Error meaning == |
| | | |
− | When dumping a process sub-tree, crtools checks that the resulting image is consistent and self-contained, meaning if an object A references another object B, and A goes into dump, then B should be dumped as well. For example, if there is a pipe, and crtools dumps its one end (object A) because it belongs to a process it dumps, it must also dump the other end of the pipe (object B), meaning it should take a process owning B into the image as well. Same is true for unix sockets: if there is a socket (A) that is <code>connect()</code>ed to another socket (B), and crtools dumps socket A (because it is opened by a process it dumps), it must also dump socket B and the task who owns it. Possibly socket B is dumped some time later in the dumping process, but it must be dumped. | + | When dumping a process sub-tree, criu checks that the resulting image is consistent and self-contained, meaning if an object A references another object B, and A goes into dump, then B should be dumped as well. For example, if there is a pipe, and criu dumps its one end (object A) because it belongs to a process it dumps, it must also dump the other end of the pipe (object B), meaning it should take a process owning B into the image as well. Same is true for unix sockets: if there is a socket (A) that is <code>connect()</code>ed to another socket (B), and criu dumps socket A (because it is opened by a process it dumps), it must also dump socket B and the task who owns it. Possibly socket B is dumped some time later in the dumping process, but it must be dumped. |
| | | |
| This restriction is in place to make sure that upon restore applications will continue to work, rather than, say, receive SIGPIPE signals due to half-closed pipes or sockets. | | This restriction is in place to make sure that upon restore applications will continue to work, rather than, say, receive SIGPIPE signals due to half-closed pipes or sockets. |
| | | |
− | With that said, "external socket is used" error means crtools detected a unix socket connected to another socket which is not being dumped (because it belongs to a process not going into the image). | + | With that said, "external socket is used" error means criu detected a unix socket connected to another socket which is not being dumped (because it belongs to a process not going into the image). |
| | | |
− | == Using --ext-unix-sk == | + | == Using the option == |
| | | |
− | However, sometimes it is possible to dump and successfully restore only one end of a unix socket pair. One particular example is the <code>logd</code>, a daemon which opens a datagram unix socket and waits on it for messages to be written into a log file. Processes using logd also create datagram unix sockets and connect those to the logd socket. These connections are thus uni-directional, meaning that the logd's socket remains unconnected. In this case it is possible to dump a program using logd as a client. For it to work after restore its socket needs to be reconnected back to logd using the logd's socket name. | + | However, sometimes it is possible to dump and successfully restore only one end of a unix socket pair. One particular example is the datagram sockets with on-way connection (client to server) used e.g. by <code>logd</code>. Server opens a datagram socket and waits on it for messages to be written into a log file. Processes using logd also create datagram sockets and connect those to the server. These connections are thus uni-directional. In this case it is possible to dump a program with the client-side socket and on restore the socket needs to be reconnected back to the original server. |
| | | |
− | This is when <code>--ext-unix-sk</code> option should be used. By providing this option (for both dump and restore commands), user states "I know there may be uni-directional unix connections, and I will make sure the server end will exist on restore". | + | This is when {{Opt|--external}} option should be used. By providing this option for both dump (now) and restore (in plans) commands, user states "I know there may be uni-directional dgram unix connections, and I will make sure the server end will exist on restore". |
| | | |
− | For '''crtools dump''', this option enables dumping unix sockets with additional information about that other ("external") socket it is connected to. | + | For '''criu dump''', this option enables dumping ''datagram'' unix sockets with additional information about that other ("external") socket it is connected to. |
| | | |
− | For '''crtools restore''', this option asks crtools to re-connect such sockets back. | + | For '''criu restore''', this option asks criu to re-connect such sockets back. |
| + | |
| + | == Limitations == |
| + | |
| + | Some types of sockets are hard to deal with. |
| + | |
| + | === stream/seqpacket === |
| + | |
| + | Named unix sockets with stream/seqpacket options can't be dumped/restored, as once we dump one end, |
| + | the other one will see EOF on the socket and may close it. |
| + | |
| + | The plan for this is to extend the <code>--external unix[...]</code> semantics to work like this: |
| + | |
| + | * On dump, the <code>--external unix[id]</code> says that socket with <code>''id''</code> is OK to be disconnected |
| + | * On restore, the <code>--external unix[''id'']:''path''</code> says that the socket <code>''id''</code> should be reconnected back to the path it say on dump (or to the specified <code>''path''</code>) (THIS IS IN PLANS!) |
| + | |
| + | === socketpair === |
| + | |
| + | Unnamed unix sockets created with <code>socketpair()</code> system call can be dumped and restored. |
| + | |
| + | On dump, tell inode of this socket to CRIU, like this |
| + | |
| + | criu dump -D images -o dump.log -v4 --external unix[11890815] -t 16528 |
| + | |
| + | On restore, the server should create a new pair and call <code>criu restore</code> asking it to [[Inheriting FDs on restore|inherit]] one. |
| + | For example: |
| + | |
| + | criu restore -d -D images -o restore.log --pidfile restore.pid -v4 -x --inherit-fd fd[3]:socket:[11890815] |
| + | |
| + | Test is available for this feature, see test/socketpairs in criu sources. |
| + | |
| + | == Old days == |
| + | |
| + | For now the same thing is specified with <code>-x|--ext-unix-sk</code> option. Note, that the <code>id</code> argument was optional and made CRIU treat as external any unconnected socket. Soon this option will be [[deprecation|deprecated]]. |
| | | |
| == See also == | | == See also == |
| | | |
| * [[Advanced usage]] | | * [[Advanced usage]] |
| + | * [[Inheriting FDs on restore]] |
| + | |
| + | [[Category:HOWTO]] |
| + | [[Category:API]] |
| + | [[Category:External]] |
| + | [[Category:Sockets]] |