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

Provided by: dante-server_1.4.3+dfsg-1_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 an 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 an 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