.TH tntnet.xml 7 "2006\-07\-23" Tntnet "Tntnet users guide"
.SH NAME
.PP
tntnet.xml \- configuration file for tntnet(8)

.SH DESCRIPTION
.PP
Tntnet is configured using a xml file. The name of the file is \fItntnet.xml\fP\&. The
root node of \fItntnet.xml\fP should be \fB\fCtntnet\fR while it is not checked. Most of
the settings are just single values. They are described here in alphabetical
order.

.SH SETTINGS
.PP
This section describes the variables, used by Tntnet (8).

.PP
\fB\fC<accessLog>\fR\fIfilename\fP\fB\fC</accessLog>\fR

.PP
Writes a log entry for each request in a common format. This format is
  compatible with most log file analyze systems for http servers.

.PP
The log file has the fields: \fB\fCpeer ip\fR \- \fB\fCusername\fR [\fB\fCtime\fR] "\fB\fChttp method\fR
  \fB\fCquery string\fR HTTP/\fB\fCmajor version\fR\&.\fB\fCminor version\fR" \fB\fChttp return code\fR
  \fB\fCcontent size\fR "\fB\fCreferer\fR" "\fB\fCuser agent\fR"

.PP
The \fB\fCusername\fR, \fB\fCreferer\fR and \fB\fCuser agent\fR may be '\-' when the value is not
  available. Also the \fB\fCcontent\-size\fR can be empty in some cases.

.PP
\fIExample\fP

.PP
.RS

.nf
<accessLog>/var/log/tntnet/access.log</accessLog

.fi
.RE

.PP
\fB\fC<bufferSize>\fR\fIbytes\fP\fB\fC</bufferSize>\fR

.PP
Specifies the number of bytes sent in a single system call. This does not
  limit anything in application level. It does not affect e.g. savepoints or
  exception handling. Component output is collected completely and then passed
  in chunks of \fB\fCbufferSize\fR bytes to the operating system.

.PP
The default value is 16384.

.PP
\fB\fC<compPath>\fR [ \fB\fC<entry>\fR\fIpath1\fP\fB\fC</entry>\fR ] \fB\fC</compPath>\fR

.PP
\fB\fCcomppath\fR specifies, where tntnet should search for webapplications. Tntnet
  searches first in the current directory and then in each directory, you
  specify here, until a library is found. You can repeat the directive as many
  times as desired to add more entries. If it is not found, the next
  \fB\fCmappings\fR entry is tried.

.PP
\fIExample\fP

.PP
.RS

.nf
<comppath>
  <entry>/usr/local/lib/tntnet</entry>
  <entry>/usr/local/share/tntnet</entry>
</comppath>

.fi
.RE

.PP
\fB\fC<chroot>\fR\fIdirectory\fP\fB\fC</chroot>\fR

.PP
Does a chroot(2) system call on startup, which locks the process into the
  directory at system level.

.PP
\fIExample\fP

.PP
.RS

.nf
<chroot>/var/tntnet</chroot>

.fi
.RE

.PP
\fB\fC<daemon>\fR\fI0|1\fP\fB\fC</daemon>\fR

.PP
If this flag is set to 1, Tntnet forks at startup and terminates the
  parent process on successful initialization.

.PP
\fB\fC<dir>\fR\fIdirectory\fP\fB\fC</dir>\fR

.PP
Changes the current working directory of the process on startup.

.PP
\fIExample\fP

.PP
.RS

.nf
<dir>/var/tntnet</dir>

.fi
.RE

.PP
\fB\fC<defaultContentType>\fR\fIcontentType\fP\fB\fC</defaultContentType>\fR

.PP
Sets the content type header of the reply. The content type may be changed in
  the application using \fB\fCreply.setContentType("something")\fR\&.

.PP
By default "text/html; charset=UTF\-8" is set.

.PP
\fIExample\fP

.PP
.RS

.nf
<defaultContentType>text/html; charset=ISO\-8858\-1</defaultContentType>

.fi
.RE

.PP
\fB\fC<enableCompression>\fR\fIyes|no\fP\fB\fC</enableCompression>\fR

