85
edits
Changes
Jump to navigation
Jump to search
Created page with "'''libcriu''' is a C API for CRIU, which is a simple wrapper around our RPC. Although you can use RPC directly, libcriu provides the interface that is much easier to u..."
'''libcriu''' is a C API for CRIU, which is a simple wrapper around our [[RPC]]. Although you can use [[RPC]] directly, libcriu provides the interface that is much easier to use in C apps. Note that [[RPC]] is supported in the first place, and if you want the most recent set of options you should probably use [[RPC]].
== Beginning ==
You could find libcriu header at lib/criu.h.
To create lib/libcriu.so run make in the main directory.
== Setup options ==
=== init options ===
Call '''int criu_init_opts(void)''' to init request options. Note: it should be called before using any other functions from libcriu except criu_check(). Also you should use it to reinit options. It return 0 on success and -1 on fail.
=== set service address ===
Use '''void criu_set_service_address(char *address)''' to specify path to CRIU service socket. Call it with NULL to make libcriu use default address: /var/run/criu_service.socket.
=== set dump/restore options ===
Use criu_set_* functions to setup dump/restore options.
<pre>
void criu_set_pid(int pid);
void criu_set_images_dir_fd(int fd); /* must be set for dump/restore */
void criu_set_leave_running(bool leave_running);
void criu_set_ext_unix_sk(bool ext_unix_sk);
void criu_set_tcp_established(bool tcp_established);
void criu_set_evasive_devices(bool evasive_devices);
void criu_set_shell_job(bool shell_job);
void criu_set_file_locks(bool file_locks);
void criu_set_log_level(int log_level);
void criu_set_log_file(char *log_file);
</pre>
If no pid is set on 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. See [[Usage#Security]].
Only images_dir_fd is required at dump/restore, all other options 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:
<pre>#criu restore -D /path/to/imgs_dir -v4 -o restore.log</pre>
is equal to:
<pre>
criu_init_opts();
criu_set_service_address("/path/to/criu/service/socket");
int fd = open("/path/to/imgs_dir", O_DIRECTORY);
criu_set_images_dir_fd(fd);
criu_set_log_file("restore.log");
criu_set_log_level(4);
criu_restore();
</pre>
== check/dump/restore ==
Use this functions to check/dump/restore:
<pre>
int criu_check(void);
int criu_dump(void);
int criu_restore(void);
</pre>
Here is a table of return values and errno's of this functions:
{| class="wikitable"
|-
! Return value
! errno
! Description
|-
| 0
| undefined
| Success
|-
| >0
| undefined
| Success(criu_restore() only)
|-
| -EBADE
| RPC error(if provided, for now undefined)
| RPC has returned fail.
|-
| -ECONNREFUSED
| errno
| Unable to connect to CRIU.
|-
| -ECOMM
| errno
| Unable to send/recv msg to/from CRIU.
|-
| -EINVAL
| undefined
| CRIU doesn't support this type of request. You should probably update CRIU.
|-
| -EBADMSG
| undefined
| Unexpected response from CRIU. You should probably update CRIU.
|}
== Beginning ==
You could find libcriu header at lib/criu.h.
To create lib/libcriu.so run make in the main directory.
== Setup options ==
=== init options ===
Call '''int criu_init_opts(void)''' to init request options. Note: it should be called before using any other functions from libcriu except criu_check(). Also you should use it to reinit options. It return 0 on success and -1 on fail.
=== set service address ===
Use '''void criu_set_service_address(char *address)''' to specify path to CRIU service socket. Call it with NULL to make libcriu use default address: /var/run/criu_service.socket.
=== set dump/restore options ===
Use criu_set_* functions to setup dump/restore options.
<pre>
void criu_set_pid(int pid);
void criu_set_images_dir_fd(int fd); /* must be set for dump/restore */
void criu_set_leave_running(bool leave_running);
void criu_set_ext_unix_sk(bool ext_unix_sk);
void criu_set_tcp_established(bool tcp_established);
void criu_set_evasive_devices(bool evasive_devices);
void criu_set_shell_job(bool shell_job);
void criu_set_file_locks(bool file_locks);
void criu_set_log_level(int log_level);
void criu_set_log_file(char *log_file);
</pre>
If no pid is set on 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. See [[Usage#Security]].
Only images_dir_fd is required at dump/restore, all other options 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:
<pre>#criu restore -D /path/to/imgs_dir -v4 -o restore.log</pre>
is equal to:
<pre>
criu_init_opts();
criu_set_service_address("/path/to/criu/service/socket");
int fd = open("/path/to/imgs_dir", O_DIRECTORY);
criu_set_images_dir_fd(fd);
criu_set_log_file("restore.log");
criu_set_log_level(4);
criu_restore();
</pre>
== check/dump/restore ==
Use this functions to check/dump/restore:
<pre>
int criu_check(void);
int criu_dump(void);
int criu_restore(void);
</pre>
Here is a table of return values and errno's of this functions:
{| class="wikitable"
|-
! Return value
! errno
! Description
|-
| 0
| undefined
| Success
|-
| >0
| undefined
| Success(criu_restore() only)
|-
| -EBADE
| RPC error(if provided, for now undefined)
| RPC has returned fail.
|-
| -ECONNREFUSED
| errno
| Unable to connect to CRIU.
|-
| -ECOMM
| errno
| Unable to send/recv msg to/from CRIU.
|-
| -EINVAL
| undefined
| CRIU doesn't support this type of request. You should probably update CRIU.
|-
| -EBADMSG
| undefined
| Unexpected response from CRIU. You should probably update CRIU.
|}