source: mod_gnutls/test/README @ dc55c77

Last change on this file since dc55c77 was b21bf4f, checked in by Thomas Klute <thomas2.klute@…>, 5 years ago

configure: Check if creating namespaces is possible

Some Linux distributions (I've observed this on Debian) restrict
unprivileged users' ability to create namespaces, so checking just
whether the "unshare" command is available is not enough: If it is but
the user building mod_gnutls does not have the necessary permissions,
test cases will fail when trying to create their namespaces. Add a
check that tries to actually create a namespace and disable namespace
isolation of tests if it fails.

  • Property mode set to 100644
File size: 5.4 KB
[4b53371]1Unit Tests for Apache's mod_gnutls
[26081ce]4Authors: Daniel Kahn Gillmor <>
5         Thomas Klute <>
7There are a lot of ways that a TLS-capable web server can go wrong.  I
8want to at least test for some basic/common configurations.
11Running the tests
[c3bee83]14From the top level of the source, or from test/ (where this README is),
[0f5c9e1]15just run:
[c3bee83]17  make check
[c3bee83]19from test/. You can also run specific test cases by passing their
20script names to make in the TESTS variable:
[c3bee83]22  TESTS="test-03_cachetimeout_in_vhost.bash" make -e check
24This should be handy when you're just trying to experiment with a new
25test and don't want to wait for the full test suite to run.
[dff57b4]27The default configuration assumes that a loopback device with IPv4 and
28IPv6 support is available (TEST_IP="[::1]") and that
29TEST_HOST="localhost" resolves to at least one of these addresses. If
30this does not apply to your system, you can pass different values to
31./configure, e.g. to use IPv4 only:
33  TEST_HOST="localhost" TEST_IP="" ./configure
[4b53371]36Adding a Test
39Please add more tests!
[e78bc78]41The simplest way to add a test is (from test/):
[c3bee83]43  ./newtest
[e78bc78]45This will prompt you for a simple name for the test and then copy a
46starting set of files from tests/00_basic, and create a script which
47you can add to TESTS in when your test is ready for
48inclusion in the test suite.
[c3bee83]54Each test consists of a script in test/ and a directory in
55test/tests/, which the test suite uses to spin up an isolated Apache
56instance or two (for proxy tests) and try to connect to it with
57gnutls-cli and make a simple HTTP 1.1 or 1.0 request.
[c3bee83]59Test directories usually contain the following files:
[c3bee83]61 * apache.conf -- Apache configuration to be used
[c3bee83]63 * gnutls-cli.args -- the arguments to pass to gnutls-cli
65 * input -- the full HTTP request (including the final blank line)
[c3bee83]67 * backend.conf [optional] -- Apache configuration for the proxy
68   backend server, if any
[4b53371]70 * output [optional] -- the lines of this file will be checked against
71   the same number of lines at the end of the output produced by the
[c3bee83]72   gnutls-cli process. "Date" and "Server" headers are filtered from
73   the response because they are expected to change between runs
74   (date) or builds (server version).
76 * fail.server [optional] -- if this file exists, it means we expect
77   the web server to fail to even start due to some serious
78   configuration problem.
80 * fail.client [optional] -- if this file exists, it means we expect
81   the client to fail to fetch its file.  If you already have
82   fail.server, do not also specify this; we know that a failed server
83   should result in a failed file retrieval.
[c3bee83]85The "runtests" script is used to start one Apache instance and send a
86request based on the files described above. Note that some tests take
87additional steps, e.g. starting another server to act as proxy
88backend, and there is no technical requirement to use "runtests".
[b21bf4f]90By default (if "unshare" is available and has the permissions required
91to create network and user namespaces), each test case is run inside
92its own network namespace. This avoids address and port conflicts with
[c3bee83]93other tests as well has the host system.
95When writing your own tests, make sure to call netns_reexec (defined
96in common.bash) if you need to start any network services outside of
97runtests (which will create the namespace if it doesn't exist
98already). However, some architectures might not support namespaces, so
99traditional locking (using flock) and serial execution are still
103Robustness and Tuning
[c3bee83]106Here are some things that you might want to tune about the tests based
107on your expected setup (along with the variables that can be passed to
108"make check" to adjust them):
[c3bee83]110 * They need a functioning loopback device.
[c3bee83]112 * They expect (by default) to have port 9932 [TEST_PORT] available
[dff57b4]113   and open for connections on the addresses listed in TEST_IP.
[c3bee83]115 * Depending on the compile time configuration of the Apache binary
116   installed on your system you may need to load additional Apache
117   modules. The recommended way to do this is to drop a configuration
118   file into the test/apache-conf/ directory. Patches to detect such
119   situations and automatically configure the tests accordingly are
120   welcome.
122 * If a machine is particularly slow or under heavy load, it's
[4b53371]123   possible that these tests will fail for timing
[c3bee83]124   reasons. [TEST_QUERY_DELAY (seconds for the HTTP request to be sent
[34e5dc7]125   and responded to)]
[c3bee83]127The first two of these issues are avoided when the tests are isolated
128using network namespaces, which is the default (see "Implementation"
[b21bf4f]129above). The ./configure script tries to detect if namespaces can be
130used (some Linux distributions disable them for unprivileged
131users). If this detection returns a false positive or you do not want
132to use namespace isolation for some other reason, you can run
133configure with the --disable-test-namespaces option.
[f9f184f]135In some situations you may want to see the exact environment as
136configured by make, e.g. if you want to manually run an Apache
137instance with Valgrind using the same configuration as a test
138case. Use "make show-test-env" to dump AM_TESTS_ENVIRONMENT to stdout.
140If you are building on an exotic architecture which does not support
141flock (or timeouts using flock -w), you can disable it by passing
142"--disable-flock" to ./configure. This will force serial execution of
143tests, including environment setup.
Note: See TracBrowser for help on using the repository browser.