Ubuntu Manpage: danted.conf - Dante server configuration file syntax

Provided by: dante-server_1.4.2+dfsg-7build7_amd64

NAME

       danted.conf - Dante server configuration file syntax

DESCRIPTION

       The configuration file for the Dante server controls both access controls and logging.  It
       is divided into three parts; server settings, rules, and routes.

       Note that server settings must come before rules and routes.

       A line can be commented out using the standard comment character #.

SERVER SETTINGS

The server settings control the generic behaviour of the server. Each keyword is
separated from its value by a ':' character.

The following keywords are available:

clientmethod
A list of acceptable authentication methods for client-rules, listed in order of
preference. These are authentication methods that are to be checked immediately
after the SOCKS client has connected to Dante, and before any socks-negotiation has
started.

Supported values are pam.address, pam.any, none, and rfc931 .

For all methods the authentication will be based on solely on the IP-address of the
client, possibly in combination with a rfc931 ("ident") lookup towards the host the
client is running on.

Any credentials provided during this pass will also be available for use in later
socks-rules, when the socks-request from the client is evaluated.

The default value for this keyword is all methods that may be necessary for the
later socks-based authentication methods, as specified as values to the global
socksmethod keyword. Normally you should not need to set this keyword, as Dante
will set it to the correct value by it self.

compatibility
With the sameport keyword, the server attempts to use the same port on the server's
external side as the client used on the server's internal side. This is normally
the default, but when this option is given it will be done with privileged ports
also, meaning if a client connects to Dante from a privileged port, Dante will
attempt to connect to the target destination from a privileged port too. There can
be security issues involved with this, so normally this option should not be set.

The draft-5.05 keyword will enable usage of parts of the socks v5-05 draft. The
only feature from this draft that Dante supports is the "USECLIENTSPORT" extension.
Note that there is a conflicting interpretation of this extension, so enabling it
might prevent clients using the conflicting interpretation from working correctly.
Only affects UDP.

cpu The CPU settings for the various type of Dante processes. Note that the
possibility for configuring these settings depend on the platform Dante is running
on. Not all platforms may provide support for these type of CPU settings.

There are four process types: mother, negotiate, request, and io.

The currently supported options are:

schedule.<process type>: <scheduling policy>/<priority>.

Example: cpu.schedule.mother: SCHED_FIFO/20 The above requests that the kernel
schedules the mother process(es) using a first-in, first-out policy, at priority
20.

The default is to not request any specific scheduling.

mask.<process type>: <cpu id 1> [cpu id 1 ...]/any.

Example: cpu.mask.mother: any Example: cpu.mask.io: 0 1

The mask gives control over the CPU/cores on which the different process types will
run. Specifying the default (all) allows the process type to run on any CPU id.
Specifying one or more numeric CPU id limits the process to that set of CPUs.

The cpu keywords (schedule and mask) should in most cases not be necessary. If they
are to be used, the io processes are where most of the work is done and adjusting
the priority or CPU usage is what is likely to have the most significant
performance effect client performance and overhead from the server. The other
processes are primarily used during connection/session establishment and changes to
settings for the non-io process types will primarily affect these operations.

The default is to not limit processes to any specific cpu.

debug Print debug info to the logs. The value sets the debug level.

errorlog
This value can be set to receive only error-related logoutput. Note that this does
not include client-specific errors, but only more serious "global" errors.

The possible values are the same as for the logoutput keyword mentioned below.

The intent is to have a special place that only serious errors are logged so that
they can discovered quickly. The default is to not have any special place to log
errors.

external
The address to be used for outgoing connections. The address given may be either a
IP address or an interface name. Can be given multiple times for different
addresses.

external.log.<loglevel>.error
See internal.log.<loglevel>.error. This option has an identical syntax and
semantics, but applies to error related to the external interface side.

external.protocol
By default Dante will use the address families specified and available, and there
is no need to set this keyword.

In some cases the operator may however wish to specify an address in a form that
may include more than one address family, yet not wish for Dante to use all the
address families available for that address form.

This will typically happen if the operator wishes to specify that Dante should use
the addresses on a network interface card which has both IPv4 and IPv6 addresses
configured, yet the operator wishes Dante to only use one of these two address
families. The operator can then specify the address family he wants Dante too look
for when expanding the interface name for IP-addresses to use.