.PP
Specifies, if Tntnet should use gzip compression at http level. By default
  Tntnet use compression. A http client like a web browser can send a header
  "Accept\-Encoding", to tell Tntnet, that it would accept compressed data.
  Tntnet then can decide, if it use compression. When the body is complete,
  Tntnet tries to compress the body. If the data can be compressed by more than
  10%, Tntnet sends this compressed data. With this flag, this feature can be
  turned off.

.PP
Compression slows down processing but reduces the network load. Normally the
  size of html pages can be compressed by about 70%, while Tntnet slows down by
  up to 30%.

.PP
\fIExample\fP

.PP
.RS

.nf
<enableCompression>no</enableCompression>

.fi
.RE

.PP
\fB\fC<environment>\fR \fB\fC<name1>\fR\fIvalue1\fP\fB\fC</name1>\fR \fB\fC<name2>\fR\fIvalue2\fP\fB\fC</name2>\fR \fB\fC</environment>\fR

.PP
Sets environment variables.

.PP
\fB\fC<errorLog>\fR\fIfilename\fP\fB\fC</errorLog>\fR

.PP
Redirects stderr to the specified file when tntnet runs as a daemon. If
  ErrorLog is not set stderr is redirected to /dev/null.

.PP
\fIExample\fP

.PP
.RS

.nf
<errorLog>/var/log/tntnet/error.log</errorLog>

.fi
.RE

.PP
\fB\fC<group>\fR\fIunix\-group\-id\fP\fB\fC</group>\fR

.PP
Changes the group under which tntnet runs.

.PP
The user is changes using the system call setgid(2), which is only allowed,
  when tntnet starts as root user.

.PP
\fIExample\fP

.PP
.RS

.nf
<group>tntnet\-group</group>

.fi
.RE

.PP
\fB\fC<keepAliveTimeout>\fR\fImilliseconds\fP\fB\fC</keepAliveTimeout>\fR

.PP
Sets the timeout for keep\-alive requests.

.PP
Tntnet tries to do keep\-alive\-requests wherever possible. This has the effect,
  that tntnet can receive multiple requests within a single tcp connection. The
  connection times out after KeepAliveTimeout milliseconds. The timeout defaults
  to 15000ms.

.PP
\fIExample\fP

.PP
.RS

.nf
<keepAliveTimeout>300000</keepAliveTimeout>

.fi
.RE

.PP
\fB\fC<keepAliveMax>\fR\fInumber\fP\fB\fC</keepAliveMax>\fR

.PP
Sets the maximum number of request per tcp connection. This defaults to 100.

.PP
\fIExample\fP

.PP
.RS

.nf
<keepAliveTimeout>10</keepAliveTimeout>

.fi
.RE

.PP
\fB\fC<listeners>\fR\fIlistener definition\fP\fB\fC</listeners>\fR

.PP
Specifies, on which local interfaces tntnet waits for connections. There can
  be more than one Listen directives, in which case tntnet waits on every
  address.

.PP
See separate section \fIListeners\fP

.PP
\fB\fC<logging>\fR\fIlogger definition\fP\fB\fC</logging>\fR

.PP
Configures logging. See separate section \fIlogging\fP

.PP
\fB\fC<listenRetry>\fR\fInumber\fP\fB\fC</listenRetry>\fR

.PP
On startup Tntnet calls listen on the specified port. When the systemcall
  returns with an error, Tntnet tries again and fails after the specified number
  of attempts.

.PP
The default number is 5.

.PP
\fIExample\fP

.PP
.RS

.nf
<listenRetry>10</listenRetry>

.fi
.RE

.PP
\fB\fC<listenBacklog>\fR\fInumber\fP\fB\fC</listenBacklog>\fR

.PP
The system call listen(3p) needs a parameter backlog, which specifies, how
  many pending connections the operating system should queue before it starts to
  ignore new request. The value is configurable here.

.PP
The default value is 16.

.PP
\fIExample\fP

.PP
.RS

.nf
<ListenBacklog>64</ListenBacklog>

.fi
.RE

.PP
\fB\fC<mappings>\fR\fIurlmappings\fP\fB\fC</mappings>\fR

.PP
This is the most important setting for tntnet. It specifies, which components
  schould be called on which urls.

.PP
For details see the section \fIURL MAPPING\fP\&.

.PP
\fB\fC<maxUrlMapCache>\fR\fInumber\fP\fB\fC</maxUrlMapCache>\fR

