1COMPEL(1)                         CRIU Manual                        COMPEL(1)
2
3
4

NAME

6       compel - Execute parasitic code within another process.
7

SYNOPSIS

9       compel hgen [option ...]
10
11       compel plugins [PLUGIN_NAME ...]
12
13       compel [--compat] includes | cflags | ldflags
14
15       compel [--compat] [--static] libs
16

DESCRIPTION

18       compel  is  a  utility  to execute arbitrary code, also called parasite
19       code, in the context of a foreign process.  The  parasitic  code,  once
20       compiled  with  compel flags and packed, can be executed in the context
21       of other tasks. Currently there is only one way to load  the  parasitic
22       blob into victim task using libcompel.a, called c-header.
23

ARGUMENTS

25   Positional Arguments
26       hgen
27           create a header from the .po file, which is the parasite binary.
28
29       plugins
30           prints the plugins available.
31
32       ldflags
33           prints  the  ldflags available to compel during linking of parasite
34           code.
35
36       cflags
37           prints the compel cflags to be used during compilation of parasitic
38           code.
39
40       includes
41           prints list of standard include directories.
42
43       libs
44           prints  list  of  static  or dynamic libraries that compel can link
45           with.
46

OPTIONS

48       -f, --file FILE
49           Path to the binary file, FILE, which compel must turn into a header
50
51       -o, --output FILE
52           Path to the header file, FILE, where compel must write the  result‐
53           ing header.
54
55       -p, --prefix NAME
56           Specify prefix for var names
57
58       -l, --log-level NUM
59           Default log level of compel.
60
61       -h, --help
62           Prints usage and exits.
63
64       -V, --version
65           Prints version number of compel.
66

SOURCE EXAMPLES

68   Parasitic Code
69       #include <compel/plugins/std.h>
70
71       int  parasite_trap_cmd(int  cmd,  void  *args);  //gets  called by com‐
72       pel_run_in_thread()
73
74       int parasite_daemon_cmd(int cmd, void *arg); //  gets  called  by  com‐
75       pel_rpc_call() and compel_rpc_call_sync()
76
77       void  parasite_cleanup(void);  //gets called on parasite unload by com‐
78       pel_cure()
79
80   Infecting code
81       The parasitic code is compiled and converted to a header using  compel,
82       and included here.
83
84       #include <compel/infect.h>
85
86       #include "parasite.h"
87
88       Following steps are perfomed to infect the victim process:
89
90       ·   stop the task: int compel_stop_task(int pid);
91
92       ·   prepare  infection handler: struct parasite_ctl *compel_prepare(int
93           pid);
94
95       ·   execute system call: int compel_syscall(ctl, int  syscall_nr,  long
96           *ret, int arg ...);
97
98       ·   infect      victim:      int      compel_infect(ctl,     nr_thread,
99           size_of_args_area);
100
101       ·   cure the victim: int compel_cure(ctl); //ctl pointer  is  freed  by
102           this call
103
104       ·   Resume victim: int compel_resume_task(pid, orig_state, state);
105
106       ctl  must  be  configured  with blob information by calling PREFIX_set‐
107       up_c_header(), with ctl as its argument. PREFIX is the  argument  given
108       to -p when calling hgen, else it is deduced from file name.
109

EXAMPLES

111       To generate a header file(.h) from a parasite binary file(.po) use:
112
113               compel hgen -f parasite.po -o parasite.h
114
115       parasite.po file is obtained by compiling the parasite source with com‐
116       pel flags and linking it with the compel plugins.
117

AUTHOR

119       The CRIU team.
120
121
122
123criu 3.15                         11/04/2020                         COMPEL(1)