Valid values for this keyword are: ipv4 and ipv6, indicating that Dante should only
use the IPv4 address family or only the IPv6 address family, respectively. The
default is to use both families, if available.

A corresponding keyword exists for the internal side (see internal.protocol).

external.rotation
If more than one external address is given, this governs which of the given
addresses is selected as the source address for outgoing connections/packets. Note
that regardless of which external rotation value is used, all external addresses
that are to be used must be listed via the external keyword first.

Valid values are none (the default), route, and same-same.

none indicates the first address on the list of external addresses should be used.

route indicates the kernels routing table should be consulted to find out what the
source address for a given destination will be, and might require you to set
user.privileged to root. Note that route might create problems for ftp-clients
using active ftp if the Dante bind extension is enabled for the ftp-client.

same-same indicates the source address for a given destination should be the same
address as the Dante server accepted the clients connection on.

internal
The internal addresses. Connections will only be accepted on these addresses. The
address given may be either a IP address or an interface name.

internal.log.<loglevel>.error
Specifies that certain system call failures, listed as symbolic errno values, or
certain dns failures, listed as symbolic libresolv failure-codes, should be logged,
possibly an extra time, at the log-level log-level.

Note that this only applies to errors on the internal interface side only.

A corresponding keyword exists for the external side (see external.log).

In addition to the standard errno and getaddrinfo(3) error symbols, the following
special symbols are accepted:

no-route
Any error related to no route.

dns-any
Any error related to DNS/hostname-resolving.

system-any
Any system error. I.e., any errno value.

internal.protocol
See external.protocol. This option has an identical syntax and semantics, but
applies to the internal interface, for addresses to listen to connections from
clients on.

libwrap.hosts_access
If the server is compiled with libwrap support, determines whether the
hosts_access() function should be used for access control. When enabled by setting
this value to yes, the libwrap library determines if TCP connections or UDP packets
should be immediately dropped or not, typically by consulting /etc/hosts.allow and
/etc/hosts.deny. These checks are applied to all traffic, before the rule
processing starts. The default value is no (disabled).

logoutput
This value controls where the server sends logoutput. It can be set to
syslog[/facility], stdout, stderr, a filename, or a combination. The default is
nowhere. Note that if errorlog is also set, there will be a overlap between what
is logged there (errors only), and what will be logged here (errors, and everything
else).

socksmethod
A list of acceptable authentication methods for socks-rules, listed in order of
preference. It is thus important that you specify these in the desired order,
normally with the more secure methods first.

Supported values are bsdauth, gssapi, none, pam.any, pam.address, pam.username,
rfc931, and username,

If a method is not set in this list it will never be selected. The default is no
methods, which means all socks-requests will be blocked.

See the section on AUTHENTICATION METHODS for an explanation of the different
methods and their meaning.

srchost
This keyword allows you to configure a few options that relate to the srchost,
i.e., the host the Dante server accepts the connections from.

With the nodnsmismatch keyword, the server will not accept connections from
addresses having a mismatch between DNS IP address and hostname. Default is to
accept them.

With the nodnsunknown keyword, the server will not accept connections from
addresses without a DNS record. Default is to accept them.

With the checkreplyauth keyword, the server will check that the authentication on
bind-replies and udp-replies matches that which is set in the rule and global
socksmethod. Normally, authentication is not desired on replies, as they are
replies sent to the socks-clients from non-socks clients, and thus only a limited
set of authentication methods are possible.

The methods possible for TCP are the methods not involving the socks protocol in
any way, and are listed in the clientmethod section previously mentioned. For UDP-
replies, no methods can be used.

Default is not to check the authentication on replies.

timeout.connect
The number of seconds the server will wait for a connect initiated on behalf of the
socks-client to complete. The default is 30. Setting it to 0 will use the systems
default.

timeout.io
The number of seconds an established connection can be idle. The default is 0,
meaning forever. See also the "-n" option in the danted(8) manpage.

Individual timeouts can be set for TCP and UDP by suffixing io with
".<protocolname>", i.e. timeout.io.tcp or timeout.io.udp.

Individual timeouts can also be set within rules, using the same syntax. The
timeout set in the rule will then override the default timeouts for clients
matching the rule.

