1tntnet.xml(7)                 Tntnet users guide                 tntnet.xml(7)
2
3
4

NAME

6       tntnet.xml - configuration file for tntnet(8)
7
8

DESCRIPTION

10       Tntnet  is  configured  using  a xml file. The name of the file is tnt‐
11       net.xml. The root node of tntnet.xml should be tntnet while it  is  not
12       checked.  Most  of  the  settings  are  just  single  values.  They are
13       described here in alphabetical order.
14
15

SETTINGS

17       This section describes the variables, used by Tntnet (8).
18
19
20       <accessLog>filename</accessLog>
21
22
23       Writes a log entry for each request in a common format. This format is
24         compatible with most log file analyze systems for http servers.
25
26
27       The log file has the fields: peer ip - username [time] "http method
28         query string HTTP/major version.minor version" http return code
29         content size "referer" "user agent"
30
31
32       The username, referer and user agent may be '-' when the value is not
33         available. Also the content-size can be empty in some cases.
34
35
36       Example
37
38
39              <accessLog>/var/log/tntnet/access.log</accessLog
40
41
42
43       <bufferSize>bytes</bufferSize>
44
45
46       Specifies the number of bytes sent in a single system call.  This  does
47       not
48         limit  anything  in  application level. It does not affect e.g. save‐
49       points or
50         exception handling. Component output is collected completely and then
51       passed
52         in chunks of bufferSize bytes to the operating system.
53
54
55       The default value is 16384.
56
57
58       <compPath> [ <entry>path1</entry> ] </compPath>
59
60
61       comppath  specifies,  where  tntnet  should search for webapplications.
62       Tntnet
63         searches first in the current directory and then in  each  directory,
64       you
65         specify  here, until a library is found. You can repeat the directive
66       as many
67         times as desired to add more entries. If it is not found, the next
68         mappings entry is tried.
69
70
71       Example
72
73
74              <comppath>
75                <entry>/usr/local/lib/tntnet</entry>
76                <entry>/usr/local/share/tntnet</entry>
77              </comppath>
78
79
80
81       <chroot>directory</chroot>
82
83
84       Does a chroot(2) system call on startup, which locks the  process  into
85       the
86         directory at system level.
87
88
89       Example
90
91
92              <chroot>/var/tntnet</chroot>
93
94
95
96       <daemon>0|1</daemon>
97
98
99       If this flag is set to 1, Tntnet forks at startup and terminates the
100         parent process on successful initialization.
101
102
103       <dir>directory</dir>
104
105
106       Changes the current working directory of the process on startup.
107
108
109       Example
110
111
112              <dir>/var/tntnet</dir>
113
114
115
116       <defaultContentType>contentType</defaultContentType>
117
118
119       Sets  the  content  type  header  of the reply. The content type may be
120       changed in
121         the application using reply.setContentType("something").
122
123
124       By default "text/html; charset=UTF-8" is set.
125
126
127       Example
128
129
130              <defaultContentType>text/html; charset=ISO-8858-1</defaultContentType>
131
132
133
134       <enableCompression>yes|no</enableCompression>
135
136
137       Specifies, if Tntnet should use gzip  compression  at  http  level.  By
138       default
139         Tntnet  use  compression. A http client like a web browser can send a
140       header
141         "Accept-Encoding", to tell Tntnet, that it  would  accept  compressed
142       data.
143         Tntnet  then can decide, if it use compression. When the body is com‐
144       plete,
145         Tntnet tries to compress the body. If the data can be  compressed  by
146       more than
147         10%,  Tntnet sends this compressed data. With this flag, this feature
148       can be
149         turned off.
150
151
152       Compression slows down processing but reduces the  network  load.  Nor‐
153       mally the
154         size of html pages can be compressed by about 70%, while Tntnet slows
155       down by
156         up to 30%.
157
158
159       Example
160
161
162              <enableCompression>no</enableCompression>
163
164
165
166       <environment>  <name1>value1</name1>  <name2>value2</name2>  </environ‐
167       ment>
168
169
170       Sets environment variables.
171
172
173       <errorLog>filename</errorLog>
174
175
176       Redirects stderr to the specified file when tntnet runs as a daemon. If
177         ErrorLog is not set stderr is redirected to /dev/null.
178
179
180       Example
181
182
183              <errorLog>/var/log/tntnet/error.log</errorLog>
184
185
186
187       <group>unix-group-id</group>
188
189
190       Changes the group under which tntnet runs.
191
192
193       The  user  is  changes  using  the system call setgid(2), which is only
194       allowed,
195         when tntnet starts as root user.
196
197
198       Example
199
200
201              <group>tntnet-group</group>
202
203
204
205       <keepAliveTimeout>milliseconds</keepAliveTimeout>
206
207
208       Sets the timeout for keep-alive requests.
209
210
211       Tntnet tries to do keep-alive-requests wherever possible. This has  the
212       effect,
213         that tntnet can receive multiple requests within a single tcp connec‐
214       tion. The
215         connection times out after KeepAliveTimeout milliseconds. The timeout
216       defaults
217         to 15000ms.
218
219
220       Example
221
222
223              <keepAliveTimeout>300000</keepAliveTimeout>
224
225
226
227       <keepAliveMax>number</keepAliveMax>
228
229
230       Sets the maximum number of request per tcp connection. This defaults to
231       100.
232
233
234       Example
235
236
237              <keepAliveTimeout>10</keepAliveTimeout>
238
239
240
241       <listeners>listener definition</listeners>
242
243
244       Specifies, on which local  interfaces  tntnet  waits  for  connections.
245       There can
246         be  more  than  one  Listen directives, in which case tntnet waits on
247       every
248         address.
249
250
251       See separate section Listeners
252
253
254       <logging>logger definition</logging>
255
256
257       Configures logging. See separate section logging
258
259
260       <listenRetry>number</listenRetry>
261
262
263       On startup Tntnet calls listen on the specified port. When the  system‐
264       call
265         returns  with an error, Tntnet tries again and fails after the speci‐
266       fied number
267         of attempts.
268
269
270       The default number is 5.
271
272
273       Example
274
275
276              <listenRetry>10</listenRetry>
277
278
279
280       <listenBacklog>number</listenBacklog>
281
282
283       The system call listen(3p) needs a parameter backlog, which  specifies,
284       how
285         many  pending connections the operating system should queue before it
286       starts to
287         ignore new request. The value is configurable here.
288
289
290       The default value is 16.
291
292
293       Example
294
295
296              <ListenBacklog>64</ListenBacklog>
297
298
299
300       <mappings>urlmappings</mappings>
301
302
303       This is the most important setting for tntnet. It specifies, which com‐
304       ponents
305         schould be called on which urls.
306
307
308       For details see the section URL MAPPING.
309
310
311       <maxUrlMapCache>number</maxUrlMapCache>
312
313
314       Mapping urls to components is done using regular expressions. Executing
315       these
316         expressions is quite expensive while the number of different urls  is
317       quite
318         limited in typical web applications. Hence tntnet caches the results.
319
320
321       The  caching algorithm is very simple. Tntnet just collects the results
322       in a
323         map. When the maximum size of the list is  reached,  it  is  cleared.
324       This makes
325         management of the cache very cheap.
326
327
328       This setting sets the maximum number of entries in the map.
329
330
331       If you see frequently a warning message, that the cache is cleared, you
332       may
333         consider increasing the size.
334
335
336       The default value is 8192.
337
338
339       Example
340
341
342              <maxUrlMapCache>32768</maxUrlMapCache>
343
344
345
346       <maxRequestSize>number</maxRequestSize>
347
348
349       This directive limits the size of the request. After number Bytes the
350         connection is just closed. This prevents denial  of  service  attacks
351       through
352         long requests. Every request is read into memory, so it must fit into
353       it.
354         Bear in mind, that if you use file upload fields a request  might  be
355       larger
356         than just a few bytes.
357
358
359       The value defaults to 0, which means, that there is no limit at all.
360
361
362       Example
363
364
365              <maxRequestSize>65536</maxRequestSize>
366
367
368
369       <maxRequestTime>seconds</maxRequestTime>
370
371
372       In  daemon  mode  tntnet has a watchdog, which restarts tntnet when the
373       maximum
374         request time is exceeded. This happens, when a request is in  a  end‐
375       less loop or
376         otherwise hangs. Restarting tntnet looses all active sessions and the
377         currently running requests. Therefore the timeout should be well long
378       enough
379         for the longes request.
380
381
382       The default value is 600 seconds, which is normally much longer than  a
383       http
384         request should run. If the Timeout is set to 0, the watchdog is deac‐
385       tivated.
386
387
388       Example
389
390
391              <maxRequestTime>1200</maxRequestTime>
392
393
394
395       <minThreads>number</minThreads>
396
397
398       Tntnet uses a dynamic pool of worker threads, which wait for incoming
399         requests. MinThreads specifies, how many worker threads there have to
400       be. This
401         defaults to 5.
402
403
404       Example
405
406
407              <minThreads>10</minThreads>
408
409
410
411       <minCompressSize>number</minCompressSize>
412
413
414       Http  compression  for  replies smaller than this are not compressed at
415       all.
416
417
418       The default value for this is 1024.
419
420
421       Example
422
423
424              <minCompressSize>256</minCompressSize>
425
426
427
428       <mimeDb>filename</mimeDb>
429
430
431       Specify filename for mime db. The default is /etc/mime.types.
432
433
434       The format of the file is just like this /etc/mime.types. A  mime  type
435       is
436         followed  after white space by a list of file extensions delimited by
437       white
438         space.
439
440
441       <maxThreads>number</maxThreads>
442
443
444       Tntnet uses a dynamic pool of worker threads, which wait for incoming
445         requests. maxThreads limits the number of threads.
446
447
448       The default is 100.
449
450
451       Example
452
453
454              <maxThreads>200</maxThreads>
455
456
457
458       <pidfile>filename</pidfile>
459
460
461       When run in daemon mode, tntnet writes the process id  of  the  monitor
462       process
463         to filename. When the monitor process is deactivated, the pid of the
464         worker  process  is  written. This ensures, that sending a sigkill to
465       the the
466         stored process id stops tntnet.
467
468
469       Example
470
471
472              <pidfile>/var/run/tntnet.pid</pidfile>
473
474
475
476       <queueSize>number</queueSize>
477
478
479       Tntnet has a request queue, where new requests wait for  service.  This
480       sets a
481         maximum size of this queue, after wich new requests are not accepted.
482
483
484       The default value is 1000.
485
486
487       Example
488
489
490              <queueSize>50</queueSize>
491
492
493
494       <reuseAddress>0|1</reuseAddress>
495
496
497       The  flag  specifies  whether  the socket option SO_REUSEADDR should be
498       set.
499         When the entry is omitted the flag is set.
500
501
502       <server>name</server>
503
504
505       Set the server response header. Tntnet sets the http  header  "Server:"
506       to
507         "Tntnet/version"  by  default.  Whith  this setting the header can be
508       changed.
509
510
511       Example
512
513
514              <server>Myserver version 1.2</server>
515
516
517
518       <sessionTimeout>seconds</sessionTimeout>
519
520
521       This sets the number of seconds without requests after which a sesssion
522       is
523         timed out.
524
525
526       The default value is 300 seconds.
527
528
529       Example
530
531
532              <sessionTimeout>600</sessionTimeout>
533
534
535
536       <socketReadTimeout>milliseconds</socketReadTimeout>
537
538
539       A  worker thread waits for some milliseconds on incoming data. If there
540       is no
541         data, the job is put into a  queue  and  another  thread  waits  with
542       poll(2) on
543         incoming  data  on  multiple sockets. The workerthreads are freed and
544       they can
545         respond to other requests quickly. The default value is 10  millisec‐
546       onds, which
547         is  good  for  normal operation. A value of 0 results in non blocking
548       read. If
549         timeout is reached, this does not mean, that the socket is closed.  A
550       small
551         timeout reduces contextswitches on slow connections.
552
553
554       Example
555
556
557              <socketReadTimeout>0</socketReadTimeout>
558
559
560
561       <socketWriteTimeout>milliseconds</socketWriteTimeout>
562
563
564       This  defines  the  time, how long the workerthreads wait on write.  If
565       the
566         timeout is exceeded, the socket is closed and the browser  might  not
567       get all
568         data.  The default value is 10000 milliseconds.
569
570
571       Example
572
573
574              <socketWriteTimeout>20000</socketWriteTimeout>
575
576
577
578       <threadStartDelay>ms</threadStartDelay>
579
580
581       When additional worker threads are needed tntnet waits the number of
582         milliseconds before it starts additional threads to prevent high load
583       when
584         starting many threads at once.
585
586
587       The default value is 10ms.
588
589
590       Example
591
592
593              <threadStartDelay>1000</threadStartDelay>
594
595
596
597       <user>username</user>
598
599
600       Changes the user under which tntnet answers requests.
601
602
603       The user is changes using the system  call  setuid(2),  which  is  only
604       allowed,
605         when tntnet starts as root user.
606
607
608       Example
609
610
611              <user>www-data</user>
612
613
614
615       <virtualhosts>  { <virtualhost> <hostname>hostname-regex</hostname>map‐
616       pings</virtualhost> }</virtualhosts>
617
618
619       Defines mappings for virtual hosts. These mappings are valid only  when
620       the
621         host header matches the hostname-regex. See section URL MAPPING for
622         details about how to define actual mappings
623
624
625       A vhost entry in the mappings should be empty since it is already spec‐
626       ified
627         for the whole group.
628
629
630       The mappings defined here are always matched before the mappings on the
631       top
632         level of the configuration.
633
634
635       Example
636
637
638              <virtualhosts>
639                <virtualhost>
640                  <hostname>www\.tntnet\.org</hostname>
641                  <mappings>
642                    <mapping>
643                      <url>^/$</url>
644                      <target>static@tntent</target>
645                      <pathinfo>htdocs/index.html</pathinfo>
646                    </mapping>
647                    <mapping>
648                      <url>^/(.*)$</url>
649                      <target>static@tntent</target>
650                      <pathinfo>htdocs/$1</pathinfo>
651                    </mapping>
652                  </mappings>
653                </virtualhost>
654              </virtualhosts>
655
656
657

