RPC

CRIU-RPC is a remote procedure call (RPC) protocol which uses Google Protocol Buffers to encode its calls. The requests are served by CRIU when either launched in so called "swrk" mode or by a service started with the criu service command. It uses a SEQPACKET Unix domain socket for transport. In case of a standalone service it listens at /var/run/criu-service.socket as a transport.

The criu_req/criu_resp are two main messages for requests/responses. They are to be used for transferring messages and needed to provide compatibility with an older versions of rpc. Field type in them must be set accordingly to type of request/response that is stored. Types of request/response are defined in enum criu_req_type. See the API compliance page for information what each option might mean.

The protocol is simple: client sends a criu_req message to server, server responds back with criu_resp. In most of the cases the socket gets closed, but there are three exceptions from this rule, see below.

If no pid is set and type is DUMP, CRIU will dump client process by default.

All processes in the subtree starting with pid must have the same uid, as a client, or client's uid must be root (uid == 0), otherwise CRIU will return an error.

Only the images_dir_fd is required, all other fields are optional. Client must open directory for/with images by itself and set images_dir_fd to the opened fd. CRIU will open /proc/client_pid/fd/images_dir_fd.

The logic of setting request is the same as when setting options in console.

The field success reports result of processing request, while criu_***_resp store some request-specific information. The response type is set to the corresponding request type or to EMPTY to report a "generic" error. If success == false, one should check cr_errno field to get a more detailed error code (see include/cr-errno.h).

This message can be sent twice — one time for the process that calls DUMP, and another time for the same process again, in case it requested a self-dump. In the latter case the restored field would be true.

If the opts.notify_scripts in the request is set to TRUE, CRIU would report back resp messages with type set to NOTIFY and this field present. The notifications are the way action scripts work for RPC mode.

After handling the notification the client must response with the request again with the type set to NOTIFY and the notify_success set to the whether the notification was successful. In case of successful notification acknowledge the server doesn't close the socket and continues to work.

Before issuing a DUMP request client may send one or more PRE_DUMP requests. Once the PRE_DUMP is sent and response is received, client may send one more PRE_DUMP or DUMP request. The server would only close the socket after the DUMP one.

This mode turns on when one fork() + exec() CRIU with the swrk action and one more argument specifying the number of descriptor with SOCK_SEQPACKET Unix socket. With this CRIU works as service worker task accepting standard RPC requests via the mentioned socket and using one to do action scripts notifications and result reporting.

On a server side, CRIU creates SOCK_SEQPACKET Unix socket and listens for connections on it. After receiving criu_req, CRIU processes it, does what was requested and sends criu_resp with set request-specific criu_***_resp field back.
If CRIU gets unknown type of request, it will return criu_resp with type == EMPTY and success == false.