timeout.negotiate
The number of seconds a client can spend negotiating with the Dante server for a
socks session before Dante will close the connection to the client. The default is
30. Set it to 0 for forever, though that is strongly discouraged.

timeout.tcp_fin_wait
The timeout for the equivalent of TCP's FIN-WAIT-2. The default is 0, which means
use the systems default (normally, no timeout).

udp.connectdst
Enables or disables whether the server should attempt connecting UDP sockets to the
destination. Valid values are yes and no.

The default is yes, which improves UDP performance, but may not be compatible with
some UDP-based application protocols as it means the server can only receive
packets from the destination address.

The socket will only remain connected as long as the client only sends UDP packets
to one destination address. If packets are sent to multiple destinations the socket
will no longer remain connected and replies can be received from any destination.

Userids
On platforms providing a privilege-model supported by Dante, the Dante server does
not use userid-switching via the seteuid(2) system call. On other platforms, it is
prudent to set the userid to be used by the Dante server to appropriate values.
The Dante server can use two different userids, or three if compiled with libwrap
support. They are as follows:

user.privileged
Username which will be used for doing privileged operations. If you need special
privileges to read the danted.conf file or to write the danted.pid file (you can
create it manually before starting danted), have anything in your configuration
that requires binding privileged TCP/UDP ports (ports below 1024), or use some sort
of password-based authentication, this probably needs to be set to root.

If not, you can probably set it to the same value as user.unprivileged.

user.unprivileged
User which the server runs as most of the time. This should be an id with as
little privileges as possible. It is recommended that a separate userid is created
for this purpose.

user.libwrap
User used to execute libwrap commands. Normally this should be the same as
user.unprivileged

MODULES

       The  following  modules  are  supported  by  Dante.  Modules are purchased separately from
       Inferno Nettverk A/S and may add extra functionality that is not  needed  by  most  users.
       See the Dante homepage for more information.

       bandwidth
              The bandwidth module gives control over how much bandwidth the Dante server uses on
              behalf of different clients or to different targets.

       redirect
              The redirect module gives you control over what addresses the server  will  use  on
              behalf  of  the  clients,  as well as allowing you to redirect client requests to a
              different addresses.

