Difference between revisions of "External UNIX socket"

m (→‎Using the option: use template:opt)
 
(13 intermediate revisions by 2 users not shown)
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.
  
 
== Error meaning ==
 
== Error meaning ==
Line 13: Line 13:
 
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.
 
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 dgram 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 '''criu dump''', this option enables dumping ''datagram'' 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.
Line 20: Line 20:
  
 
== Limitations ==
 
== Limitations ==
Named unix sockets with stream/seqpacket options can't be dumped\restored now, see plan below.
 
  
== What to do with stream/seqpacket? ==
+
Some types of sockets are hard to deal with.
  
Such sockets cannot be just dumped and restored as once we dump one end, the other one seen EOF on socket and may close one. The plan for this is to extend the --ext-unix-sk semantics to work like this
+
=== stream/seqpacket ===
  
* On dump the <code>--ext-unix-sk $id</code> says that socket with $id is OK to be disconnected
+
Named unix sockets with stream/seqpacket options can't be dumped/restored, as once we dump one end,
* On restore the <code>--ext-unix-sk$id[=$path]</code> says that the socket $id should be reconnected back to the path it say on dump (or to the $path).
+
the other one will see EOF on the socket and may close it.
  
== What to do with socketpair()-s? ==
+
The plan for this is to extend the <code>--external unix[...]</code> semantics to work like this:
Unnamed unix sockets created with socketpair() systemcall can be dumped and restored.
 
For dump socketpair put inode of this socket in <code>--ext-unix-sk</code> option, for example:
 
  
<code>
+
* On dump, the <code>--external unix[id]</code> says that socket with <code>''id''</code> is OK to be disconnected
criu dump -D images -o dump.log -v4 --ext-unix-sk=11890815 -t 16528
+
* 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!)
</code>
 
  
For restore socketpair the server should create new pair and call criu restore asking it to [[Inheriting FDs on restore|inherit]] one. Example of command:
+
=== socketpair ===
  
<code>
+
Unnamed unix sockets created with <code>socketpair()</code> system call can be dumped and restored.
criu restore -d -D images -o restore.log --pidfile restore.pid -v4 -x --inherit-fd fd[3]:socket:[11890815]
 
</code>
 
  
test source code also available for this feature and can be found in criu source tree under test/socketpairs.
+
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:HOWTO]]
[[Category:Network]]
+
[[Category:API]]
 
[[Category:External]]
 
[[Category:External]]
 +
[[Category:Sockets]]

Latest revision as of 22:01, 23 June 2017

This explains the meaning of external socket is used error message, and the purpose of --external unix[...] option.

Error meaningEdit

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 connect()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.

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 the optionEdit

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 logd. 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 --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 criu dump, this option enables dumping datagram unix sockets with additional information about that other ("external") socket it is connected to.

For criu restore, this option asks criu to re-connect such sockets back.

LimitationsEdit

Some types of sockets are hard to deal with.

stream/seqpacketEdit

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 --external unix[...] semantics to work like this:

  • On dump, the --external unix[id] says that socket with id is OK to be disconnected
  • On restore, the --external unix[id]:path says that the socket id should be reconnected back to the path it say on dump (or to the specified path) (THIS IS IN PLANS!)

socketpairEdit

Unnamed unix sockets created with socketpair() 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 criu restore asking it to 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 daysEdit

For now the same thing is specified with -x|--ext-unix-sk option. Note, that the id argument was optional and made CRIU treat as external any unconnected socket. Soon this option will be deprecated.

See alsoEdit