taler-docs

Documentation for GNU Taler components, APIs and protocols
Log | Files | Refs | README | LICENSE

taler-twister.1.rst (5274B)


      1 taler-twister(1)
      2 ################
      3 
      4 .. only:: html
      5 
      6    Name
      7    ====
      8 
      9    **taler-twister** - arm the next fault injected by a taler-twister-service
     10 
     11 
     12 Synopsis
     13 ========
     14 
     15 **taler-twister**
     16 [**-a** | **--checkalive**]
     17 [**-c** *FILENAME* | **--config=**\ ‌\ *FILENAME*]
     18 [**-d** *PATH* | **--deleteobject=**\ \ *PATH*]
     19 [**-F** *PATH* | **--flip-ul=**\ \ *PATH*]
     20 [**-f** *PATH* | **--flip-dl=**\ \ *PATH*]
     21 [**-H** *HEADER* | **--modify-header-dl=**\ \ *HEADER*]
     22 [**-h** | **--help**]
     23 [**-L** *LOGLEVEL* | **--log=**\ \ *LOGLEVEL*]
     24 [**-l** *FILENAME* | **--logfile=**\ \ *FILENAME*]
     25 [**-M** | **--malform**]
     26 [**-m** *PATH* | **--modify-dl=**\ \ *PATH*]
     27 [**-r** *STATUS* | **--responsecode=**\ \ *STATUS*]
     28 [**-U** | **--malformupload**]
     29 [**-V** *VALUE* | **--value=**\ \ *VALUE*]
     30 [**-v** | **--version**]
     31 [**-X** *PATH* | **--modify-ul=**\ \ *PATH*]
     32 
     33 
     34 Description
     35 ===========
     36 
     37 **taler-twister** is a command-line tool to arm the next fault injected by
     38 a running **taler-twister-service**, the fault-injecting HTTP proxy used
     39 by the GNU Taler test suites.
     40 
     41 Each invocation connects to a running service over its GNUnet IPC socket,
     42 queues the mutations named by the options given, waits for the service to
     43 acknowledge them and exits.  A queued mutation applies to the *next*
     44 request or response the proxy forwards, and is consumed by it; a test
     45 script therefore invokes **taler-twister** once before every HTTP request
     46 whose handling it wants to break.  Several options may be combined in one
     47 invocation, each queueing its own mutation.
     48 
     49 The service to talk to is selected by the configuration file: pass the
     50 *same* **-c** option that the service was started with, so that both agree
     51 on the control socket.
     52 
     53 Mutations are either *download* scoped, altering the response travelling
     54 from the upstream service back to the client, or *upload* scoped, altering
     55 the request travelling from the client to the upstream service.
     56 
     57 Options taking a *PATH* address a position inside a JSON body in
     58 object-dotted notation: field names and array indices are separated by
     59 dots, so ``f1.f2.0`` denotes the string ``x`` in ``{"f1":{"f2":["x"]}}``.
     60 Any such mutation forces the affected body to be buffered in full and
     61 re-serialized; bodies sent with ``Content-Encoding: deflate`` are
     62 transparently inflated first, so that paths resolve against the
     63 decompressed JSON.
     64 
     65 Its options are as follows:
     66 
     67 **-a** \| **--checkalive**
     68    Do not queue any mutation, only check that the service accepts IPC
     69    connections.  Exits with status 0 if the connection succeeded.  This is
     70    what test harnesses use to wait for a freshly launched service.
     71 
     72 **-c** *FILENAME* \| **--config=**\ ‌\ *FILENAME*
     73    Use the configuration and other resources for the twister
     74    to operate from *FILENAME*.
     75 
     76 **-d** *PATH* \| **--deleteobject=**\ \ *PATH*
     77    Delete the JSON object at *PATH* from the next response.
     78 
     79 **-F** *PATH* \| **--flip-ul=**\ \ *PATH*
     80    Flip a random character of the *string* at *PATH* in the next request.
     81    The field must be a JSON string.
     82 
     83 **-f** *PATH* \| **--flip-dl=**\ \ *PATH*
     84    Flip a random character of the *string* at *PATH* in the next response.
     85    The field must be a JSON string.
     86 
     87 **-H** *HEADER* \| **--modify-header-dl=**\ \ *HEADER*
     88    Replace the value of the HTTP response header *HEADER* in the next
     89    response.  Requires **--value**.
     90 
     91 **-h** \| **--help**
     92    Print short help on options.
     93 
     94 **-L** *LOGLEVEL* \| **--log=**\ \ *LOGLEVEL*
     95    Configure logging to use *LOGLEVEL*.
     96 
     97 **-l** *FILENAME* \| **--logfile=**\ \ *FILENAME*
     98    Configure logging to write logs to *FILENAME*.
     99 
    100 **-M** \| **--malform**
    101    Truncate the next response at a random position.
    102 
    103 **-m** *PATH* \| **--modify-dl=**\ \ *PATH*
    104    Set the JSON value at *PATH* in the next response.  Requires
    105    **--value**.
    106 
    107 **-r** *STATUS* \| **--responsecode=**\ \ *STATUS*
    108    Replace the HTTP status code of the next response with *STATUS*.
    109 
    110 **-U** \| **--malformupload**
    111    Truncate the next request at a random position.
    112 
    113 **-V** *VALUE* \| **--value=**\ \ *VALUE*
    114    The new value for **--modify-dl**, **--modify-ul** or
    115    **--modify-header-dl**.  Note that *VALUE* is always set as a JSON
    116    string, except for the literals ``true`` and ``false``; numbers cannot
    117    be injected as JSON numbers in this version.
    118 
    119 **-v** \| **–version**
    120    Print version information.
    121 
    122 **-X** *PATH* \| **--modify-ul=**\ \ *PATH*
    123    Set the JSON value at *PATH* in the next request.  Requires
    124    **--value**.
    125 
    126 
    127 Exit Status
    128 ===========
    129 
    130 0 if every queued mutation was acknowledged (or, with **--checkalive**, if
    131 the service could be reached), 3 if the command line could not be parsed,
    132 and 1 otherwise, in particular if the service is not running or rejected a
    133 mutation.
    134 
    135 
    136 Examples
    137 ========
    138 
    139 Make the next proxied response come back as HTTP 500:
    140 
    141 .. code-block:: console
    142 
    143    $ taler-twister -c twister.conf -r 500
    144 
    145 Remove the ``signature`` field from the ``deposit`` object of the next
    146 response, and corrupt one character of the next uploaded ``coin_pub``
    147 field:
    148 
    149 .. code-block:: console
    150 
    151    $ taler-twister -c twister.conf -d deposit.signature -F coin_pub
    152 
    153 
    154 See Also
    155 ========
    156 
    157 taler-twister-service(1), taler-unified-setup(1).
    158 
    159 
    160 Bugs
    161 ====
    162 
    163 Report bugs by using https://bugs.taler.net or by sending electronic
    164 mail to <taler@gnu.org>.