SOCKET OPTIONS

       The server has support for setting a large number of  low-level  socket  options  on  both
       incoming  and outgoing traffic.  Most users will not need to set any of these options, but
       some might want to do it, to enable  special  network  features,  or  to  perform  various
       experiments.

       Options  can  be set globally as defaults for all traffic, or be set in the access control
       rules to only affect clients and targets matching the given rule.

       The socket options that are available vary between platforms, so during configuration  and
       building  of  the server the options that are available will be determined. Currently, the
       following options should be detected, when available, for the specified protocol levels:

              SOCKET so_bindany, so_broadcast, so_debug,  so_dontroute,  so_jumbo,  so_keepalive,
                     so_oobinline,    so_priority,    so_rcvbuf,   so_rcvbufforce,   so_rcvlowat,
                     so_sndbuf, so_sndbufforce, so_sndlowat, so_useloopback

              TCP    tcp_cork, tcp_cwnd, tcp_init_cwnd, tcp_keepcnt, tcp_keepidle, tcp_keepintvl,
                     tcp_linger2,  tcp_maxrt,  tcp_maxseg,  tcp_md5sig,  tcp_nodelay,  tcp_noopt,
                     tcp_nopush, tcp_sack_enable, tcp_stdurg, tcp_syncnt, tcp_window_clamp

              UDP    udp_cork

              IP     ip_auth_level,   ip_dontfrag,   ip_esp_network_level,    ip_esp_trans_level,
                     ip_freebind,   ip_ipcomp_level,  ip_minttl,  ip_mtu_discover,  ip_portrange,
                     ip_recvtos, ip_tos, ip_ttl

       The syntax for setting socket options is as follows:

       <direction>.<level>.<option>: <value>

       The value field corresponds to the value that the socket option should be set to. For many
       socket  options  this  is an integer value.  The level and option values correspond to the
       socket names and protocol levels listed above. Both should be in lower-case.

       The direction keywords is used to specify whether the socket  option  should  be  set  for
       traffic  on  the  internal  or the external interface and can have the values internal and
       external.  For example, to set the IP_TOS socket option on outgoing traffic, the following
       syntax can be used:

       external.ip.ip_tos: 0x10

       In  this  example,  the argument value (0x10) is specified as a hex value. For some of the
       socket options the value can also be set symbolically. Currently this is possible for  the
       following options, with the listed values:

              ip_portrange
                     ip_portrange_default, ip_portrange_low, ip_portrange_high

       The  IP_TOS  socket  option  also  supports  this,  but  handling  this option is somewhat
       complicated by the same bits having different meanings in different RFCs. Handling this is
       done  with  a  subfield  that  indicates  the  type  of  argument that should be used. The
       following subfields are defined and should be added to the name of the  socket  option  as
       specified below:

              ip_tos.dscp
                     af11  af12 af13 af21 af22 af23 af31 af32 af33 af41 af42 af43 cs0 cs1 cs2 cs3
                     cs4 cs5 cs6 cs7 ef

              ip_tos.prec
                     netcontrol internetcontrol critic_ecp flashoverride flash immediate priority
                     routine

              ip_tos.tos
                     lowdelay throughput reliability

       When  numerical  arguments are given to subfields, the values are shifted to apply only to
       the subfield bit range. The following example shows the different ways of  setting  IP_TOS
       to lowdelay on external traffic:

       external.ip.ip_tos:     0x10       #base value, numerically
       external.ip.ip_tos.tos: 0x08       #subfield, numerically
       external.ip.ip_tos.tos: lowdelay   #subfield, symbolically

       The  first  value  sets  the  value directly, the second sets only the TOS bits, which are
       shifted relative to the base value. The final line sets the TOS value symbolically.

       This functionality gives a large amount of control over socket options, but it should  not
       be  used  without some understanding of how the kernel allows the socket option to be set,
       and the limitations that apply when the socket options are set as either  defaults  or  in
       rules.

       Setting  a  socket  option  in  a client pass or socks-rules will cause any defaults to be
       overridden. Global options are set before bind() is called on internal sockets, or  before
       connect()  is  called  on  external  sockets. Options set in client rules are also applied
       before bind() is called on the internal socket, but cannot be set for the external socket.
       For  socks-rules,  both  external  and internal options can be set, but because the socks-
       request must be interpreted before the rules can be evaluated, socket options can only  be
       set on internal sockets after the connection has been received.

       Some socket options must be set before a connection has been established, while others can
       only be set after a connection has been established. Others can be set at any time.

       Socket options that are not listed above can also be set by specifying the  socket  option
       name numerically, for example:

       external.ip.10:     0x12

       In this example the socket option corresponding to the value 10 will be set. These numbers
       are platform dependent but can typically be  determined  by  looking  at  the  appropriate
       system  header  files.   Specifying options numerically might result in some warnings, but
       allows any socket option to be specified, as long as it takes a numerical  argument.  This
       is not the recommended approach for setting socket options, but represents a simple way of
       setting socket options that are not directly supported by the server, such as local kernel
       extensions.

AUTHENTICATION METHODS

The Dante server supports the following authentication methods. Some installations of
Dante may support only a subset of these, depending on platform support.

none This method requires no form of authentication.

username
This method requires the client to provide a username and password. This
information must match the username and password given in the system password file.

gssapi This method requires the setup of a Kerberos environment and can provide strong
encryption and authentication, depending on the gssapi settings you choose.

rfc931 This method requires the host the socks client runs on to provide a rfc931
("ident") username for the client. This username match a username given in the
system password file.

pam.address
IP-based (rhosts) PAM authentication.

pam.any
Will try to match against any type of PAM authentication, depending on the
information that is currently available. Normally of limited use, and you should
instead set the pam-based method(s) you actually want.

pam.username
Username/password-based PAM authentication. Similar to the method username, but
the information is passed to the PAM subsystem for authentication, rather than
Dante using the system password file directly. When using PAM, be wary of memory
leakages and other bugs in the external PAM library Dante will have to use on your
platform.

bsdauth
This method requires the available client data to be verified by the BSD
Authentication system. Similar to the method username, but passed to the BSD
authentication system instead.