.PP
Mapping urls to components is done using regular expressions. Executing these
  expressions is quite expensive while the number of different urls is quite
  limited in typical web applications. Hence tntnet caches the results.

.PP
The caching algorithm is very simple. Tntnet just collects the results in a
  map. When the maximum size of the list is reached, it is cleared. This makes
  management of the cache very cheap.

.PP
This setting sets the maximum number of entries in the map.

.PP
If you see frequently a warning message, that the cache is cleared, you may
  consider increasing the size.

.PP
The default value is 8192.

.PP
\fIExample\fP

.PP
.RS

.nf
<maxUrlMapCache>32768</maxUrlMapCache>

.fi
.RE

.PP
\fB\fC<maxRequestSize>\fR\fInumber\fP\fB\fC</maxRequestSize>\fR

.PP
This directive limits the size of the request. After \fInumber\fP Bytes the
  connection is just closed. This prevents denial of service attacks through
  long requests. Every request is read into memory, so it must fit into it.
  Bear in mind, that if you use file upload fields a request might be larger
  than just a few bytes.

.PP
The value defaults to 0, which means, that there is no limit at all.

.PP
\fIExample\fP

.PP
.RS

.nf
<maxRequestSize>65536</maxRequestSize>

.fi
.RE

.PP
\fB\fC<maxRequestTime>\fR\fIseconds\fP\fB\fC</maxRequestTime>\fR

.PP
In daemon mode tntnet has a watchdog, which restarts tntnet when the maximum
  request time is exceeded. This happens, when a request is in a endless loop or
  otherwise hangs. Restarting tntnet looses all active sessions and the
  currently running requests. Therefore the timeout should be well long enough
  for the longes request.

.PP
The default value is 600 seconds, which is normally much longer than a http
  request should run. If the Timeout is set to 0, the watchdog is deactivated.

.PP
\fIExample\fP

.PP
.RS

.nf
<maxRequestTime>1200</maxRequestTime>

.fi
.RE

.PP
\fB\fC<minThreads>\fR\fInumber\fP\fB\fC</minThreads>\fR

.PP
Tntnet uses a dynamic pool of worker threads, which wait for incoming
  requests. MinThreads specifies, how many worker threads there have to be. This
  defaults to 5.

.PP
\fIExample\fP

.PP
.RS

.nf
<minThreads>10</minThreads>

.fi
.RE

.PP
\fB\fC<minCompressSize>\fR\fInumber\fP\fB\fC</minCompressSize>\fR

.PP
Http compression for replies smaller than this are not compressed at all.

.PP
The default value for this is 1024.

.PP
\fIExample\fP

.PP
.RS

.nf
<minCompressSize>256</minCompressSize>

.fi
.RE

.PP
\fB\fC<mimeDb>\fR\fIfilename\fP\fB\fC</mimeDb>\fR

.PP
Specify filename for mime db. The default is /etc/mime.types.

.PP
The format of the file is just like this /etc/mime.types. A mime type is
  followed after white space by a list of file extensions delimited by white
  space.

.PP
\fB\fC<maxThreads>\fR\fInumber\fP\fB\fC</maxThreads>\fR

.PP
Tntnet uses a dynamic pool of worker threads, which wait for incoming
  requests. \fB\fCmaxThreads\fR limits the number of threads.

.PP
The default is 100.

.PP
\fIExample\fP

.PP
.RS

.nf
<maxThreads>200</maxThreads>

.fi
.RE

.PP
\fB\fC<pidfile>\fR\fIfilename\fP\fB\fC</pidfile>\fR

.PP
When run in daemon mode, tntnet writes the process id of the monitor process
  to filename. When the monitor process is deactivated, the pid of the
  worker process is written. This ensures, that sending a sigkill to the the
  stored process id stops tntnet.

.PP
\fIExample\fP

.PP
.RS

.nf
<pidfile>/var/run/tntnet.pid</pidfile>

.fi
.RE

.PP
\fB\fC<queueSize>\fR\fInumber\fP\fB\fC</queueSize>\fR

.PP
Tntnet has a request queue, where new requests wait for service. This sets a
  maximum size of this queue, after which new requests are not accepted.

