dwww Home | Manual pages | Find package

COMPEL(1)                         CRIU Manual                         COMPEL(1)

NAME compel - Execute parasitic code within another process.

SYNOPSIS

       compel hgen [option ...]

       compel plugins [PLUGIN_NAME ...]

       compel [--compat] includes | cflags | ldflags

       compel [--compat] [--static] libs

DESCRIPTION

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

ARGUMENTS

   Positional Arguments

       hgen
           create a header from the .po file, which is the parasite binary.

       plugins
           prints the plugins available.

       ldflags
           prints the ldflags available to compel during  linking  of  parasite
           code.

       cflags
           prints  the compel cflags to be used during compilation of parasitic
           code.

       includes
           prints list of standard include directories.

       libs
           prints list of static or dynamic  libraries  that  compel  can  link
           with.

OPTIONS

       -f, --file FILE
           Path to the binary file, FILE, which compel must turn into a header

       -o, --output FILE
           Path to the header file, FILE, where compel must write the resulting
           header.

       -p, --prefix NAME
           Specify prefix for var names

       -l, --log-level NUM
           Default log level of compel.

       -h, --help
           Prints usage and exits.

       -V, --version
           Prints version number of compel.

SOURCE EXAMPLES

   Parasitic Code

       #include <compel/plugins/std.h>

       int  parasite_trap_cmd(int  cmd,  void  *args);  //gets  called  by com-
       pel_run_in_thread()

       int parasite_daemon_cmd(int cmd, void *arg);  //  gets  called  by  com-
       pel_rpc_call() and compel_rpc_call_sync()

       void  parasite_cleanup(void);  //gets  called on parasite unload by com-
       pel_cure()

   Infecting code

       The parasitic code is compiled and converted to a header  using  compel,
       and included here.

       #include <compel/infect.h>

       #include "parasite.h"

       Following steps are performed to infect the victim process:

       •   stop the task: int compel_stop_task(int pid);

       •   prepare  infection  handler: struct parasite_ctl *compel_prepare(int
           pid);

       •   execute system call: int compel_syscall(ctl,  int  syscall_nr,  long
           *ret, int arg ...);

       •   infect victim: int compel_infect(ctl, nr_thread, size_of_args_area);

       •   cure  the  victim:  int  compel_cure(ctl); //ctl pointer is freed by
           this call

       •   Resume victim: int compel_resume_task(pid, orig_state, state) or int
           compel_resume_task_sig(pid, orig_state, state, stop_signo).   //com-
           pel_resume_task_sig()  could  be  used  in  case  when  victim is in
           stopped  state.  stop_signo  could   be   read   by   calling   com-
           pel_parse_stop_signo().

       ctl   must   be   configured  with  blob  information  by  calling  PRE-
       FIX_setup_c_header(), with ctl as its argument. PREFIX is  the  argument
       given to -p when calling hgen, else it is deduced from file name.

EXAMPLES

       To generate a header file(.h) from a parasite binary file(.po) use:

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

       parasite.po  file is obtained by compiling the parasite source with com-
       pel flags and linking it with the compel plugins.

AUTHOR

       The CRIU team.

criu 4.1.1                         07/29/2025                         COMPEL(1)

Generated by dwww version 1.16 on Tue Nov 3 19:08:04 CET 2026.