ADDRESSES

       Each address field can consist of an IP address (and where required, a netmask,  separated
       from the IP address by a '/' sign), a hostname, a domainname (designated so by the leading
       '.'), or an interface name.

       An IP address can be given on on IPv4 form, IPv6 form, or as the special value 0/0,  which
       matches  all  IP addresses, be they IPv4 or IPv6.  The latter is intended for use in rules
       that should match both IPv4 and IPv6 clients or targets.

       Each address, except the external address, can include an optional port specifier.

RULES

There are two sets of rules and they work at different levels. Rules prefixed with client
are checked first and are used to see if the client is allowed to connect to the Dante
server. We call them "client-rules". These rules will start with client pass for a rule
that allows the client, or client block for a rule that blocks the client.

It is recommended that the client-rules do not use hostnames but only IP-addresses, both
for security and performance reasons. These rules operate at the TCP level.

The other rules, which we call "socks-rules", are prefixed with socks and operate at the
socks protocol level.

These rules will start with socks pass for a rule that allows the client, or socks block
for a rule that blocks the client.

These rules are only checked if the client connection has been allowed by the client-
rules. The socks-rules are used to evaluate the socks request that the client sends.

While it is less important that these rules use only IP-addresses, provided the client-
rules have been configured to only allow access from a pre-defined range of client IP-
addresses, it is still recommended.

Both set of rules include a pass or deny keyword. The pass/deny keyword determines
whether connections matching the rule are to be passed through or be blocked.

Both the client-rules and the socks-rules also specify a from/to address pair which gives
the addresses the rule will match.

In both contexts, from refers to the clients address, i.e., the address the client is
connecting to the Dante server from. The to address however refers to different things
depending on whether it is used in a client-rule or in a socks-rule.

In the client-rule context, to means the address the request is accepted on, i.e., a
address the Dante server listens on.

In the socks-rule context, to means the client's destination address, as expressed in the
client's socks request. I.e., the address the Dante server should connect to (for TCP
sessions) or send packets to (for UDP session) on behalf of the client.

Both set of rules are evaluated on a "first match is best match" basis. That means, the
first rule matched for a particular client or socks request is the rule that will be used.

In addition to the addresses there is a set of optional keywords which can be given.
There are two forms of keywords; conditions and actions. For each rule, all conditions
are checked and if they match the request, all actions are executed.

The list of condition keywords is: clientcompatibility, clientmethod, command, from,
group, socksmethod, protocol, proxyprotocol, to, user.

The list of action keywords is: bandwidth, libwrap, log, session, redirect,
timeout.connect, timeout.negotiate, timeout.io, timeout.tcp_fin_wait, and udp.portrange.

The format and content of the keyword as used in client-rules or socks-rules is identical,
but client-rules can contain only a subset of the keyword that socks-rules may contain.

The contents of a client-rule can be:

bandwidth
The clients matching this rule will all share the given amount of bandwidth,
measured in bytes per second. Requires the bandwidth module.

clientcompatibility
Enables certain options for compatibility with broken clients. Valid values are:
necgssapi, for compatibility with clients implementing GSSAPI the NEC socks way.

from The rule applies to requests coming from the specified address.

group The user must belong to one of the groups given as value.

Note that if gssapi-based authentication is used, the username as provided to the
Dante server normally includes the Kerberos domain. The name must be listed on the
same form here and in the system groupfile (usually /etc/passwd) if it is to be
used.

gssapi.enctype
Which encryption to enforce for GSSAPI-authenticated communication. Possible
values are clear, integrity, or confidentiality. The default is to accept whatever
the client offers except clear, as clear is not part of the SOCKS GSSAPI standard.

gssapi.keytab
Value for keytab to use. The default is "FILE:/etc/danted.keytab".

gssapi.servicename
Which servicename to use when involving GSSAPI. Default is "rcmd".

libwrap
The server will pass the specified parameter line to libwrap for execution.

log Used to control logging. Accepted keywords are connect, disconnect, data, error,
ioop, and tcpinfo. The default is no logging.

session
Control the max number of sessions or session establishment rate. See below for
details.

clientmethod
Require that the connection be "authenticated" using one of the given
clientmethods.

pam.servicename
Which servicename to use when involving pam. Default is "danted".