.PP
The default value is 1000.

.PP
\fIExample\fP

.PP
.RS

.nf
<queueSize>50</queueSize>

.fi
.RE

.PP
\fB\fC<reuseAddress>\fR\fI0|1\fP\fB\fC</reuseAddress>\fR

.PP
The flag specifies whether the socket option SO\_REUSEADDR should be set.
  When the entry is omitted the flag is set.

.PP
\fB\fC<server>\fR\fIname\fP\fB\fC</server>\fR

.PP
Set the server response header. Tntnet sets the http header "Server:" to
  "Tntnet/version" by default. With this setting the header can be changed.

.PP
\fIExample\fP

.PP
.RS

.nf
<server>Myserver version 1.2</server>

.fi
.RE

.PP
\fB\fC<sessionTimeout>\fR\fIseconds\fP\fB\fC</sessionTimeout>\fR

.PP
This sets the number of seconds without requests after which a session is
  timed out.

.PP
The default value is 300 seconds.

.PP
\fIExample\fP

.PP
.RS

.nf
<sessionTimeout>600</sessionTimeout>

.fi
.RE

.PP
\fB\fC<socketReadTimeout>\fR\fImilliseconds\fP\fB\fC</socketReadTimeout>\fR

.PP
A worker thread waits for some milliseconds on incoming data. If there is no
  data, the job is put into a queue and another thread waits with poll(2) on
  incoming data on multiple sockets. The workerthreads are freed and they can
  respond to other requests quickly. The default value is 10 milliseconds, which
  is good for normal operation. A value of 0 results in non blocking read. If
  timeout is reached, this does not mean, that the socket is closed. A small
  timeout reduces contextswitches on slow connections.

.PP
\fIExample\fP

.PP
.RS

.nf
<socketReadTimeout>0</socketReadTimeout>

.fi
.RE

.PP
\fB\fC<socketWriteTimeout>\fR\fImilliseconds\fP\fB\fC</socketWriteTimeout>\fR

.PP
This defines the time, how long the workerthreads wait on write.  If the
  timeout is exceeded, the socket is closed and the browser might not get all
  data.  The default value is 10000 milliseconds.

.PP
\fIExample\fP

.PP
.RS

.nf
<socketWriteTimeout>20000</socketWriteTimeout>

.fi
.RE

.PP
\fB\fC<threadStartDelay>\fR\fIms\fP\fB\fC</threadStartDelay>\fR

.PP
When additional worker threads are needed tntnet waits the number of
  milliseconds before it starts additional threads to prevent high load when
  starting many threads at once.

.PP
The default value is 10ms.

.PP
\fIExample\fP

.PP
.RS

.nf
<threadStartDelay>1000</threadStartDelay>

.fi
.RE

.PP
\fB\fC<user>\fR\fIusername\fP\fB\fC</user>\fR

.PP
Changes the user under which tntnet answers requests.

.PP
The user is changes using the system call setuid(2), which is only allowed,
  when tntnet starts as root user.

.PP
\fIExample\fP

.PP
.RS

.nf
<user>www\-data</user>

.fi
.RE

.PP
\fB\fC<virtualhosts> { <virtualhost> <hostname>\fR\fIhostname\-regex\fP\fB\fC</hostname>\fR\fImappings\fP\fB\fC</virtualhost> }</virtualhosts>\fR

.PP
Defines mappings for virtual hosts. These mappings are valid only when the
  host header matches the \fIhostname\-regex\fP\&. See section \fIURL MAPPING\fP for
  details about how to define actual mappings

.PP
A \fIvhost\fP entry in the mappings should be empty since it is already specified
  for the whole group.

.PP
The mappings defined here are always matched before the mappings on the top
  level of the configuration.

.PP
\fIExample\fP

.PP
.RS

.nf
<virtualhosts>
  <virtualhost>
    <hostname>www\\.tntnet\\.org</hostname>
    <mappings>
      <mapping>
        <url>^/$</url>
        <target>static@tntent</target>
        <pathinfo>htdocs/index.html</pathinfo>
      </mapping>
      <mapping>
        <url>^/(.*)$</url>
        <target>static@tntent</target>
        <pathinfo>htdocs/$1</pathinfo>
      </mapping>
    </mappings>
  </virtualhost>
