Newer
Older
Tools for creating and testing TLMSP (ETSI TS 103 523-2) clients, middleboxes,
and servers.
* [Overview](#overview)
* [Building](#building)
+ [Dependencies](#dependencies)
+ [Initial build](#initial-build)
+ [Update build](#update-build)
+ [Debug build](#debug-build)
* [Running](#running)
+ [Configuration](#configuration)
+ [tlmsp-client, tlmsp-mb, tlmsp-server](#tlmsp-client--tlmsp-mb--tlmsp-server)
+ [apache-httpd](#apache-httpd)
+ [curl](#curl)
tlmsp-tools provides several libraries and executables:
tlmsp-tools component | Description
------------------------|-------------------
tlmsp-client | Client program
tlmsp-mb | Middlebox program
tlmsp-server | Server program
libdemo | Common components for tlmsp-{client, mb, server}
libtlmsp-cfg | Library for parsing and accessing UCL-based configuration files
libtlmsp-util | Utility routines of interest to multiple TLMSP programs
libucl | Local build of libucl, as it isn't available on all platforms
<br>
tlmsp-tools also serves to coordinate the building of additional TLMSP-enabled
packages:
<br><br>
Additional components | Description
----------------------|---------------------
apache-httpd | Apache httpd version that can serve pages over TLMSP
curl | curl version that can fetch pages over TLMSP
openssl | OpenSSL modified to support TLMSP; used by apache, curl, and tlmsp-tools
## Building
### Dependencies
tlmsp-tools requires:
* autotools
* clang
* libev
* libpcre2
* parallel
apache-httpd additionally requires:
* libexpat
* libpcre (old version)
On Ubuntu 18.04 LTS, the following obtains all of the necessary
pieces:
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
`sudo apt-get install autoconf clang gettext libexpat1-dev libpcre3-dev libpcre2-dev libtool-bin libev-dev parallel pkg-config`
### Initial build
```
# Starting in some <directory_root>, resulting in installation to
# <directory_root>/install
mkdir tlmsp
cd tlmsp
git clone git@forge.etsi.org:cyber/tlmsp-tools.git
cd tlmsp-tools/build
./build.sh
# You will now have
# tlmsp/
# install/
# apache-httpd/
# curl/
# openssl/
# tlmsp-tools/
```
Adjust your `PATH` to include `<directory_root>/tlmsp/install/bin` ahead of
any system paths that may contain executables with the same names.
Adjust your `LD_LIBRARY_PATH` to include
`<directory_root>/tlmsp/install/lib` ahead of any other system paths that
may contain libraries with the same names.
Set TLMSP_UCL to `<directory_root>/tlmsp/install/share/tlmsp-tools/examples`.
Scripts that can be sourced in shell init files to set up the environment as
described above are installed in `<directory_root>/tlmsp/install/share/tlmsp-tools`.
Self-signed certificates and corresponding private keys (sufficient to satisfy
the default requirements for a client, server, and maximum number of
middleboxes) are installed under `<install_dir>/etc/pki` and
`<install_dir>/etc/pki/private`, respectively.
### Update build
After an initial build has been done, the following will pick up all source
changes, reconfigure, rebuild, and reinstall.
```
# While in tlmsp-tools/build
git pull
./build.sh -u
```
### Debug build
Add '-d' to the build.sh options used in order to configure and build with
compiler optimizations disabled, and compiler debug symbols and per-package
extra debug mechanisms engaged.
## Running
### Configuration
All of the programs obtain their TLMSP-related configuration from a file whose
format is described in `tlmsp-tools/libtlmsp-cfg/everything.ucl`. The
configuration file defines:
* The TLMSP entities
* The PKI configuration for each entity
* The network topology
* The TLMSP contexts being used
* The access rights of each middlebox for each context
* For tlmsp-client, tlmsp-mb, and tlmsp-server, match-action specifications
('activities') that determine their behavior
The following table summarizes the blocks from the configuration file that each
program consumes.
Program | Contexts | Client | Middleboxes | Server | Activities | Notes
:------------|:--------:|:------:|:-----------:|:------:|:----------:|:---------
tlmsp-client | X | X | X | X | X |
tlmsp-mb | | | X | X | X | Context and server address details normally obtained from the wire; when transparent middleboxes are configured, the transparency emulation sometimes requires a peek at the server block in the config file.
tlmsp-server | X | | X | X | X |
apache-httpd | X | | X | | | Server address and PKI config come from the apache configuration
curl | X | X | X | X | | Client used only for client address; Server used only for address to validate command line URL
<br>
Sample configuration files are installed in `<install_dir>/share/tlmsp-tools/examples`.
### tlmsp-client, tlmsp-mb, tlmsp-server
The server and middlebox(es) can be started in any order. The client, of course, needs to be started last.
```
# -P turns on 'presentation' style logging, which narrates the match-action activity in a relatively uncluttered way
tlmsp-server -c config.ucl -P
```
```
# middleboxes require specification of which one in the given config file to run
tlmsp-mb -c config.ucl -t mbox1 -P
# or which ones
tlmsp-mb -c config.ucl -t mbox1 -t mbox2 -P
# or all
tlmsp-mb -c config.ucl -a -P
```
```
tlmsp-client -c config.ucl -P
```
Aside from configurable logging, these three programs will print out summary
statistics in response to a specific signal. Under FreeBSD, this is SIGINFO,
which can be delivered to a process controlling a terminal by using Ctrl+T.
Under Linux, one has to resort to `kill -SIGUSR1 <pid>` from another terminal.
### apache-httpd
The apache-httpd configuration is installed at `<install_dir>/etc/apache24/httpd.conf`
and includes `<install_dir>/etc/apache24/httpd_tlmsp.conf`, which in turn
defines several virtual hosts:
| Listen address | Configuration file |
|----------------|---------------------------------|
| localhost:4443 | ${TLMSP_UCL}/apache.ucl |
| localhost:4444 | ${TLMSP_UCL}/apache.1mbox.ucl |
| localhost:4445 | ${TLMSP_UCL}/apache.2mbox.ucl |
| localhost:4446 | ${TLMSP_UCL}/apache.251mbox.ucl |
<br>
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
The apache-httpd TLMSP integration requires the UCL file to define two contexts,
one with the tag 'header' and one with the tag 'body', into which it places
response headers and bodies, respectively.
Pages are served out of `<install_dir>/share/apache24/htdocs` and logs can be
found in `<install_dir>/var/logs`.
```
# Start apache in the single-worker, foreground mode
httpd -X
```
```
# If using the server on port 4444, a middlebox will need to be started
tlmsp-mb -c ${TLMSP_UCL}/apache.1mbox.ucl -t mbox1 -P
```
```
# Run tlmsp-client, here against the server on port 4443
tlmsp-client -c ${TLMSP_UCL}/apache.ucl -P
# or use curl, again assuming against the server on port 4443
curl --tlmsp ${TLMSP_UCL}/apache.ucl https://localhost:4443 -k -v
```
Either client should successfully fetch the default index.html that installs
with apache, which consists of:
```
<html><body><h1>It works!</h1></body></html>
```
### curl
The curl TLMSP integration requires the UCL file to define two contexts, one
with the tag 'header' and one with the tag 'body', into which it places request
headers and bodies, respectively.
Also, the server hostname and port indicated in the URL on the command line
must match the hostname and port indicated by the server address in the UCL file.
curl continues to require an explicit URL in TLMSP mode so that different request
paths can be specified without having to edit the UCL file.
```
tlmsp-server -c ${TLMSP_UCL}/curl.ucl -P
```
```
curl --tlmsp ${TLMSP_UCL}/curl.ucl https://localhost:10254 -k -v
```