Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
tntnet.xml(8)		      Tntnet users guide		 tntnet.xml(8)

NAME
       tntnet.xml - configuration file for tntnet(8)

DESCRIPTION
       Tntnet  is  configured  using  a	xml file. The name of the file is tnt-
       net.xml.	The root node of tntnet.xml should be tntnet while it  is  not
       checked.	 Most  of  the	settings  are just single values. They are de-
       scribed here in alphabetical order.

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

       <accessLog>filename</accessLog>
	      Writes a log entry for each request in  a	 common	 format.  This
	      format is	compatible with	most log file analyze systems for http
	      servers.

	      The log file has the fields: peer-ip -  username	[time]	"http-
	      method  query-string  HTTP/major-version.minor-version" http-re-
	      turn-code	content-size "referer" "user-agent"

	      The username, referer and	user-agent may be '-' when  the	 value
	      is  not  available.  Also	 the content-size can be empty in some
	      cases.

	      Example

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

       <bufferSize>bytes</bufferSize>

	      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  col-
	      lected  completely and then passed in chunks of bufferSize bytes
	      to the operating system.

	      The default value	is 16384.

       <comppath> [ <entry>path1</entry> ] </comppath>

	      comppath specifies, where	tntnet should search  for  webapplica-
	      tions.  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  mappings  entry  is
	      tried.

	      Example

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

       <chroot>directory</chroot>

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

	      Example

	      <chroot>/var/tntnet</chroot>

       <daemon>0|1</daemon>

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

       <dir>directory</dir>

	      Changes the current working directory of the process on startup.

	      Example

	      <dir>/var/tntnet</dir>

       <enableCompression>yes|no</enableCompression>

	      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.

	      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%.

	      Example

	      <enableCompression>no</enableCompression>

       <errorLog>filename</errorLog>

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

	      Example

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

       <group>unix-group-id</group>

	      Changes the group	under which tntnet runs.

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

	      Example

	      <group>tntnet-group</group>

       <keepAliveTimeout>milliseconds</keepAliveTimeout>

	      Sets the timeout for keep-alive requests.

	      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.

	      Example

	      <keepAliveTimeout>300000</keepAliveTimeout>

       <keepAliveMax>number</keepAliveMax>

	      Sets the maximum number of request per tcp-connection. This  de-
	      faults to	100.

	      Example

	      <keepAliveTimeout>10</keepAliveTimeout>

       <listeners>listener definition</listeners>

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

	      See separate section Listeners

       <logging>listener definition</logging>

	      Configures logging. See separate section logging

       <listenRetry>number</listenRetry>

	      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.

	      The default number is 5.

	      Example

	      <listenRetry>10</listenRetry>

       <listenBacklog>number</listenBacklog>

	      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.

	      The default value	is 16.

	      Example

	      <ListenBacklog>64</ListenBacklog>

       <mappings>urlmappings</mappings>

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

	      For details see the section Url mapping.

       <maxUrlMapCache>number</maxUrlMapCache>

	      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.

	      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.

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

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

	      The default value	is 8192.

	      Example

	      <maxUrlMapCache>32768</maxUrlMapCache>

       <maxRequestSize>number</maxRequestSize>

	      This  directive  limits  the  size  of the request. After	number
	      Bytes  the  connection  is  just	closed.	 This	prevents   de-
	      nial-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.

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

	      Example

	      <maxRequestSize>65536</maxRequestSize>

       <maxRequestTime>seconds</maxRequestTime>

	      In daemon	mode tntnet has	a watchdog, which restarts tntnet when
	      the maximum request time is exceeded. This happens, when	a  re-
	      quest 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.

	      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.

	      Example

	      <maxRequestTime>1200</maxRequestTime>

       <minThreads>number</minThreads>

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

	      Example

	      <minThreads>10</minThreads>

       <minCompressSize>number</minCompressSize>

	      Http-compression for replies smaller  than  this	are  not  com-
	      pressed at all.

	      The default value	for this is 1024.

	      Example

	      <minCompressSize>256</minCompressSize>

       <mimeDb>filename</mimeDb>

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

	      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.

       <maxThreads>number</maxThreads>

	      Tntnet uses a dynamic pool of worker-threads, which wait for in-
	      coming requests. maxThreads limits the number of threads.

	      The default is 100.

	      Example

	      <maxThreads>200</maxThreads>

       <pidFile>filename</pidFile>

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

	      Example

	      <pidFile>/var/run/tntnet.pid</pidFile>

       <queueSize>number</queueSize>

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

	      The default value	is 1000.

	      Example

	      <queueSize>50</queueSize>

       <sessionTimeout>seconds</sessionTimeout>

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

	      The default value	is 300 seconds.

	      Example

	      <sessionTimeout>600</sessionTimeout>

       <socketReadTimeout>milliseconds</socketReadTimeout>

	      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  connec-
	      tions.

	      Example

	      <socketReadTimeout>0</socketReadTimeout>

       <socketWriteTimeout>milliseconds</socketWriteTimeout>

	      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 millisec-
	      onds.

	      Example

	      <socketWriteTimeout>20000</socketWriteTimeout>

       <threadStartDelay>ms</threadStartDelay>

	      When additional worker threads are needed	tntnet waits the  num-
	      ber  of milliseconds before it starts additional threads to pre-
	      vent high	load when starting many	threads	at once.

	      The default value	is 10ms.

	      Example

	      <threadStartDelay>1000</threadStartDelay>

       <user>username</user>

	      Changes the user under which tntnet answers requests.

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

	      Example

	      <user>www-data</user>