port Parameter to from, to and via. Accepts the keywords eq/=, neq/!=, ge/>=, le/<=,
gt/>, lt/< followed by a number. A port range can also be given as "port <start #>
- <end #>", which will match all port numbers within the range <start #> and <end
#>.

The default is to match all ports.

redirect
The source and/or destination can be redirected using the redirect statement.
Requires the redirect module.

The syntax of the redirect statement is as follows:

redirect from: ADDRESS

See the redirect manual for detailed information.

socksmethod
If the client offers more than one authentication method, Dante will select the
method to use based on the order the methods are listed here. Valid values are the
same as in the global socksmethod line. Normally there will be no need to set this
keyword in a client-rule, but if it is set and the client offers none of the
methods listed, the client will be blocked at this stage.

timeout.negotiate
See the global timeout.negotiate option.

to The rule applies to requests going to the address given as value.

user The user must match one of the names given as value. If no user value is given for
a rule requiring usernames, the effect will be the same as listing every user in
the password file.

The contents of a socks-rule can be:

bandwidth
The clients matching this rule will all share the given amount of bandwidth,
measured in bytes per second. Requires the bandwidth module.

bsdauth.stylename
The name of the BSD authentication style to use. The default is to not specify a
value, causing the default system style to be used.

command
The rule applies to the given commands. Valid commands are bind, bindreply,
connect, udpassociate and udpreply. Can be used instead of, or to complement,
protocol. The default is all commands valid for the protocols allowed by the rule.

from The rule applies to requests coming from the address given as value.

group The user must belong to one of the groups given as value.

libwrap
The server will pass the line to libwrap for execution.

log Used to control logging. Accepted keywords are connect, disconnect, data, ioop,
and tcpinfo.

session
Control the max number of sessions or session establishment rate. See

socksmethod
Require that the connection be established using one of the given authentication
methods. A method normally refers to the socks client part of the rule, and thus
authenticates the client, and not the target destination (see checkreplyauth for
information about authentication the target destination). Valid values are the
same as in the global socksmethod line.

pam.servicename
What servicename to use when involving pam. Default is "danted".

port Parameter to from, to and via. Accepts the keywords eq/=, neq/!=, ge/>=, le/<=,
gt/>, lt/< followed by a number. A portrange can also be given as "port <start #>
- <end #>", which will match all port numbers within the range <start #> and <end
#>.

The default is all ports.

protocol
The rule applies to the given protocols. Valid values are tcp and udp. The
default is all supported protocols that can apply to the given commands.

proxyprotocol
The rule applies to requests using the given proxy protocol. Valid proxy protocols
are socks_v4 and socks_v5. The default is all supported proxy protocols.

redirect
The source and/or destination can be redirected using the redirect statement.
Requires the redirect module.

The syntax of the redirect statement is as follows:

redirect from: ADDRESS

redirect to: ADDRESS

The semantics of from and to vary according to command. See the redirect manual
for detailed information.

timeout.connect
See the global timeout.connect option.

timeout.io
See the global timeout.io option.

timeout.tcp_fin_wait
See the global timeout.tcp_fin_wait option.

to The rule applies to requests going to or using the address given as value. Note
that the meaning of this address is affected by command.

udp.portrange
The argument to this keyword is two port numbers, separated by a dash ('-'). They
specify the UDP port-range that will be used between the socks-client and the
Dante-server for UDP packets. Note that this has no relation to the UDP port-range
used between the Dante-server and external, non-socks, clients/servers.

user The user must match one of the names given as value. If no user value is given for
a rule requiring usernames, the effect will be the same as listing every user in
the password file.

SESSION

The session keyword can be used any any rule to limit the number of active sessions and
the rate at which they are established. There are two main commands for this; session.max,
that controls the max number of sessions that can be matched, and session.throttle, that
controls the connection rate. These commands can be applied both for the total limit for
all matching clients and can be set as global defaults or in any of the rule types. The
session.max keyword takes a number corresponding to the highest number of allowed
simultaneous connections as an argument. The session.throttle keyword takes two number
separated by a slash character, with the first representing the number of connections and
the latter a time duration in seconds. If more than the specified number of connections
are received in the specified number of seconds, additional connections will be dropped.

