1tntnet.xml(8) Tntnet users guide tntnet.xml(8)
2
6 tntnet.xml - configuration file for tntnet(8)
7
9 Tntnet is configured using a xml file. The name of the file is tnt‐
10 net.xml. The root node of tntnet.xml should be tntnet while it is not
11 checked. Most of the settings are just single values. They are
12 described here in alphabetical order.
13
15 This section describes the variables, used by Tntnet (8).
16 <accessLog>filename</accessLog>
18 Writes a log entry for each request in a common format. This
19 format is compatible with most log file analyze systems for http
20 servers.
21 The log file has the fields: peer-ip - username [time] "http-
23 method query-string HTTP/major-version.minor-version" http-
24 return-code content-size "referer" "user-agent"
25 The username, referer and user-agent may be '-' when the value
27 is not available. Also the content-size can be empty in some
28 cases.
29 Example
31 <accessLog>/var/log/tntnet/access.log</accessLog
33 <bufferSize>bytes</bufferSize>
35 Specifies the number of bytes sent in a single system-call. This
37 does not limit anything in application-level. It does not affect
38 e.g. savepoints or exception-handling. Component-output is col‐
39 lected completely and then passed in chunks of bufferSize bytes
40 to the operating system.
41 The default value is 16384.
43 <comppath> [ <entry>path1</entry> ] </comppath>
45 comppath specifies, where tntnet should search for webapplica‐
47 tions. Tntnet searches first in the current directory and then
48 in each directory, you specify here, until a library is found.
49 You can repeat the directive as many times as desired to add
50 more entries. If it is not found, the next mappings entry is
51 tried.
52 Example
54 <comppath>
56 <entry>/usr/local/lib/tntnet</entry>
57 <entry>/usr/local/share/tntnet</entry>
58 </comppath>
59 <chroot>directory</chroot>
61 Does a chroot(2)-system call on startup, which locks the process
63 into the directory at system-level.
64 Example
66 <chroot>/var/tntnet</chroot>
68 <daemon>0|1</daemon>
70 If this flag is set to 1, Tntnet forks at startup and terminates
72 the parent-process on successful initialization.
73 <dir>directory</dir>
75 Changes the current working directory of the process on startup.
77 Example
79 <dir>/var/tntnet</dir>
81 <enableCompression>yes|no</enableCompression>
83 Specifies, if Tntnet should use gzip-compression at http-level.
85 By default Tntnet use compression. A http-client like a web
86 browser can send a header "Accept-Encoding", to tell Tntnet,
87 that it would accept compressed data. Tntnet then can decide,
88 if it use compression. When the body is complete, Tntnet tries
89 to compress the body. If the data can be compressed by more than
90 10%, Tntnet sends this compressed data. With this flag, this
91 feature can be turned off.
92 Compression slows down processing but reduces the network-load.
94 Normally the size of html-pages can be compressed by about 70%,
95 while Tntnet slows down by up to 30%.
96 Example
98 <enableCompression>no</enableCompression>
100 <errorLog>filename</errorLog>
102 Redirects stderr to the specified file when tntnet runs as a
104 daemon. If ErrorLog is not set stderr is redirected to
105 /dev/null.
106 Example
108 <errorLog>/var/log/tntnet/error.log</errorLog>
110 <group>unix-group-id</group>
112 Changes the group under which tntnet runs.
114 The user is changes using the system call setgid(2), which is
116 only allowed, when tntnet starts as root user.
117 Example
119 <group>tntnet-group</group>
121 <keepAliveTimeout>milliseconds</keepAliveTimeout>
123 Sets the timeout for keep-alive requests.
125 Tntnet tries to do keep-alive-requests wherever possible. This
127 has the effect, that tntnet can receive multiple requests within
128 a single tcp-connection. The connection times out after
129 KeepAliveTimeout milliseconds. The timeout defaults to 15000ms.
130 Example
132 <keepAliveTimeout>300000</keepAliveTimeout>
134 <keepAliveMax>number</keepAliveMax>
136 Sets the maximum number of request per tcp-connection. This
138 defaults to 100.
139 Example
141 <keepAliveTimeout>10</keepAliveTimeout>
143 <listeners>listener definition</listeners>
145 Specifies, on which local interfaces tntnet waits for connec‐
147 tions. There can be more than one Listen-directives, in which
148 case tntnet waits on every address.
149 See separate section Listeners
151 <logging>listener definition</logging>
153 Configures logging. See separate section logging
155 <listenRetry>number</listenRetry>
157 On startup Tntnet calls listen on the specified port. When the
159 systemcall returns with an error, Tntnet tries again and fails
160 after the specified number of attempts.
161 The default number is 5.
163 Example
165 <listenRetry>10</listenRetry>
167 <listenBacklog>number</listenBacklog>
169 The system-call listen(3p) needs a parameter backlog, which
171 specifies, how many pending connections the operating-system
172 should queue before it starts to ignore new request. The value
173 is configurable here.
174 The default value is 16.
176 Example
178 <ListenBacklog>64</ListenBacklog>
180 <mappings>urlmappings</mappings>
182 This is the most important setting for tntnet. It specifies,
184 which components schould be called on which urls.
185 For details see the section Url mapping.
187 <maxUrlMapCache>number</maxUrlMapCache>
189 Mapping urls to components is done using regular expressions.
191 Executing these expressions is quite expensive while the number
192 of different urls is quite limited in typical web applications.
193 Hence tntnet caches the results.
194 The caching algorithm is very simple. Tntnet just collects the
196 results in a map. When the maximum size of the list is reached,
197 it is cleared. This makes management of the cache very cheap.
198 This setting sets the maximum number of entries in the map.
200 If you see frequently a warning message, that the cache is
202 cleared, you may consider increasing the size.
203 The default value is 8192.
205 Example
207 <maxUrlMapCache>32768</maxUrlMapCache>
209 <maxRequestSize>number</maxRequestSize>
211 This directive limits the size of the request. After number
213 Bytes the connection is just closed. This prevents
214 denial-of-service-attacks through long requests. Every request
215 is read into memory, so it must fit into it. Bear in mind, that
216 if you use file-upload-fields a request might be larger than
217 just a few bytes.
218 The value defaults to 0, which means, that there is no limit at
220 all.
221 Example
223 <maxRequestSize>65536</maxRequestSize>
225 <maxRequestTime>seconds</maxRequestTime>
227 In daemon mode tntnet has a watchdog, which restarts tntnet when
229 the maximum request time is exceeded. This happens, when a
230 request is in a endless loop or otherwise hangs. Restarting tnt‐
231 net looses all active sessions and the currently running
232 requests. Therefore the timeout should be well long enough for
233 the longes request.
234 The default value is 600 seconds, which is normally much longer
236 than a http request should run. If the Timeout is set to 0, the
237 watchdog is deactivated.
238 Example
240 <maxRequestTime>1200</maxRequestTime>
242 <minThreads>number</minThreads>
244 Tntnet uses a dynamic pool of worker-threads, which wait for
246 incoming requests. MinThreads specifies, how many worker threads
247 there have to be. This defaults to 5.
248 Example
250 <minThreads>10</minThreads>
252 <minCompressSize>number</minCompressSize>
254 Http-compression for replies smaller than this are not com‐
256 pressed at all.
257 The default value for this is 1024.
259 Example
261 <minCompressSize>256</minCompressSize>
263 <mimeDb>filename</mimeDb>
265 Specify filename for mime db. The default is /etc/mime.types.
267 The format of the file is just like this /etc/mime.types. A mime
269 type is followed after white space by a list of file extensions
270 delimited by white space.
271 <maxThreads>number</maxThreads>
273 Tntnet uses a dynamic pool of worker-threads, which wait for
275 incoming requests. maxThreads limits the number of threads.
276 The default is 100.
278 Example
280 <maxThreads>200</maxThreads>
282 <pidFile>filename</pidFile>
284 When run in daemon-mode, tntnet writes the process-id of the
286 monitor-process to filename. When the monitor-process is deacti‐
287 vated, the pid of the worker-process is written. This ensures,
288 that sending a sigkill to the the stored process-id stops tnt‐
289 net.
290 Example
292 <pidFile>/var/run/tntnet.pid</pidFile>
294 <queueSize>number</queueSize>
296 Tntnet has a request-queue, where new requests wait for service.
298 This sets a maximum size of this queue, after wich new requests
299 are not accepted.
300 The default value is 1000.
302 Example
304 <queueSize>50</queueSize>
306 <sessionTimeout>seconds</sessionTimeout>
308 This sets the number of seconds without requests after which a
310 sesssion is timed out.
311 The default value is 300 seconds.
313 Example
315 <sessionTimeout>600</sessionTimeout>
317 <socketReadTimeout>milliseconds</socketReadTimeout>
319 A worker-thread waits for some milliseconds on incoming data. If
321 there is no data, the job is put into a queue and another thread
322 waits with poll(2) on incoming data on multiple sockets. The
323 workerthreads are freed and they can respond to other requests
324 quickly. The default value is 10 milliseconds, which is good for
325 normal operation. A value of 0 results in non-blocking read. If
326 timeout is reached, this does not mean, that the socket is
327 closed. A small timeout reduces contextswitches on slow connec‐
328 tions.
329 Example
331 <socketReadTimeout>0</socketReadTimeout>
333 <socketWriteTimeout>milliseconds</socketWriteTimeout>
335 This defines the time, how long the workerthreads wait on write.
337 If the timeout is exceeded, the socket is closed and the browser
338 might not get all data. The default value is 10000 millisec‐
339 onds.
340 Example
342 <socketWriteTimeout>20000</socketWriteTimeout>
344 <threadStartDelay>ms</threadStartDelay>
346 When additional worker threads are needed tntnet waits the num‐
348 ber of milliseconds before it starts additional threads to pre‐
349 vent high load when starting many threads at once.
350 The default value is 10ms.
352 Example
354 <threadStartDelay>1000</threadStartDelay>
356 <user>username</user>
358 Changes the user under which tntnet answers requests.
360 The user is changes using the system call setuid(2), which is
362 only allowed, when tntnet starts as root user.
363 Example
365 <user>www-data</user>
367
369 Tntnet is a web server, which receives http requests from a http client
370 and answers them. A http request has a url and other attributes, which
371 are used to decide, how the answer should look like. This is done my
372 mapping urls to components.
373 A component is something, which generates a http reply. They are nor‐
375 mally generated with the ecpp compiler ecppc(1). The ecppc compiler
376 generated C++ classes with component names. The classes are compiled
377 and linked into a shared library. Both the component name and the
378 shared library name is needed to identify a component.
379 The component identifier is a string built from the component name, the
381 @ character and the shared library name. A example is myclass@myappli‐
382 cation. This tells tntnet: load shared library myapplication and call
383 the component with the name myclass in that library, which creates the
384 reply to the request.
385 To tell tntnet, which component to call, url mappings must be config‐
387 ured.
388 Configuration is done in the xml section <mappings>. Multiple mappings
390 can be configured there. A mapping has a condition and a target. Tntnet
391 looks in the list of mappings for the first mapping, where the condi‐
392 tion is met and uses that to call the component. The component may
393 return either a reply - then the request is done or a special value
394 DECLINED, which tells tntnet to continue in the list and look for the
395 next mapping, where the condition is met.
396 The component, which returns DECLINED may already have generated part
398 of the request. This is preserved for the next mapping. A common use
399 case is to write a special component, which just checks the user name
400 and password. If the user name and password is valid, DECLINED is
401 returned and tntnet calls the next mapping where the condition is met.
402 Also when the condition is met, but the component could not be loaded,
404 tntnet continues with the next mapping.
405 When the end of the list is reached and no mapping returned a http
407 reply code, tntnet replies with http not found (404) error.
408 So how these mapping are specified then?
410 The mapping contains 3 kind of nodes:
412 conditions
414 Multiple conditions can be specified. All conditions must be met
415 when the mapping is to be used.
416 The most important is <url>, which contains a extended regular
418 expression (see regex(7) for details). This expression is
419 checked against the url of the request. If the url tag is omit‐
420 ted, the mapping is used for every url.
421 The condition <vhost> specifies the virtual host, for which this
423 mapping is valid. When this is specified, the mapping is only
424 valid for requests, where the virtual host matches the setting.
425 The value is also a extended regular expression. Note, that a
426 dot matches any character in regular expressions, which may be
427 irritating here. If you want to specify a mapping for the all
428 hosts of the domain tntnet.org, you have to set <vhost>tnt‐
429 net\.org$</vhost>. Also the dollar sign at the end is important,
430 since it matches the end of the string. Otherwise the mapping
431 would be also valid for a virtual host like tntnet.org.foo.com,
432 which may not be what you meant.
433 The condition method specifies the http method for which the
435 mapping should be considered. Again a extended regular expres‐
436 sion is used.
437 The condition ssl is a boolean value. The value should be 0 or
439 1. The setting checks, whether this mapping should be used
440 depending on ssl. If the value is 1, the condition is met, when
441 the request is sent via ssl. If the value is 0, the condition is
442 met, when the request is sent without ssl.
443 target The mapping node contains a node <target>, which contains the
445 component name, which is to be called when the conditions are
446 met.
447 The target may contain back references to the regular expression
449 in the <url> condition. Parts of the regular expression may be
450 in brackets. In the target $1 is replaced with the first brack‐
451 eted expression, $2 with the second and so on.
452 This node is mandatory.
454 parameters
456 When the condition is met, additional parameters may be passed
457 to the called component. There are 2 nodes for this.
458 The node <pathinfo> can be requested in the component using
460 request.getPathInfo(). If the node is not set, the url is set as
461 path info.
462 The node <args> contains additional parameters, which can be
464 passed to the component. The node can have any number of nodes
465 with values. The tags are used as a parameter name and the con‐
466 tent as the value. The method request.getArg(name) returns the
467 value of the specified name. When the node is not set, the
468 method returns a empty string. Optionally a diffrent default
469 value can be passed to the method as an additional parameter
470 like request.getArg(name,defaultValue).
471 For compatibility reasons with older tntnet request.getArg
473 accepts a numeric argument. Previously the arguments did not
474 have names but were accessed by index. To emulate this,
475 request.getArg with a numeric argument translates the number
476 into the name "argnumber". So accessing request.getArg(2)
477 returns the value of the argument with the name arg2. Accessing
478 a numeric argument equal or greater than the number of arguments
479 (the first is number 0) used to be not allowed. Now a empty
480 string is returned.
481 Example
483 <mappings>
485 <!-- map / to index@myapp -->
486 <mapping>
487 <target>index@myapp</target>
488 <url>^/$</url>
489 <pathinfo>index.html</pathinfo>
490 </mapping>
491 <!-- map /comp.* or /comp to comp@myapp -->
492 <mapping>
493 <target>action@myapp</target>
494 <url></url> <!-- any url -->
495 <method>POST</method> <!-- but only on method POST -->
496 <vhost>localhost</vhost> <!-- and host header must be localhost -->
497 <ssl>1</ssl> <!-- and ssl is enabled -->
498 </mapping>
499 <mapping>
500 <target>$1@myapp</target>
501 <url>^/([^.]+)(\.(.+))?</url>
502 <args>
503 <extension>$2</extension>
504 </args>
505 </mapping>
506 </mappings>
507
509 The section <listeners> specifies the ip addresses and ports, where
510 tntnet waits for incoming requests. Multiple listeners may be defined,
511 when tntnet should listen on multiple ip addresses or ports.
512 Each listener is defined in a node <listener>. A listener must have a
514 subnode <ip> and <port>. The node <ip> may contain a ip address or
515 hostname or may be left empty. If the node is empty, any interface is
516 used. The <port> must contain the numeric port number.
517 The ip address may be a IPv4 or IPv6 address.
519 Optionally a tag <certificate> may be added. This enables ssl on the
521 interface and specifies the ssl host certificate for the interface.
522 Note that tntnet can be built without ssl support. In that case the
523 certificate is just ignored and unencrypted http is used here.
524 Example
526 <listeners>
528 <listener>
529 <ip></ip>
530 <port>80</port>
531 </listener>
532 <listener>
533 <ip></ip>
534 <port>443</port>
535 <!-- a certificate enables ssl -->
536 <certificate>tntnet.pem</certificate>
537 </listener>
538 </listeners>
539
541 This manual page was written by Tommi Mäkitalo ⟨tommi@tntnet.org⟩.
542
544 tntnet (1)
545Tntnet 2006-07-23 tntnet.xml(8)