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