</virtualhosts>

.fi
.RE

.SH URL MAPPING
.PP
Tntnet is a web server, which receives http requests from a http client and
answers them. A http request has a url and other attributes, which are used to
decide, how the answer should look like. This is done my mapping urls to components.

.PP
A component is something, which generates a http reply. They are normally
generated with the ecpp compiler ecppc(1). The ecppc compiler generated C++
classes with component names. The classes are compiled and linked into a shared
library. Both the component name and the shared library name is needed to
identify a component.

.PP
The component identifier is a string built from the component name, the @
character and the shared library name. A example is \fB\fCmyclass@myapplication\fR\&.
This tells tntnet: load shared library \fB\fCmyapplication\fR and call the component
with the name \fB\fCmyclass\fR in that library, which creates the reply to the request.

.PP
To tell tntnet, which component to call, url mappings must be configured.

.PP
Configuration is done in the xml section \fB\fC<mappings>\fR\&. Multiple mappings can be
configured there. A mapping has a condition and a target. Tntnet looks in the
list of mappings for the first mapping, where the condition is met and uses that
to call the component. The component may return either a reply \- then the
request is done or a special value \fB\fCDECLINED\fR, which tells tntnet to continue in
the list and look for the next mapping, where the condition is met.

.PP
The component, which returns \fB\fCDECLINED\fR may already have generated part of the
request. This is preserved for the next mapping. A common use case is to write a
special component, which just checks the user name and password. If the user
name and password is valid, \fB\fCDECLINED\fR is returned and tntnet calls the next
mapping where the condition is met.

.PP
Also when the condition is met, but the component could not be loaded, tntnet
continues with the next mapping.

.PP
When the end of the list is reached and no mapping returned a http reply code,
tntnet replies with http not found (404) error.

.PP
So how these mapping are specified then?

.PP
The mapping contains 3 kind of nodes:

.PP
\fB\fCconditions\fR
  Multiple conditions can be specified. All conditions must be met when the
  mapping is to be used.

.PP
The most important is \fB\fC<url>\fR, which contains a extended regular expression
  (see regex(7) for details). This expression is checked against the url of the
  request. If the url tag is omitted, the mapping is used for every url.

.PP
The condition \fB\fC<vhost>\fR specifies the virtual host, for which this mapping is
  valid. When this is specified, the mapping is only valid for requests, where
  the virtual host matches the setting. The value is also a extended regular
  expression. Note, that a dot matches any character in regular expressions,
  which may be irritating here. If you want to specify a mapping for the all
  hosts of the domain \fB\fCtntnet.org\fR, you have to set
  \fB\fC<vhost>tntnet\\.org$</vhost>\fR\&. Also the dollar sign at the end is important,
  since it matches the end of the string. Otherwise the mapping would be also
  valid for a virtual host like \fB\fCtntnet.org.foo.com\fR, which may not be what you
  meant.

.PP
The condition \fB\fCmethod\fR specifies the http method for which the mapping should
  be considered. Again a extended regular expression is used.

.PP
The condition \fB\fCssl\fR is a boolean value. The value should be 0 or 1. The
  setting checks, whether this mapping should be used depending on ssl.  If the
  value is 1, the condition is met, when the request is sent via ssl. If the
  value is 0, the condition is met, when the request is sent without ssl.

.PP
\fB\fCtarget\fR
  The mapping node contains a node \fB\fC<target>\fR, which contains the component name,
  which is to be called when the conditions are met.

.PP
The target may contain back references to the regular expression in the
  \fB\fC<url>\fR condition. Parts of the regular expression may be in brackets. In the
  target $1 is replaced with the first bracketed expression, $2 with the second
  and so on.

.PP
This target node is mandatory.

.PP
Optionally there may be another node \fB\fC<httpreturn>\fR, which specifies the
  default http return code of components. The component may return with the
  special constant DEFAULT, which instructs tntnet to return the default http
  return code for this mapping. The ecpp compiler generates components, which
  return exactly that value and the default value is HTTP\_OK. The value of the
  node may be a numeric http return code or the word DECLINED, which instructs
  tntnet to continue with the next mapping.

.PP
\fB\fCparameters\fR
  When the condition is met, additional parameters may be passed to the called
  component. There are 2 nodes for this.