Stateful session tracking on a per IP-address basis is also supported. For stateful
tracking, the limits apply to each connection with a matching IP-address, with the
session.state.key keyword is used to control how the IP-address is determined. Currently
two values are supported, from and hostid. The former causes the limit to be applied to
all hosts with the same source IP-address and the latter to all TCP connections with the
same hostid value. If a hostid value is used, the session.state.key.hostindex keyword can
be used to choose which of the to hostid values are used, with the first value being the
default.

Limits are evaluated first for client rules, then for hostid rules, and finally for socks
rules. By default, a limit set in a matching client rule will be used also any subsequent
matching hostid or socks rules, unless either of these rules also have session limit
keywords. This session inheritance can be disabled in client and hostid rules, causing
them to only apply in the rule in which they appear. This is done by setting the
session.inheritable to no.

The session keywords must be set in a rule (either client, hostid, or socks), setting them
globally is not supported.

TRAFFIC MONITORING

The Dante server can be configured to monitor the traffic passing through it, and trigger
alarms based on the observed network traffic.

The alarms are specified in so-called monitors. These objects have the same general format
as the rules Dante uses for access control and enable perform passive monitoring of
network traffic, or the lack of network traffic.

The following example shows the general monitor syntax, specifying a monitor without any
monitoring operations:

monitor {
from: 0.0.0.0/0 to: www.example.org port = 80
protocol: tcp
}

A monitor can include many of the same keywords that are available in the Dante ACL rules.
The following subset is currently supported:

from Normally specifies what SOCKS client addresses/networks to monitor.

to Normally specifies what target addresses/networks to monitor.

protocol
Can be used to restrict monitoring to a certain protocol (TCP, UDP or both).
Note: only TCP should be used for now.

hostid Can be used to restrict monitoring to only clients with a specific hostid
value set.

hostindex
Used along with the hostid keyword to control which of the two possible
hostid values will be used when matching.

NOTE: It is currently recommended that the protocol keyword is always specified and set to
tcp because there is currently only limited support for monitoring of UDP traffic, and
testing of UDP traffic monitoring has not been done.

The main function of monitors is to provide a container for one or more alarms, which are
specified using a new set of keywords not available for other rules. Alarms specify a
condition that will cause Dante to log a warning if the condition is triggered.

Active TCP sessions will at most match one monitor, but multiple alarms can be specified
in a single monitor. This makes it possible to specify multiple sets of conditions for the
same TCP sessions, depending on what network interface the traffic is transferred on and
whether the traffic is being received or transmitted.

Alarms can trigger as a result of periods of no or little data being transmitted, or a
large numbers of TCP connections disconnecting during a short period of time, or for other
reasons. See below for a complete list of what conditions alarms can be enabled for.

Data alarms
Adding an alarm.data keyword to a monitor will result in warnings being logged if there
are periods with too little network traffic.

Dante has four network paths and data alarms can be configured independently for each of
them:

internal.alarm.data.recv
Data received on Dante's internal interface (data sent from the SOCKS
clients to Dante).

internal.alarm.data.send
Data sent out on Dante's internal interface (data sent from Dante to the
SOCKS clients).

external.alarm.data.recv
Data received on Dante's external interface (data sent from the target
servers to Dante).

external.alarm.data.send
Data sent out on Dante's external interface (data sent from Dante to the
target servers).

The data.alarm keyword takes two parameters: a byte count and a duration in seconds. The
alarm will trigger if the specified number of seconds pass with only the specified number
of bytes (or less) being transmitted.

The syntax is as follows:

internal.alarm.data.recv: DATALIMIT in INTERVAL

The DATALIMIT is a number that specifies the byte limit. The INTERVAL is a number that
specifies the duration. If only DATALIMIT bytes (or less) have been transferred during a
period of INTERVAL seconds, an alarm will trigger in Dante.

Data alarms trigger when a period of data idleness has been detected. Once a data alarm
has triggered it will remain active until it is cleared. A warning will be logged when the
alarm triggers and than again when the alarm condition is cleared. In between these two
points no warnings related to this alarm will be logged. This avoids repeating the same
alarm/warning multiple times during network problems that last for an extended amount of
time. When the alarm is cleared, Dante will also include information about how long the
alarm condition lasted.