URL MAPPING

659       Tntnet is a web server, which receives http requests from a http client
660       and answers them. A http request has a url and other attributes,  which
661       are  used  to  decide, how the answer should look like. This is done my
662       mapping urls to components.
663
664
665       A component is something, which generates a http reply. They  are  nor‐
666       mally  generated  with  the  ecpp compiler ecppc(1). The ecppc compiler
667       generated C++ classes with component names. The  classes  are  compiled
668       and  linked  into  a  shared  library.  Both the component name and the
669       shared library name is needed to identify a component.
670
671
672       The component identifier is a string built from the component name, the
673       @  character and the shared library name. A example is myclass@myappli‐
674       cation.  This tells tntnet: load shared library myapplication and  call
675       the  component with the name myclass in that library, which creates the
676       reply to the request.
677
678
679       To tell tntnet, which component to call, url mappings must  be  config‐
680       ured.
681
682
683       Configuration  is done in the xml section <mappings>. Multiple mappings
684       can be configured there. A mapping has a condition and a target. Tntnet
685       looks  in  the list of mappings for the first mapping, where the condi‐
686       tion is met and uses that to call  the  component.  The  component  may
687       return  either  a  reply  - then the request is done or a special value
688       DECLINED, which tells tntnet to continue in the list and look  for  the
689       next mapping, where the condition is met.
690
691
692       The  component,  which returns DECLINED may already have generated part
693       of the request. This is preserved for the next mapping.  A  common  use
694       case  is  to write a special component, which just checks the user name
695       and password. If the user name  and  password  is  valid,  DECLINED  is
696       returned and tntnet calls the next mapping where the condition is met.
697
698
699       Also  when the condition is met, but the component could not be loaded,
700       tntnet continues with the next mapping.
701
702
703       When the end of the list is reached and  no  mapping  returned  a  http
704       reply code, tntnet replies with http not found (404) error.
705
706
707       So how these mapping are specified then?
708
709
710       The mapping contains 3 kind of nodes:
711
712
713       conditions
714         Multiple conditions can be specified. All conditions must be met when
715       the
716         mapping is to be used.
717
718
719       The most important is <url>, which contains a extended regular  expres‐
720       sion
721         (see  regex(7)  for  details). This expression is checked against the
722       url of the
723         request. If the url tag is omitted, the mapping  is  used  for  every
724       url.
725
726
727       The  condition  <vhost> specifies the virtual host, for which this map‐
728       ping is
729         valid. When  this  is  specified,  the  mapping  is  only  valid  for
730       requests, where
731         the  virtual  host  matches the setting. The value is also a extended
732       regular
733         expression. Note, that a dot matches any character in regular expres‐
734       sions,
735         which  may  be  irritating here. If you want to specify a mapping for
736       the all
737         hosts of the domain tntnet.org, you have to set
738         <vhost>tntnet\.org$</vhost>. Also the  dollar  sign  at  the  end  is
739       important,
740         since  it  matches the end of the string. Otherwise the mapping would
741       be also
742         valid for a virtual host like tntnet.org.foo.com, which  may  not  be
743       what you
744         meant.
745
746
747       The  condition  method  specifies the http method for which the mapping
748       should
749         be considered. Again a extended regular expression is used.
750
751
752       The condition ssl is a boolean value. The value should be 0 or 1. The
753         setting checks, whether this mapping should be used depending on ssl.
754       If the
755         value  is  1, the condition is met, when the request is sent via ssl.
756       If the
757         value is 0, the condition is met, when the request  is  sent  without
758       ssl.
759
760
761       target
762         The  mapping node contains a node <target>, which contains the compo‐
763       nent name,
764         which is to be called when the conditions are met.
765
766
767       The target may contain back references to the regular expression in the
768         <url> condition. Parts of the regular expression may be in  brackets.
769       In the
770         target  $1  is  replaced with the first bracketed expression, $2 with
771       the second
772         and so on.
773
774
775       This target node is mandatory.
776
777
778       Optionally there may be another node <httpreturn>, which specifies the
779         default http return code of components. The component may return with
780       the
781         special  constant  DEFAULT,  which  instructs  tntnet  to  return the
782       default http
783         return code for this mapping. The ecpp compiler generates components,
784       which
785         return exactly that value and the default value is HTTP_OK. The value
786       of the
787         node may be a numeric http return code or the  word  DECLINED,  which
788       instructs
789         tntnet to continue with the next mapping.
790
791
792       parameters
793         When the condition is met, additional parameters may be passed to the
794       called
795         component. There are 2 nodes for this.
796
797
798       The node <pathinfo> can be requested in the component using
799         request.getPathInfo(). If the node is not set, the url is set as path
800       info.
801
802
803       The  node <args> contains additional parameters, which can be passed to
804       the
805         component. The node can have any number of  nodes  with  values.  The
806       tags are
807         used as a parameter name and the content as the value. The method
808         request.getArg(name)  returns  the  value of the specified name. When
809       the
810         node is not set, the method returns  a  empty  string.  Optionally  a
811       diffrent
812         default  value can be passed to the method as an additional parameter
813       like
814         request.getArg(name,defaultValue).
815
816
817       For compatibility reasons with older tntnet  request.getArg  accepts  a
818       numeric
819         argument.  Previously  the  arguments  did  not  have  names but were
820       accessed by
821         index. To emulate this, request.getArg with a numeric argument trans‐
822       lates
823         the number into the name "argnumber". So accessing
824         request.getArg(2) returns the value of the argument with the name
825         arg2.  Accessing  a numeric argument equal or greater than the number
826       of
827         arguments (the first is number 0) used to be not allowed. Now a empty
828       string
829         is returned.
830
831
832       Example
833
834
835              <mappings>
836                <!-- map / to index@myapp -->
837                <mapping>
838                  <target>index@myapp</target>
839                  <url>^/$</url>
840                  <pathinfo>index.html</pathinfo>
841                </mapping>
842                <!-- map /comp.* or /comp to comp@myapp -->
843                <mapping>
844                  <target>action@myapp</target>
845                  <url></url>               <!-- any url -->
846                  <method>POST</method>     <!-- but only on method POST -->
847                  <vhost>localhost</vhost>  <!-- and host header must be localhost -->
848                  <ssl>1</ssl>              <!-- and ssl is enabled -->
849                </mapping>
850                <mapping>
851                  <target>$1@myapp</target>
852                  <url>^/([^.]+)(\.(.+))?</url>
853                  <args>
854                    <extension>$2</extension>
855                  </args>
856                </mapping>
857              </mappings>
858
859
860