URL MAPPING
       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.

       A component is something, which generates a http	reply. They  are  nor-
       mally  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.

       The component identifier	is a string built from the component name, the
       @  character and	the shared library name. A example is myclass@myappli-
       cation.	This tells tntnet: load	shared library myapplication and  call
       the  component with the name myclass in that library, which creates the
       reply to	the request.

       To tell tntnet, which component to call,	url mappings must  be  config-
       ured.

       Configuration  is done in the xml section <mappings>. 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	condi-
       tion is met and uses that to call the component.	The component may  re-
       turn  either  a reply - then the	request	is done	or a special value DE-
       CLINED, which tells tntnet to continue in the list  and	look  for  the
       next mapping, where the condition is met.

       The  component,	which returns DECLINED 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, DECLINED  is  re-
       turned and tntnet calls the next	mapping	where the condition is met.

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

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

       So how these mapping are	specified then?

       The mapping contains 3 kind of nodes:

       conditions
	      Multiple conditions can be specified. All	conditions must	be met
	      when the mapping is to be	used.

	      The most important is <url>, 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	 omit-
	      ted, the mapping is used for every url.

	      The condition <vhost> 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  tntnet.org,  you have to set <vhost>tnt-
	      net\.org$</vhost>. 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  tntnet.org.foo.com,
	      which may	not be what you	meant.

	      The  condition  method  specifies	 the http method for which the
	      mapping should be	considered. Again a extended  regular  expres-
	      sion is used.

	      The  condition  ssl is a boolean value. The value	should be 0 or
	      1. The setting checks, whether this mapping should be  used  de-
	      pending  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.

       target The  mapping  node  contains a node <target>, which contains the
	      component	name, which is to be called when  the  conditions  are
	      met.

	      The target may contain back references to	the regular expression
	      in the <url> condition. Parts of the regular expression  may  be
	      in  brackets. In the target $1 is	replaced with the first	brack-
	      eted expression, $2 with the second and so on.

	      This node	is mandatory.

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

	      The  node	<pathinfo> can be requested in the component using re-
	      quest.getPathInfo(). If the node is not set, the url is  set  as
	      path info.

	      The  node	 <args>	 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 con-
	      tent as the value. The method request.getArg(name)  returns  the
	      value  of	 the  specified	 name.	When  the node is not set, the
	      method returns a empty string.  Optionally  a  diffrent  default
	      value  can  be  passed  to the method as an additional parameter
	      like request.getArg(name,defaultValue).

	      For compatibility	reasons	with older tntnet  request.getArg  ac-
	      cepts  a numeric argument. Previously the	arguments did not have
	      names  but  were	accessed  by  index.  To  emulate  this,   re-
	      quest.getArg  with a numeric argument translates the number into
	      the name "argnumber". So accessing request.getArg(2) returns the
	      value  of	 the  argument with the	name arg2. 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.

       Example

	      <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>

LISTENERS
       The section <listeners> 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.

       Each listener is	defined	in a node <listener>. A	listener must  have  a
       subnode	<ip>  and  <port>.  The	 node <ip> may contain a ip address or
       hostname	or may be left empty. If the node is empty, any	 interface  is
       used. The <port>	must contain the numeric port number.

       The ip address may be a IPv4 or IPv6 address.

       Optionally  a  tag  <certificate> may be	added. This enables ssl	on the
       interface and specifies the ssl host  certificate  for  the  interface.
       Note  that  tntnet  can	be built without ssl support. In that case the
       certificate is just ignored and unencrypted http	is used	here.

       Example

	      <listeners>
		<listener>
		  <ip></ip>
		  <port>80</port>
		</listener>
		<listener>
		  <ip></ip>
		  <port>443</port>
		  <!-- a certificate enables ssl -->
		  <certificate>tntnet.pem</certificate>
		</listener>
	      </listeners>

AUTHOR
       This manual page	was written by Tommi MAxkitalo <tommi@tntnet.org>.

SEE ALSO
       tntnet (1)

Tntnet				  2006-07-23			 tntnet.xml(8)

NAME | DESCRIPTION | SETTINGS | URL MAPPING | LISTENERS | AUTHOR | SEE ALSO

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=tntnet.xml&sektion=7&manpath=FreeBSD+12.2-RELEASE+and+Ports>

home | help