Changes

'''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/xemul/criu/tree/criu-dev/compel the criu-dev branch of CRIU repo, subdirectory 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].

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.

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.

</pre>

</pre>

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

 

Then link the parasite binary. Include all the .o files needed and compel std plugin by using compel linker script.

<pre>

<pre>

$ ld foo1.o foo2.o compel/plugins/std.built-in.o -T compel/arch/$ARCH/scripts/compel-pack.lds.S -o parasite.po  

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

</pre>

</pre>

=== Using libcompel.a library ===

=== 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 you .po file with the <code>hgen</code> action of compel tool:

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 -v parasite_relocs -p parasite_sym -s parasite_blob -r parasite_nr_gotpcrel -u compel/include/uapi/ -o parasite.h

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

Here the <code>-f</code> option tells which binary to turn into header, and <code>-o</code> option tells where to put the resulting header. The rest of the arguments are used to fill in the blob descriptor, see the [[#Infecting]] section below for details.

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.

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

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

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

First, the <code>ctl</code> should be configured with the blob information. Currently there is only one type of blobs, generated by <code>compel hgen</code>. To put this info into ctl, one should call <code>compel_parasite_blob_desc(ctl)</code> to get a pointer on <code>struct parasite_blob_desc</code> and fill in the fields of this strucure:

First, the <code>ctl</code> should be configured with the blob information. For that,

 

you should call <code>''PREFIX''_setup_c_header()</code> function

* <code>.parasite_type</code> should be set to <code>COMPEL_BLOB_CHEADER</code>

with <code>ctl</code> as an argument. Here <code>''PREFIX''</code>

* <code>.hdr.mem</code> should be set to the <code>parasite_blob</code> of hgen

is the same as the argument given to <code>-p</code> option

* <code>.hdr.bsize</code> should be set to the sizeof(this symbol)

to <code>compel hgen</code>, and if not given, it is derived

* <code>.hdr.nr_gotpcrel</code> should be set to the <code>parasite_nr_gotpcrel</code> of hgen

(in the above example it's <code>parasite</code>).

** <code>.hdr.parasite_ip_off</code> to <code>COMPEL_H_PARASITE_HEAD(parasite_sym)</code>

** <code>.hdr.addr_cmd_off</code>  to <code>COMPEL_H_PARASITE_CMD(parasite_sym)</code>

* <code>.hdr.relocs</code> should be set to <code>parasite_relocs</code> argument (it's an array)

* <code>.hdr.nr_relocs</code> should be set to a number of elements in this array (<code>sizeof(arr)/sizeof(arr[0])</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.

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.

* [[Compel/Usage_scenarios]]

* [[Compel/Usage_scenarios]]

* [[Compel plugins]]

* [[Compel plugins]]

* Examples of working code available [https://github.com/xemul/criu/tree/criu-dev/compel/test on github].

* 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>

 

[[Category:Compel]]

[[Category:Compel]]