LISTENERS

862       The  section  <listeners>  specifies  the ip addresses and ports, where
863       tntnet waits for incoming requests. Multiple listeners may be  defined,
864       when tntnet should listen on multiple ip addresses or ports.
865
866
867       Each  listener  is defined in a node <listener>. A listener must have a
868       subnode <port>. The node <ip> may contain a ip address or  hostname  or
869       may  be left empty or even omitted. If the node is empty, any interface
870       is used. The <port> must contain the numeric port number.
871
872
873       The ip address may be a IPv4 or IPv6 address.
874
875
876       Example
877
878
879              <listeners>
880                <listener>
881                  <port>80</port>
882                </listener>
883              </listeners>
884
885
886

SSL

888       Optionally a tag <certificate> may be added. This enables  ssl  on  the
889       interface and specifies the ssl host certificate for the interface.
890
891
892       The  ssl  key  can be stored in a separate file. A tag <key> specifies,
893       where to find it. It is really encouraged to do so and to remove  group
894       and other readability from the key file.
895
896
897       Example
898
899
900              <listeners>
901                <listener>
902                  <port>443</port>
903                  <!-- a certificate enables ssl -->
904                  <certificate>tntnet.pem</certificate>
905                  <key>tntnet.key</key>
906                </listener>
907              </listeners>
908
909
910
911       Client  certificates  are  supported.  The  tags  <sslCa> and <sslVeri‐
912       fyLevel> can be added to specify the type of check. If <sslVerifyLevel>
913       to  1,  a  client  certificate  is requested but tntnet accepts, if the
914       client sends no certificate.  The application can check the certificate
915       using  request.getSslCertificate().   It  returns a certificate object,
916       which may be empty.
917
918
919       If <sslVerifyLevel> is 2, a client certificate is mandatory. A  connec‐
920       tion without a certificate is not accepted.
921
922
923       In any case the client certificate is verified against the CA specified
924       by <sslCa>.
925
926
927       Example
928
929
930              <listeners>
931                <listener>
932                  <port>443</port>
933                  <certificate>tntnet.pem</certificate>
934                  <key>tntnet.key</key>
935                  <sslVerifyLevel>2</sslVerifyLevel>
936                  <sslCa>myCa.pem</sslCa>
937                </listener>
938              </listeners>
939
940
941
942       With this setting clients has to send a certificate signed  by  the  CA
943       myCa.pem.
944
945