.PP
The node \fB\fC<pathinfo>\fR can be requested in the component using
  \fB\fCrequest.getPathInfo()\fR\&. If the node is not set, the url is set as path info.

.PP
The node \fB\fC<args>\fR contains additional parameters, which can be passed to the
  component. The node can have any number of nodes with values. The tags are
  used as a parameter name and the content as the value. The method
  \fB\fCrequest.getArg(\fR\fIname\fP\fB\fC)\fR returns the value of the specified \fIname\fP\&. When the
  node is not set, the method returns a empty string. Optionally a different
  default value can be passed to the method as an additional parameter like
  \fB\fCrequest.getArg(\fR\fIname\fP\fB\fC,\fR\fIdefaultValue\fP\fB\fC)\fR\&.

.PP
For compatibility reasons with older tntnet \fB\fCrequest.getArg\fR accepts a numeric
  argument. Previously the arguments did not have names but were accessed by
  index. To emulate this, \fB\fCrequest.getArg\fR with a numeric argument translates
  the number into the name "\fB\fCarg\fR\fInumber\fP". So accessing
  \fB\fCrequest.getArg(\fR\fI2\fP\fB\fC)\fR returns the value of the argument with the name
  \fB\fCarg2\fR\&. Accessing a numeric argument equal or greater than the number of
  arguments (the first is number 0) used to be not allowed. Now a empty string
  is returned.

.PP
\fIExample\fP

.PP
.RS

.nf
<mappings>
  <!\-\- map / to index@myapp \-\->
  <mapping>
    <target>index@myapp</target>
    <url>^/$</url>
    <pathinfo>index.html</pathinfo>
  </mapping>
  <!\-\- map /comp.* or /comp to comp@myapp \-\->
  <mapping>
    <target>action@myapp</target>
    <url></url>               <!\-\- any url \-\->
    <method>POST</method>     <!\-\- but only on method POST \-\->
    <vhost>localhost</vhost>  <!\-\- and host header must be localhost \-\->
    <ssl>1</ssl>              <!\-\- and ssl is enabled \-\->
  </mapping>
  <mapping>
    <target>$1@myapp</target>
    <url>^/([^.]+)(\\.(.+))?</url>
    <args>
      <extension>$2</extension>
    </args>
  </mapping>
</mappings>

.fi
.RE

.SH LISTENERS
.PP
The section \fB\fC<listeners>\fR specifies the ip addresses and ports, where tntnet
waits for incoming requests. Multiple listeners may be defined, when tntnet
should listen on multiple ip addresses or ports.

.PP
Each listener is defined in a node \fB\fC<listener>\fR\&. A listener must have a subnode
\fB\fC<port>\fR\&. The node \fB\fC<ip>\fR may contain a ip address or hostname or may be left
empty or even omitted. If the node is empty, any interface is used. The \fB\fC<port>\fR
must contain the numeric port number.

.PP
The ip address may be a IPv4 or IPv6 address.

.PP
\fIExample\fP

.PP
.RS

.nf
<listeners>
  <listener>
    <port>80</port>
  </listener>
</listeners>

.fi
.RE

.SH SSL
.PP
Optionally a tag \fB\fC<certificate>\fR may be added. This enables ssl on the interface
and specifies the ssl host certificate for the interface.

.PP
The ssl key can be stored in a separate file. A tag \fB\fC<key>\fR specifies, where to
find it. It is really encouraged to do so and to remove group and other
readability from the key file.

.PP
\fIExample\fP

.PP
.RS

.nf
<listeners>
  <listener>
    <port>443</port>
    <!\-\- a certificate enables ssl \-\->
    <certificate>tntnet.pem</certificate>
    <key>tntnet.key</key>
  </listener>
</listeners>

.fi
.RE

.PP
Client certificates are supported. The tags \fB\fC<sslCa>\fR and \fB\fC<sslVerifyLevel>\fR can
be added to specify the type of check. If \fB\fC<sslVerifyLevel>\fR to \fB\fC1\fR, a client
certificate is requested but tntnet accepts, if the client sends no certificate.
The application can check the certificate using \fB\fCrequest.getSslCertificate()\fR\&.
It returns a certificate object, which may be empty.

