haproxytech / spoa-mirror

Mirror HTTP requests using the HAProxy SPOP
GNU Lesser General Public License v2.1
40 stars 16 forks source link
                 -------------------------------
                     spoa-mirror for HAProxy
                 -------------------------------

Summary

  1. Introduction
  2. Build instructions
  3. Use of the program
  4. Known bugs and limitations
  1. Introduction

Replicating (mirroring) HTTP requests using the HAProxy SPOP, i.e. Stream Processing Offload Protocol.

This is a very simple program that can be used to replicate HTTP requests via the SPOP protocol. All requests are replicated to the web address (URL) selected when running the program.

The program originated from a test program located in the contrib/spoa_example directory. spoa.c is an original program that comes with HAProxy source.

The program uses the libev event library, as opposed to the original program that uses the libevent library.

  1. Build instructions

Prerequisites for configuring and compiling the program:

Creating the build subsystem (configure script):

% ./scripts/bootstrap

Configuring the program:

% ./configure

The program can be configured with debugging features enabled, but it is not recommended for actual use:

% ./configure --enable-debug

To configure the program, the system must have installed development packages for cURL and libev, which will be selected automatically when running the configure script.

Compiling the program:

% make all

After that, in the directory src will be located spoa-mirror program.

  1. Use of the program

The options supported by the program can be found using the '-h' option:

% ./src/spoa-mirror -h

--- help output ------- Usage: spoa-mirror { -h --help } spoa-mirror { -V --version } spoa-mirror { -r --runtime=TIME } [OPTION]...

Options are: -a, --address=NAME Specify the address to listen on (default: "0.0.0.0"). -B, --libev-backend=TYPE Specify the libev backend type (default: AUTO). -b, --connection-backlog=VALUE Specify the connection backlog size (default: 10). -c, --capability=NAME Enable the support of the specified capability. -D, --daemonize Run this program as a daemon. -F, --pidfile=FILE Specifies a file to write the process-id to. -h, --help Show this text. -i, --monitor-interval=TIME Set the monitor interval (default: 5.00s). -l, --logfile=[MODE:]FILE Log all messages to logfile (default: stdout/stderr). -m, --max-frame-size=VALUE Specify the maximum frame size (default: 16384 bytes). -n, --num-workers=VALUE Specify the number of workers (default: 10). -p, --port=VALUE Specify the port to listen on (default: 12345). -r, --runtime=TIME Run this program for the specified time (0 = unlimited). -t, --processing-delay=TIME Set a delay to process a message (default: 0). -u, --mirror-url=URL Specify the URL for the HTTP mirroring. -I, --mirror-interface=NAME Specify the interface/address for outgoing connections. -P, --mirror-local-port=VALUE Specify the local port range for outgoing connections. -V, --version Show program version.

Supported libev backends: select, poll, epoll, linuxaio.

Supported capabilities: fragmentation, pipelining, async.

Allowed logging file opening modes: a, w. The 'a' mode allows openning or creating file for writing at end-of-file. The 'w' mode allows truncating the file to zero length or creating a new file. If a capital letter is used for the mode, then line buffering is used when writing to the log file.

The time delay/interval is specified in milliseconds by default, but can be in any other unit if the number is suffixed by a unit (us, ms, s, m, h, d).

Copyright 2018-2020 HAProxy Technologies SPDX-License-Identifier: GPL-2.0-or-later --- help output -------

The program simultaneously supports short and long format options.

The test directory contains the configuration files for HAProxy (haproxy.cfg) and SPOE (spoe.cfg). ssl-cert.pem is a certificate intended for testing if we want to use HTTPS HAProxy frontend.

During the normal work of the program, should be placed under the comment the following lines in the spoe.cfg:

--- spoe.cfg ---------- messages check-client-ip messages test --- spoe.cfg ----------

These two rows can be used when debugging the program, especially if it is configured with the option --enable-debug .

First, the spoa-mirror program should be launched by referring to the URL to which the HTTP request will be copied. In the example below, URL is set to http://localhost:8100/ .

% ./src/spoa-mirror -r0 -u"http://localhost:8100/"

'-r' is the option that must be specified when launching a program. It is used to prevent the program from starting unnecessarily when testing the program options, or printing the program help. In addition, with this option, the program runtime is set. If the time is set to 0, the program runtime is unlimited.

After that, the HAProxy should be started (as the root user), using haproxy.cfg configuration file:

/path-to/haproxy -f haproxy.cfg

Note related to SPOE configuration: in the 'spoe-message' section (in the given example, this section is called 'mirror') the 'args' keyword must always (and only) contain the following arguments (after the sign '=' there is a permitted argument type):

arg_method=STR arg_path=STR arg_ver=STR arg_hdrs=(BIN|STR) arg_body=BIN

'arg_hdrs' can have a binary (req.hdrs_bin) or string (req.hdrs) data type argument specified. In case we want to make some changes in the HTTP headers that are sent to the mirror URL, then we will use the string data type for that argument to which we can add the regsub() converter, as in the example:

.. arg_hdrs=req.hdrs,regsub(foo,bar)

  1. Known bugs and limitations

HAProxy should be used in SSL termination mode if HTTPS is used in the HAProxy frontend part.

HTTP methods that certainly work are GET, HEAD, POST and PUT. Other methods can be added if necessary. In order for the HTTP PUT method to work properly, it is necessary to add the 'option http-buffer-request' to the HAProxy configuration, because otherwise the contents of the HTTP body will not be transferred.