LISTENER SETTINGS

947       We summarize the settings for the listeners here.
948
949
950       <ip>ip</ip>
951
952
953              Optional setting for the ip address where tntnet should listen on.
954
955
956
957       <port>port</port>
958
959
960              Mandatory setting on which tntnet should listen on.
961
962
963
964       <certificate>certificate</certificate>
965
966
967              A certificate file, which contains the ssl server certificate for ssl.
968
969
970
971       <key>key</key>
972
973
974              The private key for the server certificate. If the key is not specified,
975              tntnet expects the key in the certificate file.
976
977
978
979       <sslVerifyLevel>0|1|2</sslVerifyLevel>
980
981
982              Enables client certificates. When set to 0, no client certificate is needed.
983              When set to 1 a client certificate is requested but optional. It is just
984              passed to the application when available.
985              When set to 2 a client certificate is requested and needed to connect.
986
987
988
989       <sslCa>CA-file</sslCa>
990
991
992              The certificate authority the client certificate is checked against. Only
993              client certificates, which can be verified by this authority are accepted.
994              This settins is mandatory when `sslVerifyLevel` is set to 1 or 2.
995
996
997

LOGGING

999       Logging is configured in the <logging> section.
1000
1001
1002       Every  log output has a category and a level. Categories are hierarchi‐
1003       cal.
1004
1005
1006       The configuration tells which category is output  at  which  level  and
1007       where the output is written to.
1008
1009
1010       The  main  log  levels  are  in decreasing severity FATAL, ERROR, WARN,
1011       INFO, DEBUG, FINER, FINEST. The severity FINE is the same as  DEBUG.  A
1012       special level is TRACE.
1013
1014
1015       The settings are:
1016
1017
1018       <rootlogger>level</rootlogger>
1019
1020
1021              Sets the main level used, when nothing else is specified. The default is
1022              _FATAL_.
1023
1024
1025
1026       <loggers>loggers</loggers>
1027
1028
1029              Specifies the log levels for a category. See separate section about
1030              *loggers* for details.
1031
1032
1033
1034       <file>filename</file>
1035
1036
1037              Log output is written to file. Default is *stderr*.
1038
1039
1040
1041       <maxfilesize>size</maxfilesize>
1042
1043
1044              Specifies maximum _size_ of file. The size is a number in bytes or it can be
1045              prepended by a unit of 'k', 'm' or 'g', which specified kilo, mega or
1046              gigabytes. The unit is not case sensitive.
1047
1048              After reaching the size, a log message is written into the current file and
1049              renamed by appending a '.0' to it. A new file is then created.
1050
1051
1052
1053       <maxbackupindex>number</maxbackupindex>
1054
1055
1056              If the *maxfilesize* was reached and there is already a file with a *.0*
1057              extension it is renamed to .1. This happens up to the specified number. So
1058              if *maxfilesize* is e.g. 4 the log files are rolled up to .4, so that 5
1059              files are kept.
1060
1061
1062
1063       <logport>portnumber</logport>
1064
1065
1066              When a *portnumber* is specified and no *file* is specified (*file* has
1067              higher priority), log messages are sent to the specified udp port.
1068
1069
1070
1071       <loghost>host</loghost>
1072
1073
1074              When *logport* and *loghost are set, the messages are sent to the host.
1075
1076
1077
1078       <broadcast>boolean</broadcast>
1079
1080
1081              When the host address is a network address, the *broadcast* flag must be
1082              set. Then the messages are sent as broadcast udp messages to the network.
1083
1084              A boolean value is false when it is empty or starts with '0', 'f', 'F', 'n'
1085              or 'N'.
1086
1087
1088
1089       <stdout>boolean</stdout>
1090
1091
1092              When no file or loghost is set output and this flag is set, the output is
1093              written to *stdout*. The default is *stderr*.
1094
1095              A boolean value is false when it is empty or starts with '0', 'f', 'F', 'n'
1096              or 'N'.
1097
1098
1099
1100   loggers
1101       In  the section <loggers> a list of <logger> is specified. A logger has
1102       this settings:
1103
1104
1105       <category>category</category>
1106
1107
1108              Specifies the category
1109
1110
1111
1112       <level>level</level>
1113
1114
1115              Specifies the level for this category.
1116
1117              The level can be one of the log levels _FATAL_, _ERROR_, _WARN_, _INFO_,
1118              _DEBUG_, _FINE_, _FINER_ or _FINEST_. The all messages with a level of this
1119              or higher are output. So e.g. setting _DEBUG_ outputs all messages from
1120              _FATAL_ to _DEBUG_.
1121
1122              It is enough to specify the first character (except _FINE_, _FINER_ and
1123              _FINEST_).
1124
1125              Setting _TRACE_ (or _T_) is like _DEBUG_ plus all _TRACE_ messages. _TRACE_
1126              is special since it outputs a message when a the code is reached and a exit
1127              message when the scope of the code is exited. Typically the _TRACE_ messages
1128              are put at the start of functions so that the log shows when a function is
1129              called and when it is exited.
1130
1131              Multiple log levels can be separated by '|'. In that case only those levels
1132              are output. E.g. _WARN|DEBUG_ prints just warning and debug messages. When
1133              just one level should be printed, it can be prepended by '|', so e.g.
1134              _|ERROR_ prints just error messages.
1135
1136              Prepending a 'T' to the log level adds always traces. E.g. *TINFO* prints
1137              info messages and above and traces. _TFINEST_ prints just everything.
1138
1139
1140
1141       Note that all components has a automatic log category of component.name
1142       set.
1143
1144
1145   logger examples
1146              <loggers>
1147                  <logger>
1148                      <category>tntnet</category>
1149                      <level>DEBUG</level>
1150                  </logger>
1151              </loggers>
1152
1153
1154
1155       Prints much debug information when tntnet runs.
1156
1157
1158              <loggers>
1159                  <logger>
1160                      <category>tntnet.dispatcher</category>
1161                      <level>DEBUG</level>
1162                  </logger>
1163                  <logger>
1164                      <category>component</category>
1165                      <level>TRACE</level>
1166                  </logger>
1167              </loggers>
1168
1169
1170
1171       Prints  debug  messages about the processing of url mappings and traces
1172       about called (ecpp-)components.
1173
1174
1175       Other useful categories are tntnet.messageheader, which  outputs  debug
1176       messages  for  each  header  sent  from the client or tntnet.httpreply,
1177       where we can see the reply headers.
1178
1179

AUTHOR

1181       This manual page was written by Tommi Mäkitalo ⟨tommi@tntnet.org⟩.
1182
1183

SEE ALSO

1185       tntnet (1)
1186
1187
1188
1189Tntnet                            2006-07-23                     tntnet.xml(7)
Impressum