Difference between revisions of "Compel"

From CRIU
Jump to navigation Jump to search
 
(60 intermediate revisions by 3 users not shown)
Line 1: Line 1:
[http://github.com/xemul/compel]
+
'''Compel''' is a utility to execute arbitrary code in a context of a foreign process. Compel is part of CRIU, and its sources are available from [https://github.com/checkpoint-restore/criu/tree/criu-dev/compel the criu-dev branch of CRIU repo, subdirectory compel].
  
== Usage ideas ==
+
The code to be executed is called '''parasite code'''. Once compiled with compel flags and packed, it can be executed in other task's context. Note the code is run in environment without glibc, thus it can not call the usual stdio/stdlib/etc. functions.
  
One thing parasite code can do is call clone() and create thread having access to main process VM, FDT, FS, etc. The new thread can then
+
A set of [[compel plugins]] are provided for your convenience. Plugins get linked to the parasite binary during the pack stage.
  
* Check socket FDs to get stuck/closed by polling them
+
== Writing parasite code ==
* Apply "logrotate" on the fly
 
  
Another is to do some activity on the victim and then just unload. With this we can
+
Execution of parasite code always starts with a function in compel std plugin that should be linked with parasite binary (see below). From the parasite code these symbols should be available for libcompel to work
  
* Death detection. Open pipe/socket and pass the other end outside. Once the victim dies the pipe/socket will wake up.
+
; <code>parasite_trap_cmd(int cmd, void *arg);</code>
* Binary updates. E.g. live patching or libr relink
+
: This routine gets called by <code>compel_run_in_thread()</code>
* Inject socket spy -- instead of opened socket create a unix one, put it in place of original one and send the latter back to caller so that any traffic flow in one goes "through" the spy
 
* Do "nohup" on the fly
 
* Debug stuff by MSG_PEEK-ing sockets messages of tee+splice sockets
 
* Re-connect sleeping sockets to other addresses (not 100% safe)
 
* "Soft" restart of a service -- call execve() from it's context
 
* Force entering into CT (except pid namespace, probably)
 
  
[[Category:Empty articles]]
+
; <code>parasite_daemon_cmd(int cmd, void *arg);</code>
[[Category:Sub-projects]]
+
: This routine gets called by <code>compel_rpc_call()</code> and <code>compel_rpc_call_sync()</code>. The <code>arg</code> points to the memory with arguments, see the [[#Arguments passing]] section below.
 +
 
 +
; <code>parasite_cleanup(void);</code>
 +
: This gets called on parasite unload by <code>compel_cure()</code>
 +
 
 +
== Compiling and packing ==
 +
 
 +
Compile the source of your parasite code with compel flags:
 +
 
 +
<pre>
 +
$ gcc -c foo1.c -o foo1.o $(compel cflags)
 +
</pre>
 +
 
 +
Then link the parasite binary. Include all the .o files needed.
 +
 
 +
<pre>
 +
$ ld $(compel ldflags) foo1.o foo2.o $(compel plugins) -o parasite.po
 +
</pre>
 +
 
 +
The .po blob can now be loaded as parasite.
 +
 
 +
== Loading blob ==
 +
 
 +
=== Using CLI ===
 +
 
 +
This functionality is in plans and not implemented yet.
 +
 
 +
=== Using libcompel.a library ===
 +
 
 +
Currently there is only one way to load the blob into victim task using libcompel.a, called ''c-header'' <ref>This is done for historical reasons. It was the most handy way to load [[parasite code]] by CRIU. In plans we have loading the .po ELF file itself</ref>. First you should make a header out of your .po file with the <code>hgen</code> action of compel tool:
 +
 
 +
compel hgen -f parasite.po -o parasite.h
 +
 
 +
Options meaning is the following:
 +
* <code>-f</code> tells which binary to turn into header
 +
* <code>-o</code> tells where to write the resulting header
 +
 
 +
Once <code>parasite.h</code> file is ready, it should be included into the infecting program source code to be compiled with it.
 +
 
 +
== Running parasite code ==
 +
 
 +
So, in order to infect a task with parasite one must do the following.
 +
 
 +
* Stop the task. This is done by calling <code>compel_stop_task(int pid)</code>. Its return value should be saved in case it's positive (it contains the task state).
 +
* Prepare the infection handler. This is done by calling <code>compel_prepare(int pid)</code>. The return value is an opaque pointer to <code>struct parasite_ctl</code>.
 +
* Run the remote code:
 +
** Execute a system call with <code>compel_syscall(ctl, int syscall_nr, long *ret, int arg ...)</code> (all 6 parameters)
 +
** Infect the victim with the parasite blob by calling <code>compel_infect(ctl, nr_thread, size_of_args_area)</code>
 +
* Cure the victim by calling <code>compel_cure(ctl)</code>. Note that <code>ctl</code> pointer is freed by the call so it should not be used thereafter.
 +
* Resume the task by calling <code>compel_resume_task(pid, orig_state, state)</code> with the saved state value from the first step.
 +
 
 +
=== Infecting ===
 +
 
 +
Infecting the victim with a parasite blob needs some special treatment.
 +
 
 +
First, the <code>ctl</code> should be configured with the blob information. For that,
 +
you should call <code>''PREFIX''_setup_c_header()</code> function
 +
with <code>ctl</code> as an argument. Here <code>''PREFIX''</code>
 +
is the same as the argument given to <code>-p</code> option
 +
to <code>compel hgen</code>, and if not given, it is derived
 +
from the input file name, dropping the path and the suffix
 +
(in the above example it's <code>parasite</code>).
 +
 
 +
Second, when infecting a parasite one should specify the amount of threads it will mess with (1, if only the thread leader will be accessed) and the maximum size of the memory area shared between infecting task and parasite used for arguments/result passing.
 +
 
 +
=== Arguments passing ===
 +
 
 +
To pass arguments between the infecting code and parasite, one may call <code>compel_parasite_args(ctl, type)</code> and get the pointer where it can put data. Subsequent calls to <code>compel_rpc_call[_sync]()</code> will result in this data visible in <code>void *arg</code> address of the <code>parasite_daemon_cmd()</code>.
 +
 
 +
== See also ==
 +
* [[Compel/Usage_scenarios]]
 +
* [[Compel plugins]]
 +
* Examples of working code available [https://github.com/checkpoint-restore/criu/tree/criu-dev/compel/test on github] <ref>Clone the repo, build the project by running <code>make</code>, then go to <code>compel/test/$test_name</code> directory and run <code>make</code> there. Running <code>spy</code> bynary runs the example. Then -- RTFS or talk to us on [https://lists.openvz.org/mailman/listinfo/criu criu@openvz.org] :)</ref>
 +
* Info about CRIU [[code blobs]] in which the same technology is used
 +
 
 +
 
 +
-----
 +
<references/>
 +
[[Category:Compel]]
 +
[[Category:Editor help needed]]

Latest revision as of 14:43, 29 August 2018

Compel is a utility to execute arbitrary code in a context of a foreign process. Compel is part of CRIU, and its sources are available from the criu-dev branch of CRIU repo, subdirectory compel.

The code to be executed is called parasite code. Once compiled with compel flags and packed, it can be executed in other task's context. Note the code is run in environment without glibc, thus it can not call the usual stdio/stdlib/etc. functions.

A set of compel plugins are provided for your convenience. Plugins get linked to the parasite binary during the pack stage.

Writing parasite code[edit]

Execution of parasite code always starts with a function in compel std plugin that should be linked with parasite binary (see below). From the parasite code these symbols should be available for libcompel to work

parasite_trap_cmd(int cmd, void *arg);
This routine gets called by compel_run_in_thread()
parasite_daemon_cmd(int cmd, void *arg);
This routine gets called by compel_rpc_call() and compel_rpc_call_sync(). The arg points to the memory with arguments, see the #Arguments passing section below.
parasite_cleanup(void);
This gets called on parasite unload by compel_cure()

Compiling and packing[edit]

Compile the source of your parasite code with compel flags:

$ gcc -c foo1.c -o foo1.o $(compel cflags)

Then link the parasite binary. Include all the .o files needed.

$ ld $(compel ldflags) foo1.o foo2.o $(compel plugins) -o parasite.po 

The .po blob can now be loaded as parasite.

Loading blob[edit]

Using CLI[edit]

This functionality is in plans and not implemented yet.

Using libcompel.a library[edit]

Currently there is only one way to load the blob into victim task using libcompel.a, called c-header [1]. First you should make a header out of your .po file with the hgen action of compel tool:

compel hgen -f parasite.po -o parasite.h

Options meaning is the following:

  • -f tells which binary to turn into header
  • -o tells where to write the resulting header

Once parasite.h file is ready, it should be included into the infecting program source code to be compiled with it.

Running parasite code[edit]

So, in order to infect a task with parasite one must do the following.

  • Stop the task. This is done by calling compel_stop_task(int pid). Its return value should be saved in case it's positive (it contains the task state).
  • Prepare the infection handler. This is done by calling compel_prepare(int pid). The return value is an opaque pointer to struct parasite_ctl.
  • Run the remote code:
    • Execute a system call with compel_syscall(ctl, int syscall_nr, long *ret, int arg ...) (all 6 parameters)
    • Infect the victim with the parasite blob by calling compel_infect(ctl, nr_thread, size_of_args_area)
  • Cure the victim by calling compel_cure(ctl). Note that ctl pointer is freed by the call so it should not be used thereafter.
  • Resume the task by calling compel_resume_task(pid, orig_state, state) with the saved state value from the first step.

Infecting[edit]

Infecting the victim with a parasite blob needs some special treatment.

First, the ctl should be configured with the blob information. For that, you should call PREFIX_setup_c_header() function with ctl as an argument. Here PREFIX is the same as the argument given to -p option to compel hgen, and if not given, it is derived from the input file name, dropping the path and the suffix (in the above example it's parasite).

Second, when infecting a parasite one should specify the amount of threads it will mess with (1, if only the thread leader will be accessed) and the maximum size of the memory area shared between infecting task and parasite used for arguments/result passing.

Arguments passing[edit]

To pass arguments between the infecting code and parasite, one may call compel_parasite_args(ctl, type) and get the pointer where it can put data. Subsequent calls to compel_rpc_call[_sync]() will result in this data visible in void *arg address of the parasite_daemon_cmd().

See also[edit]



  1. This is done for historical reasons. It was the most handy way to load parasite code by CRIU. In plans we have loading the .po ELF file itself
  2. Clone the repo, build the project by running make, then go to compel/test/$test_name directory and run make there. Running spy bynary runs the example. Then -- RTFS or talk to us on criu@openvz.org :)