The test-tunnel library: write tests for network tunnelling utilities
[Home | GitLab | Download | PyPI | ReadTheDocs]
Overview
The test-tunnel
library's purpose is to make it easy to write either
command-line tools or test modules that start some network tunnelling
server (e.g. stunnel, microsocks, Dante) and verify that it does indeed
forward connections and data as expected.
A tunnel test scenario
Test classes derived from the test-tunnel
library's
TestTunnel class have
a run() method that performs
the following actions:
- examines the IPv4 and IPv6 network interfaces currently configured on the running system and picks two available ports to listen on for each one
- makes a "possible connections" mapping, determining which of these addresses may be used as source and destination addresses for TCP connections. It is possible that some pairs are invalid either due to network protocol limitations or due to local system policy.
- picks a set of (server, proxy as client, proxy as server, client) address/port combinations from the above mapping so that the client may connect to the proxy and the proxy, in turn, may connect to the server
Writing a test class for a new tool
To write a new test class it is enough to create a new Python class derived from test_tunnel.run_test.TestTunnel and implement at least the three methods defined as abstract in that base class:
- slug(): return a short text string used in log messages to identify the tested program (e.g. "microsocks", "socat")
- do_spawn_server(): start the tested tool with the specified address and port to listen on and address and port to forward connections to. This method may possibly prepare a configuration file if the tool needs it, or it may start the tool and pass the addresses and ports directly on the command line if supported.
- do_handshake():
once a client socket has been connected to the already started tool
(see the do_spawn_server() method),
send and receive any "handshake" data required to make the tool establish
a connection to the test listener started by the
test-tunnel
library itself. For a SOCKS5 server this should be the protocol negotiation and authentication, for an HTTP proxy server this would be theCONNECT
request, etc.
Example tools
The test-tunnel
library contains two example command-line tools that
implement the test classes for two data forwarding programs:
the socat multipurpose relay tool and
the microsocks SOCKS5 server.
They may serve as a starting point for writing new test classes.
Contact
The test-tunnel
library was written by Peter Pentchev.
It is developed in a GitLab repository. This documentation is
hosted at Ringlet with a copy at ReadTheDocs.