A data alarm can be cleared in two ways; automatically, once enough data has been
transferred in a short enough amount of time, or manually, by sending the Dante server a
SIGHUP signal. A SIGHUP will cause all active alarms to be cleared. No log messages
indicating that the alarms have cleared will be logged when alarms are cleared in this
way.

Once an alarm has been cleared, it can trigger again if enough data is not being
transferred.

Note that data alarms will trigger regardless of whether there are active sessions
matching the monitor or not; if enough data is not being transmitted or received, a data
alarm will trigger. Alarms will trigger also shortly after server startup, if the Dante
server does not receive sufficient traffic to prevent the alarms from triggering.

Note that the message indicating that an alarm has cleared is not logged if the alarm was
cleared due to a SIGHUP signal being received.

Disconnect alarms
The disconnect alarms are related to connection disconnects and by using the
alarm.disconnect keyword the Dante server can log warnings based on the number and rate of
terminated connections.

There are two variants of the alarm keyword, one for the internal network interface,
between the SOCKS clients and Dante, and one for the external interface, between the Dante
server and the target servers:

internal.alarm.disconnect
Connections between SOCKS clients and the Dante server.

external.alarm.disconnect
Connections between the Dante server and target servers.

Each alarm keyword takes three parameters, a minimum count, a ratio value, and a time
interval. The following format is used:

internal.alarm.disconnect: MINCOUNT/RATIO in INTERVAL

The MINCOUNT is the minimum number of connections that must be disconnected for the alarm
to trigger. The RATIO is used together with the MINCOUNT to express the number of
connections, relative to the total number of connections that have existed in the time
period, that must be disconnected for the alarm to trigger. The INTERVAL is the time in
seconds within which the disconnects must occur for the alarm to trigger.

To set values that are useful, some knowledge about the expected amount of network traffic
and number of sessions is required. If the rate of disconnects, as a percentage, is lower
than the ratio specified, an alarm will not trigger. Conversely, if the MINCOUNT is set
too low, alarms might trigger too frequently because only a small number of disconnects
might be sufficient to achieve the required number of disconnects and disconnect ratio at
times when there are only a few active sessions.

Only connections that are terminated on the specified interface are counted, i.e., an
external.alarm.disconnect alarm will only trigger for connections that are terminated on
the network interface between the Dante server and the target server, either by the target
server closing the connection to Dante or by Dante receiving a fatal network error from
that side of the connection (e.g., a TCP RST packet).

Connections that are closed on the internal interface (by the SOCKS clients) will not
count towards a disconnect alarm on the external side. Likewise, connections closed by
target servers will not count towards a disconnect alarm on the internal side.

A practical consequence of this is that if a large number of connections are
simultaneously closed by both the client and the target server, each connection will only
be counted as a disconnect on one of the sides; either the external side or the internal
side, depending on which side closes the connection first.

Alarms trigger each time a sufficient number disconnects occur. Each sufficiently large
burst of disconnects will result in an alarm, but normally at most one warning per alarm
will be logged during each time interval, though this might change in a later version of
Dante.

Separate alarms are produced for each distinct alarm keyword when multiple alarms are
specified in a monitor rule.

ROUTES

       The  routes  are specified with a route keyword.  Inside a pair of curly braces ({}) a set
       of keywords control the behavior of the route.  See dante.conf(5) for a description.  This
       is used to perform so-called "server-chaining", where one socks-server connects to another
       socks-server further upstream.

       The syntax for these routes is the same as the routes used  by  the  client.   Please  see
       dante.conf(5) for information about the route syntax.

       There are however some special things one need to be aware of regarding serverchaining and
       routes specified for the server:

              At present serverchaining is only supported for the tcp connect command.

              If the route specifies that a username/password-method should  be  offered  to  the
              upstream  proxy,  Dante  will  forward  the username/password received from its own
              client to the foreign upstream proxy, meaning the upstream proxy will  receive  the
              user's username and password in cleartext from Dante.

              At  present  serverchaining does not scale well in Dante and should not be used for
              anything but minimal client loads.

EXAMPLES

       See the example/ directory in the distribution.

FILES

       /etc/danted.conf   Dante server configuration file.
       /etc/passwd       systemfile used when doing standard username/password
                         authentication.

AUTHORS

       For inferno Nettverk A/S:
          Michael Shuldman
          Karl-Andre' Skevik