.PP
If \fB\fC<sslVerifyLevel>\fR is \fB\fC2\fR, a client certificate is mandatory. A connection
without a certificate is not accepted.

.PP
In any case the client certificate is verified against the CA specified by
\fB\fC<sslCa>\fR\&.

.PP
\fIExample\fP

.PP
.RS

.nf
<listeners>
  <listener>
    <port>443</port>
    <certificate>tntnet.pem</certificate>
    <key>tntnet.key</key>
    <sslVerifyLevel>2</sslVerifyLevel>
    <sslCa>myCa.pem</sslCa>
  </listener>
</listeners>

.fi
.RE

.PP
With this setting clients has to send a certificate signed by the CA \fB\fCmyCa.pem\fR\&.

.SH LISTENER SETTINGS
.PP
We summarize the settings for the listeners here.

.PP
\fB\fC<ip>\fR\fIip\fP\fB\fC</ip>\fR

.PP
.RS

.nf
Optional setting for the ip address where tntnet should listen on.

.fi
.RE

.PP
\fB\fC<port>\fR\fIport\fP\fB\fC</port>\fR

.PP
.RS

.nf
Mandatory setting on which tntnet should listen on.

.fi
.RE

.PP
\fB\fC<certificate>\fR\fIcertificate\fP\fB\fC</certificate>\fR

.PP
.RS

.nf
A certificate file, which contains the ssl server certificate for ssl.

.fi
.RE

.PP
\fB\fC<key>\fR\fIkey\fP\fB\fC</key>\fR

.PP
.RS

.nf
The private key for the server certificate. If the key is not specified,
tntnet expects the key in the certificate file.

.fi
.RE

.PP
\fB\fC<sslVerifyLevel>\fR\fI0|1|2\fP\fB\fC</sslVerifyLevel>\fR

.PP
.RS

.nf
Enables client certificates. When set to 0, no client certificate is needed.
When set to 1 a client certificate is requested but optional. It is just
passed to the application when available.
When set to 2 a client certificate is requested and needed to connect.

.fi
.RE

.PP
\fB\fC<sslCa>\fR\fICA\-file\fP\fB\fC</sslCa>\fR

.PP
.RS

.nf
The certificate authority the client certificate is checked against. Only
client certificates, which can be verified by this authority are accepted.
This settins is mandatory when `sslVerifyLevel` is set to 1 or 2.

.fi
.RE

.SH LOGGING
.PP
Logging is configured in the \fB\fC<logging>\fR section.

.PP
Every log output has a category and a level. Categories are hierarchical.

.PP
The configuration tells which category is output at which level and where the
output is written to.

.PP
The main log levels are in decreasing severity \fIFATAL\fP, \fIERROR\fP, \fIWARN\fP, \fIINFO\fP,
\fIDEBUG\fP, \fIFINER\fP, \fIFINEST\fP\&. The severity \fIFINE\fP is the same as \fIDEBUG\fP\&. A
special level is \fITRACE\fP\&.

.PP
The settings are:

.PP
\fB\fC<rootlogger>\fR\fIlevel\fP\fB\fC</rootlogger>\fR

.PP
.RS

.nf
Sets the main level used, when nothing else is specified. The default is
\_FATAL\_.

.fi
.RE

.PP
\fB\fC<loggers>\fR\fIloggers\fP\fB\fC</loggers>\fR

.PP
.RS

.nf
Specifies the log levels for a category. See separate section about
*loggers* for details.

.fi
.RE

.PP
\fB\fC<file>\fR\fIfilename\fP\fB\fC</file>\fR

.PP
.RS

.nf
Log output is written to file. Default is *stderr*.

.fi
.RE

.PP
\fB\fC<maxfilesize>\fR\fIsize\fP\fB\fC</maxfilesize>\fR

.PP
.RS

.nf
Specifies maximum \_size\_ of file. The size is a number in bytes or it can be
prepended by a unit of 'k', 'm' or 'g', which specified kilo, mega or
gigabytes. The unit is not case sensitive.

After reaching the size, a log message is written into the current file and
renamed by appending a '.0' to it. A new file is then created.

.fi
.RE

.PP
\fB\fC<maxbackupindex>\fR\fInumber\fP\fB\fC</maxbackupindex>\fR

