1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
|
<!--
SPDX-FileCopyrightText: Peter Pentchev <roam@ringlet.net>
SPDX-License-Identifier: BSD-2-Clause
-->
# The test-tunnel library: write tests for network tunnelling utilities
\[[Home][ringlet-home] | [GitLab][gitlab] | [Download](download.md) | [PyPI][pypi] | [ReadTheDocs][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][test_tunnel.run_test.TestTunnel] class have
a [run()][test_tunnel.run_test.TestTunnel.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()][test_tunnel.run_test.TestTunnel.slug]: return a short text string
used in log messages to identify the tested program (e.g. "microsocks", "socat")
- [do_spawn_server()][test_tunnel.run_test.TestTunnel.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()][test_tunnel.run_test.TestTunnel.do_handshake]:
once a client socket has been connected to the already started tool
(see the [do_spawn_server()][test_tunnel.run_test.TestTunnel.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 the `CONNECT`
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][test_tunnel.cmd_test.socat] multipurpose relay tool and
the [microsocks][test_tunnel.cmd_test.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][roam].
It is developed in [a GitLab repository][gitlab]. This documentation is
hosted at [Ringlet][ringlet-home] with a copy at [ReadTheDocs][readthedocs].
[roam]: mailto:roam@ringlet.net "Peter Pentchev"
[gitlab]: https://gitlab.com/ppentchev/test-tunnel "The test-tunnel GitLab repository"
[pypi]: https://pypi.org/project/test-tunnel/ "The test-tunnel Python Package Index page"
[readthedocs]: https://test-tunnel.readthedocs.io/ "The test-tunnel ReadTheDocs page"
[ringlet-home]: https://devel.ringlet.net/net/test-tunnel/ "The Ringlet test-tunnel homepage"
|
