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

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()

parasite_cleanup(void);

This gets called on parasite unload by compel_cure()

Compiling and packing

Compile the source of your parasite code with compel flags:

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

If the code consists of more than one source file, they all need to be compiled, then linked together with the proper linker flags for compel:

$ ld foo1.o foo2.o -o foo.o $(compel ldflags)

Finally, pack the binary. Packing links the object file with compel plugins.

$ compel pack foo.o -o foo.compel.o [-l ''plugin'' [...]]

The -l option specifies plugins to be added to the packed binary. The std plugin is added by default, i.e. it does not require any flags.

Now, the foo.compel.o is ready for remote execution (note that foo.o was not).

Running

Using CLI, the compiled and packed parasite code can be executed like this:

$ compel run -f foo.compel.o -p ''pid'' [args ...]

Alternatively, you can link it with the libcompel.so and use the following calls:

libcompel_exec();
libcompel_exec_start();
libcompel_exec_end();

These library calls require binary argument that is copied into the parasite context and is available from it via arg_p/arg_s pair. When run from CLI, the arguments are packed in the usual way (argc/argv).

Communicating

There are several ways to pass parameters to the parasite code.

If you run the parasite binary from CLI, the command line arguments after -- are passed into the parasite's main() function.

$ compel run -f foo.compel.o -p 123 -- arg1 arg2 arg3

In main(), the standard argc and argv can be obtained using the following code:

argc = std_argc(arg_p);
argv = std_argv(arg_p, argc);

These calls are available in argv plugin. Now, argc and argv can be handled as usual.

See also

• Compel/Usage_scenarios
• Compel plugins