doc/remote_control.rst

   1
   2 Remote control
   3 ==============
   4
   5 The library has remote controlling capabilities, so external, unrelated
   6 processes can enable and disable failure points.
   7
   8 It has a very simple request/reply protocol that can be performed over
   9 different transports. At the moment, the only transport available is named
  10 pipes.
  11
  12 Remote control must be enabled by the controlled process using *fiu_rc_fifo()*
  13 (for named pipes). A set of utilities are provided to enable remote control
  14 without having to alter the application's source code, which can be useful for
  15 performing fault injection in libraries, see *fiu-run* and *fiu-ctrl* for more
  16 information.
  17
  18
  19 Remote control protocol
  20 -----------------------
  21
  22 It is a line based request/reply protocol. Lines end with a newline character
  23 (no carriage return). A request is composed of a command and 0 or more
  24 parameters, separated with a single space. The following commands are
  25 supported at the moment:
  26
  27  - ``enable <name> <failnum> <failinfo> [flags]``
  28  - ``enable_random <name> <failnum> <failinfo> <probability> [flags]``
  29  - ``disable <name>``
  30
  31 Where:
  32
  33  - *name* is the name of the point of failure (which, at the moment, cannot
  34    have spaces inside).
  35  - *failnum* the same as the *failnum* parameter of *fiu_enable()* (see the
  36    manpage for more details).
  37  - failinfo the same as the *failinfo* parameter of *fiu_enable()* (see the
  38    manpage for more details).
  39  - *flags* can be either absent or ``one``, which has the same meaning as
  40    passing ``FIU_ONETIME`` in the *flags* parameter to *fiu_enable()*.
  41
  42 The reply is always a number: 0 on success, < 0 on errors.
  43