Difference between revisions of "RPC"

From CRIU
Jump to navigation Jump to search
(extended description)
(Fixed options description)
Line 93: Line 93:
 
To launch service server run:
 
To launch service server run:
  
<pre>#criu service --address <socket_address></pre>
+
<pre>#criu service [options]</pre>
  
Note that you can set suid flag on criu and run it as non-root user, but it will be able to serve only tasks with the same user's uid.
+
Options accepted by service are
  
If no address is set, "/tmp/criu_service.socket" is used by default.
+
; --address <path>
You may also like to demonize server(-d), set log level(-v<N>) or set log file(-o <logname>). Server log file wouldn't be very informative for now, though.
+
: is where to put listening socket
For the full list of options, please run "criu -h".
+
 
 +
; --pid-file <path>
 +
: is where to write pid of service process
 +
 
 +
; --daemon
 +
: tells service to daemonize
 +
 
 +
; -o <file>
 +
: says where to write logs
 +
 
 +
; -v[N]
 +
: sets the log-level
  
 
=== Client ===
 
=== Client ===

Revision as of 08:22, 15 October 2013

CRIU-RPC is a remote procedure call (RPC) protocol which uses Google Protocol Buffers to encode its calls. The requests are served by CRIU service launched with criu service command. It uses a SEQPACKET Unix domain socket listening at /var/run/criu-srvice.socket as transport.

Protobuf messages

criu_req/criu_resp -- wrappers 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.

Request

criu_req

message criu_req {
	required criu_req_type type	= 1;

	optional criu_opts opts		= 2;
}

criu_req_type

There are only 2 request/response types for now.

enum criu_req_type {
	EMPTY		= 0;
	DUMP		= 1;
	RESTORE		= 2;
}

criu_opts

It is used to store options.

message criu_opts {
	required int32 images_dir_fd	= 1;
	optional int32 pid		= 2;

	optional bool leave_running	= 3;
	optional bool ext_unix_sk	= 4;
	optional bool tcp_established	= 5;
	optional bool evasive_devices	= 6;
	optional bool shell_job		= 7;
	optional bool file_locks	= 8;
	optional int32 log_level	= 9 [default = 2];
	optional string log_file	= 10;
}

If no pid is set and type is DUMP, CRIU will dump client process by default. Note: Whole tree <pid> must have the same uid, as a client, or client's uid must be == 0, otherwise CRIU won't dump nothing at all.

Only images_dir_fd is required, all other fields may not be set. Client must open directory for/with images by himself and set images_dir_fd to it's fd. CRIU will open /proc/<client's_pid>/fd/<images_dir_fd>, so it will work, if client is in another namespace.

The logic of setting request is the same as when setting options in console. Here is an example:

#criu restore -D /path/to/imgs_dir -v4 -o restore.log

is equal to:

request.type = RESTORE;

request.opts.imgs_dir_fd	= open("/path/to/imgs_dir")
request.opts.log_level		= 4
request.opts.log_file		= "restore.log"

Response

criu_resp

message criu_resp {
	required criu_req_type type	= 1;
	required bool success		= 2;

	optional criu_dump_resp	dump	= 3;
	optional criu_restore_resp restore = 4;
}

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.

criu_dump_resp

criu_dump_resp is used to store dump response from CRIU.

message criu_dump_resp {
	optional bool restored		= 1;
}

Field "restored" is set to "true" if process was restored.

criu_restore_resp

message criu_restore_resp {
	required int32 pid		= 1;
}

Field "pid" is set to the PID of the restored process.

Run

Server

On a server side, CRIU creates SOCK_SEQPACKET Unix socket and listens for connections on it. After receiving criu_req, CRIU processes it, do what is 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.

To launch service server run:

#criu service [options]

Options accepted by service are

--address <path>
is where to put listening socket
--pid-file <path>
is where to write pid of service process
--daemon
tells service to daemonize
-o <file>
says where to write logs
-v[N]
sets the log-level

Client

Client, in its turn, must connect to service socket, send criu_req with request in it, and wait for a criu_resp with response. You can find examples of client programs in C and Python in test/rpc/.

With RPC facilities one can perform a self dump.