taler-twister-service.1.rst (4119B)
1 taler-twister-service(1) 2 ######################## 3 4 .. only:: html 5 6 Name 7 ==== 8 9 **taler-twister-service** - fault-injecting HTTP proxy for GNU Taler tests 10 11 12 Synopsis 13 ======== 14 15 **taler-twister-service** 16 [**-c** *FILENAME* | **--config=**\ \ *FILENAME*] 17 [**-h** | **--help**] 18 [**-L** *LOGLEVEL* | **--log=**\ \ *LOGLEVEL*] 19 [**-l** *FILENAME* | **--logfile=**\ \ *FILENAME*] 20 [**-v** | **--version**] 21 22 23 Description 24 =========== 25 26 **taler-twister-service** is an HTTP proxy that sits between a REST client 27 and the service under test. By default it forwards traffic transparently; 28 on command it mutates individual requests or responses, so that test code 29 can exercise the error handling paths that a correct peer never triggers. 30 It is used by the test suites of the GNU Taler exchange, merchant and bank 31 components. 32 33 The proxy accepts requests on ``HTTP_PORT`` (or on a UNIX domain socket), 34 replays each of them against ``DESTINATION_BASE_URL``, and streams the 35 response back. Request and response bodies are pumped through libcurl 36 pause/resume callbacks, so large bodies are not buffered — except where a 37 mutation needs the whole body, which JSON mutations do. 38 39 Alongside the proxy, the process runs a GNUnet IPC control socket. Each 40 control message queues *one* mutation, which is applied to the next request 41 or response forwarded and then consumed. Mutations are normally queued 42 with **taler-twister**; C test harnesses can queue them directly through 43 **libtalertwister**. 44 45 The service does not usually need to be started by hand: GNUnet's ARM can 46 start it, and the Taler test harnesses launch it themselves. Note that it 47 is a *testing* tool — it offers no authentication on its proxy face, 48 happily corrupts the traffic it carries, and must not be exposed to an 49 untrusted network or placed in front of a production service. 50 51 Its options are as follows: 52 53 **-c** *FILENAME* \| **--config=**\ \ *FILENAME* 54 Use the configuration and other resources for the twister 55 to operate from *FILENAME*. The same file must be passed to 56 **taler-twister** so that it reaches the right control socket. 57 58 **-h** \| **--help** 59 Print short help on options. 60 61 **-L** *LOGLEVEL* \| **--log=**\ \ *LOGLEVEL* 62 Configure logging to use *LOGLEVEL*. 63 64 **-l** *FILENAME* \| **--logfile=**\ \ *FILENAME* 65 Configure logging to write logs to *FILENAME*. 66 67 **-v** \| **–version** 68 Print version information. 69 70 71 Configuration 72 ============= 73 74 All options are read from the “[twister]” section of the GNUnet 75 configuration file given with **-c**; without that option, the service 76 reads ``~/.config/twister.conf``. 77 78 SERVE 79 Should the proxy face listen on a UNIX domain socket (set option to 80 ``unix``) or on a TCP socket (set option to ``tcp``)? Mandatory. 81 82 HTTP_PORT 83 Port on which the proxy face listens, e.g. ``8888``. 84 Mandatory if ``SERVE`` is ``tcp``. 85 86 SERVE_UNIXPATH 87 Which unix domain path should the proxy face bind to? 88 Mandatory if ``SERVE`` is ``unix``. 89 90 SERVE_UNIXMODE 91 What should be the file access permissions, as an octal number, for 92 ``SERVE_UNIXPATH``? Mandatory if ``SERVE`` is ``unix``. 93 94 DESTINATION_BASE_URL 95 Base URL of the upstream service requests are forwarded to. Mandatory, 96 and must *not* end with a slash. 97 98 CHAOS_RATE 99 Percentage, between 0 and 100, of responses to be replaced by an HTTP 503 100 “Service unavailable” regardless of any queued mutation. Defaults to 101 ``0``, that is, no chaos. Unlike the queued mutations, this is a 102 standing setting, read once at startup. 103 104 PORT, HOSTNAME, UNIXPATH 105 Standard GNUnet service options describing where the *control* face 106 listens: a TCP port and bind address, a UNIX domain socket path, or both. 107 108 A minimal configuration putting the proxy on port 8888 in front of a 109 service on port 8080: 110 111 .. code-block:: ini 112 113 [twister] 114 SERVE = tcp 115 HTTP_PORT = 8888 116 DESTINATION_BASE_URL = http://localhost:8080 117 UNIXPATH = /tmp/taler-service-twister.sock 118 119 120 See Also 121 ======== 122 123 taler-twister(1), taler-unified-setup(1). 124 125 126 Bugs 127 ==== 128 129 Report bugs by using https://bugs.taler.net or by sending electronic 130 mail to <taler@gnu.org>.