.PP
.RS

.nf
If the *maxfilesize* was reached and there is already a file with a *.0*
extension it is renamed to .1. This happens up to the specified number. So
if *maxfilesize* is e.g. 4 the log files are rolled up to .4, so that 5
files are kept.

.fi
.RE

.PP
\fB\fC<logport>\fR\fIportnumber\fP\fB\fC</logport>\fR

.PP
.RS

.nf
When a *portnumber* is specified and no *file* is specified (*file* has
higher priority), log messages are sent to the specified udp port.

.fi
.RE

.PP
\fB\fC<loghost>\fR\fIhost\fP\fB\fC</loghost>\fR

.PP
.RS

.nf
When *logport* and *loghost are set, the messages are sent to the host.

.fi
.RE

.PP
\fB\fC<broadcast>\fR\fIboolean\fP\fB\fC</broadcast>\fR

.PP
.RS

.nf
When the host address is a network address, the *broadcast* flag must be
set. Then the messages are sent as broadcast udp messages to the network.

A boolean value is false when it is empty or starts with '0', 'f', 'F', 'n'
or 'N'.

.fi
.RE

.PP
\fB\fC<stdout>\fR\fIboolean\fP\fB\fC</stdout>\fR

.PP
.RS

.nf
When no file or loghost is set output and this flag is set, the output is
written to *stdout*. The default is *stderr*.

A boolean value is false when it is empty or starts with '0', 'f', 'F', 'n'
or 'N'.

.fi
.RE

.SS loggers
.PP
In the section \fB\fC<loggers>\fR a list of \fB\fC<logger>\fR is specified. A logger has this
settings:

.PP
\fB\fC<category>\fR\fIcategory\fP\fB\fC</category>\fR

.PP
.RS

.nf
Specifies the category

.fi
.RE

.PP
\fB\fC<level>\fR\fIlevel\fP\fB\fC</level>\fR

.PP
.RS

.nf
Specifies the level for this category.

The level can be one of the log levels \_FATAL\_, \_ERROR\_, \_WARN\_, \_INFO\_,
\_DEBUG\_, \_FINE\_, \_FINER\_ or \_FINEST\_. The all messages with a level of this
or higher are output. So e.g. setting \_DEBUG\_ outputs all messages from
\_FATAL\_ to \_DEBUG\_.

It is enough to specify the first character (except \_FINE\_, \_FINER\_ and
\_FINEST\_).

Setting \_TRACE\_ (or \_T\_) is like \_DEBUG\_ plus all \_TRACE\_ messages. \_TRACE\_
is special since it outputs a message when a the code is reached and a exit
message when the scope of the code is exited. Typically the \_TRACE\_ messages
are put at the start of functions so that the log shows when a function is
called and when it is exited.

Multiple log levels can be separated by '|'. In that case only those levels
are output. E.g. \_WARN|DEBUG\_ prints just warning and debug messages. When
just one level should be printed, it can be prepended by '|', so e.g.
\_|ERROR\_ prints just error messages.

Prepending a 'T' to the log level adds always traces. E.g. *TINFO* prints
info messages and above and traces. \_TFINEST\_ prints just everything.

.fi
.RE

.PP
Note that all components has a automatic log category of \fIcomponent.\fIname\fP\fP set.

.SS logger examples
.PP
.RS

.nf
<loggers>
    <logger>
        <category>tntnet</category>
        <level>DEBUG</level>
    </logger>
</loggers>

.fi
.RE

.PP
Prints much debug information when tntnet runs.

.PP
.RS

.nf
<loggers>
    <logger>
        <category>tntnet.dispatcher</category>
        <level>DEBUG</level>
    </logger>
    <logger>
        <category>component</category>
        <level>TRACE</level>
    </logger>
</loggers>

.fi
.RE

.PP
Prints debug messages about the processing of url mappings and traces about
called (ecpp\-)components.

.PP
Other useful categories are \fItntnet.messageheader\fP, which outputs debug messages
for each header sent from the client or \fItntnet.httpreply\fP, where we can see the
reply headers.

.SH AUTHOR
.PP
This manual page was written by Tommi Mäkitalo 
\[la]tommi@tntnet.org\[ra]\&.

.SH SEE ALSO
.PP
tntnet (1)