.\" $Id: sockd.conf.5,v 1.187.4.4.2.2.4.2 2019/01/09 16:52:18 karls Exp $
.\"
.\" Copyright (c) 1997, 1998, 1999, 2000, 2001, 2002, 2003, 2004, 2005, 2006,
.\"               2008, 2009, 2010, 2011, 2012, 2013, 2014, 2017
.\"      Inferno Nettverk A/S, Norway.  All rights reserved.
.\"
.\" Redistribution and use in source and binary forms, with or without
.\" modification, are permitted provided that the following conditions
.\" are met:
.\" 1. The above copyright notice, this list of conditions and the following
.\"    disclaimer must appear in all copies of the software, derivative works
.\"    or modified versions, and any portions thereof, aswell as in all
.\"    supporting documentation.
.\" 2. All advertising materials mentioning features or use of this software
.\"    must display the following acknowledgement:
.\"      This product includes software developed by
.\"      Inferno Nettverk A/S, Norway.
.\" 3. The name of the author may not be used to endorse or promote products
.\"    derived from this software without specific prior written permission.
.\"
.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY EXPRESS OR
.\" IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
.\" OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED.
.\" IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT,
.\" INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT
.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
.\" DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
.\" THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
.\" (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF
.\" THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
.\"
.\" Inferno Nettverk A/S requests users of this software to return to
.\"
.\"  Software Distribution Coordinator  or  sdc@inet.no
.\"  Inferno Nettverk A/S
.\"  Oslo Research Park
.\"  Gaustadalleen 21
.\"  NO-0349 Oslo
.\"  Norway
.\"
.\" any improvements or extensions that they make and grant Inferno Nettverk A/S
.\" the rights to redistribute these changes.
.\"
.TH DANTED.CONF 5 "July 29 2013"
.SH NAME
danted.conf \- \fBDante\fP server configuration file syntax
.SH DESCRIPTION
The configuration file for the \fBDante\fP server controls both access
controls and logging.  It is divided into three parts; server settings,
rules, and routes.

Note that server settings \fBmust\fP come before rules and routes.

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

.SH SERVER SETTINGS
The server settings control the generic behaviour of the server.  Each
keyword is separated from its value by a \fB':'\fP character.

The following keywords are available:

.\" .IP \fBchild.maxrequests\fP
.\" Maintains a max on the total number of clients a child process will
.\" serve before exiting.  After having served the given number of
.\" clients, the child process will exit.
.\"
.\" The only reason for the existence of this option is to work around buggy
.\" behavior in external libraries used by the the \fBDante\fP server,
.\" which may end up leaking resources or create other problems when having
.\" run to long.  The default value is \fB0\fP, meaning no limit.
.\"
.IP \fBclientmethod\fP
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 \fBDante,
and \fBbefore\fP any socks-negotiation has started.

Supported values are \fBpam.address\fP, \fBpam.any\fP, \fBnone\fP,
and \fBrfc931\fP .

For all methods the authentication will be based on solely on the
IP-address of the client, possibly in combination with a \fBrfc931\fP
("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 \fBDante\fP will set it to the correct value by it self.

.IP \fBcompatibility\fP
With the \fBsameport\fP 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 \fBDante\fP from a privileged port, \fBDante\fP 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 \fBdraft-5.05\fP keyword will enable usage of parts of the socks
v5-05 draft.  The only feature from this draft that \fBDante\fP 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.

.IP \fBcpu\fP
The CPU settings for the various type of \fBDante\fP processes.
Note that the possibility for configuring these settings depend on
the platform \fBDante\fP is running on.  Not all platforms may provide support
for these type of CPU settings.

There are four process types: \fBmother, negotiate, request\fP, and \fBio\fP.

The currently supported options are:

\fBschedule\fP.<process type>: <scheduling policy>/<priority>.

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

The default is to not request any specific scheduling.

\fBmask\fP.<process type>: <cpu id 1> [cpu id 1 ...]/any.

Example: \fBcpu.mask.mother: any\fP
Example: \fBcpu.mask.io: 0 1\fP

The mask gives control over the CPU/cores on which the different
process types will run. Specifying the default (\fBall\fP) 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 (\fBschedule\fP and \fBmask\fP) should in most cases
not be necessary. If they are to be used, the \fBio\fP 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.

.IP \fBdebug\fP
Print debug info to the logs.  The value sets the debug level.
.IP \fBerrorlog\fP
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 \fBlogoutput\fP 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.

.IP \fBexternal\fP
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.

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

.IP \fBexternal.protocol\fP
By default \fBDante\fP 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: \fBipv4\fP and \fBipv6\fP, 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
\fBinternal.protocol\fP).


.IP \fBexternal.rotation\fP
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 \fBexternal\fP keyword first.

Valid values are \fBnone\fP (the default), \fBroute\fP, and \fBsame-same\fP.

\fBnone\fP indicates the first address on the list of external addresses
should be used.

\fBroute\fP 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 \fBuser.privileged\fP to \fBroot\fP.
Note that \fBroute\fP might create problems for
ftp-clients using active ftp if the \fBDante\fP bind extension
is enabled for the ftp-client.

\fBsame-same\fP indicates the source address for a given destination
should be the same address as the \fBDante\fP server accepted the clients
connection on.

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

.IP \fBinternal.log.<loglevel>.error\fP
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
\fBlog-level\fP.

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

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

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

.RS
.IP \fBno-route\fP
Any error related to no route.
.IP \fBdns-any\fP
Any error related to DNS/hostname-resolving.
.IP \fBsystem-any\fP
Any system error.  I.e., any errno value.
.RE

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

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

.IP \fBlogoutput\fP
This value controls where the server sends logoutput.  It can
be set to \fBsyslog\fP[/\fBfacility\fP], \fBstdout\fP, \fBstderr\fP,
a filename, or a combination.  The default is nowhere.  Note that
if \fBerrorlog\fP 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).

.IP \fBsocksmethod\fP
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 \fBbsdauth\fP, \fBgssapi\fP, \fBnone\fP,
\fBpam.any\fP, \fBpam.address\fP, \fBpam.username\fP, \fBrfc931\fP,
and \fBusername\fP,

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 \fBAUTHENTICATION METHODS\fP for an explanation of
the different methods and their meaning.

.IP \fBsrchost\fP
This keyword allows you to configure a few options that relate to the
srchost, i.e., the host the \fBDante\fP server accepts the connections
from.

With the \fBnodnsmismatch\fP 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 \fBnodnsunknown\fP keyword, the server will not accept connections
from addresses without a DNS record.  Default is to accept them.

With the \fBcheckreplyauth\fP 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 the methods not involving the socks
protocol in any way, and are listed in the \fBclientmethod\fP section
previously mentioned.  For UDP-replies, no methods can be used.

Default is not to check the authentication on replies.

.IP \fBtimeout.connect\fP
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.
.IP \fBtimeout.io\fP
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. \fBtimeout.io.tcp\fP or \fBtimeout.io.udp\fP.

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.
.IP \fBtimeout.negotiate\fP
The number of seconds a client can spend negotiating with the
\fBDante\fP server for a socks session before \fBDante\fP
will close the connection to the client.  The default is 30.
Set it to 0 for forever, though that is strongly discouraged.
.IP \fBtimeout.tcp_fin_wait\fP
The timeout for the equivalent of TCP's FIN-WAIT-2.  The default is 0,
which means use the systems default (normally, no timeout).
.IP \fBudp.connectdst\fP
Enables or disables whether the server should attempt connecting UDP
sockets to the destination.  Valid values are \fByes\fP and \fBno\fP.

The default is \fByes\fP, 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.

.IP \fBUserids\fP
On platforms providing a privilege-model supported by \fBDante\fP,
the \fBDante\fP 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 \fBDante\fP server to appropriate
values.  The \fBDante\fP server can use two different userids, or three
if compiled with libwrap support.  They are as follows:
.IP \fBuser.privileged\fP
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 \fBuser.unprivileged\fP.
.IP \fBuser.unprivileged\fP
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.
.IP \fBuser.libwrap\fP
User used to execute libwrap commands.  Normally this should be the same
as \fBuser.unprivileged\fP

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

.IP \fBbandwidth\fP
The \fBbandwidth\fP module gives control over how much bandwidth the
\fBDante\fP server uses on behalf of different clients or to different
targets.

.IP \fBredirect\fP
The \fBredirect\fP 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.

.SH SOCKET OPTIONS

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

.RS
.IP \fBSOCKET\fP
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
.RE

.RS
.IP \fBTCP\fP
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
.RE

.RS
.IP \fBUDP\fP
udp_cork
.RE

.RS
.IP \fBIP\fP
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
.RE

The syntax for setting socket options is as follows:

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

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

The \fBdirection\fP 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 \fBinternal\fP and \fBexternal\fP.
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:

.RS
.IP \fBip_portrange\fP
ip_portrange_default, ip_portrange_low, ip_portrange_high
.RE

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:

.RS
.IP \fBip_tos.dscp\fP
af11 af12 af13 af21 af22 af23 af31 af32 af33 af41 af42 af43 cs0 cs1
cs2 cs3 cs4 cs5 cs6 cs7 ef
.RE

.RS
.IP \fBip_tos.prec\fP
netcontrol internetcontrol critic_ecp flashoverride flash immediate
priority routine
.RE

.RS
.IP \fBip_tos.tos\fP
lowdelay throughput reliability
.RE

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 \fBlowdelay\fP on
external traffic:

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

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.

.SH AUTHENTICATION METHODS
The \fBDante\fP server supports the following authentication methods.
Some installations of \fBDante\fP may support only a subset of these,
depending on platform support.

.IP \fBnone\fP
This method requires no form of authentication.
.IP \fBusername\fP
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.
.IP \fBgssapi\fP
This method requires the setup of a Kerberos environment and can
provide strong encryption and authentication, depending on the
gssapi settings you choose.
.IP \fBrfc931\fP
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.
.IP \fBpam.address\fP
IP-based (rhosts) PAM authentication.
.IP \fBpam.any\fP
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.
.IP \fBpam.username\fP
Username/password-based PAM authentication.  Similar to the method
\fBusername\fP, but the information is passed to the PAM subsystem
for authentication, rather than \fBDante\fP using the system password
file directly.  When using PAM, be wary of memory leakages and
other bugs in the external PAM library \fBDante\fP will have to use on
your platform.
.IP \fBbsdauth\fP
This method requires the available client data to be verified by
the BSD Authentication system.  Similar to the method \fBusername\fP,
but passed to the BSD authentication system instead.

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

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

Each address, except the \fBexternal\fP address, can include an optional
\fBport\fP specifier.

.SH RULES
There are two sets of rules and they work at different levels.
Rules prefixed with \fBclient\fP are checked first and are used to
see if the client is allowed to connect to the \fBDante\fP server.
We call them "client-rules".
These rules will start with \fBclient pass\fP for a rule that allows
the client, or \fBclient block\fP 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
\fBsocks\fP and operate at the socks protocol level.

These rules will start with \fBsocks pass\fP for a rule that allows the
client, or \fBsocks block\fP 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 \fBpass\fP or \fBdeny\fP keyword.  The
\fBpass\fP/\fBdeny\fP 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
\fBfrom\fP/\fBto\fP address pair which gives the addresses the rule
will match.

In both contexts, \fBfrom\fP refers to the clients address, i.e.,
the address the client is connecting to the \fBDante\fP server from.
The \fBto\fP 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, \fBto\fP means the address the request is
accepted on, i.e., a address the \fBDante\fP server listens on.

In the socks-rule context, \fBto\fP means the client's destination
address, as expressed in the client's socks request.  I.e., the
address the \fBDante\fP 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:
\fBclientcompatibility\fP, \fBclientmethod\fP, \fBcommand\fP, \fBfrom\fP,
\fBgroup\fP, \fBsocksmethod\fP, \fBprotocol\fP, \fBproxyprotocol\fP,
\fBto\fP, \fBuser\fP.

The list of action keywords is: \fBbandwidth\fP, \fBlibwrap\fP,
\fBlog\fP, \fBsession\fP, \fBredirect\fP,
\fBtimeout.connect\fP, \fBtimeout.negotiate\fP, \fBtimeout.io\fP,
\fBtimeout.tcp_fin_wait\fP, and \fBudp.portrange\fP.

The format and content of the 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.

.IP
The contents of a \fBclient-rule\fP can be:
.IP \fBbandwidth\fP
The clients matching this rule will all share the given amount of bandwidth,
measured in bytes per second.  Requires the bandwidth module.
.IP \fBclientcompatibility\fP
Enables certain options for compatibility with broken clients.
Valid values are: \fBnecgssapi\fP, for compatibility with clients
implementing GSSAPI the NEC socks way.
.IP \fBfrom\fP
The rule applies to requests coming from the specified address.

.IP \fBgroup\fP
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 \fBDante\fP 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.

.IP \fBgssapi.enctype\fP
Which encryption to enforce for GSSAPI-authenticated communication.
Possible values are \fBclear\fP, \fBintegrity\fP, or \fBconfidentiality\fP.
The default is to accept whatever the client offers
except \fBclear\fP, as \fBclear\fP is not part of the SOCKS GSSAPI standard.
.IP \fBgssapi.keytab\fP
Value for keytab to use.  The default is "FILE:/etc/danted.keytab".
.IP \fBgssapi.servicename\fP
Which servicename to use when involving GSSAPI.  Default is "rcmd".

.IP \fBlibwrap\fP
The server will pass the specified parameter line to libwrap for execution.
.IP \fBlog\fP
Used to control logging.  Accepted keywords are \fBconnect\fP,
\fBdisconnect\fP, \fBdata\fP, \fBerror\fP, \fBioop\fP, and \fBtcpinfo\fP.
The default is no logging.
.IP \fBsession\fP
Control the max number of sessions or session establishment rate. See
below for details.
.IP \fBclientmethod\fP
Require that the connection be "authenticated" using one of the
given clientmethods.
.IP \fBpam.servicename\fP
Which servicename to use when involving pam.  Default is "danted".
.IP \fBport\fP
Parameter to \fBfrom\fP, \fBto\fP and \fBvia\fP.  Accepts the keywords
\fBeq/=, neq/!=, ge/>=, le/<=, gt/>, lt/<\fP 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.

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

The syntax of the redirect statement is
as follows:

.D1
\fBredirect\fP from: \fBADDRESS\fP

\".D1
\"\fBredirect\fP to: \fBADDRESS\fP

See the redirect manual for detailed information.

.IP \fBsocksmethod\fP
If the client offers more than one authentication method, \fBDante\fP will
select the method to use based on the order the methods are listed here.
Valid values are the same as in the global \fBsocksmethod\fP 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.

.IP \fBtimeout.negotiate\fP
See the global \fBtimeout.negotiate\fP option.
.IP \fBto\fP
The rule applies to requests going to the address given as value.
.IP \fBuser\fP
The user must match one of the names given as value.
If no \fBuser\fP value is given for a rule requiring usernames, the
effect will be the same as listing every user in the password file.

Note that if gssapi-based authentication is used, the username as provided
to the \fBDante\fP server normally includes the Kerberos domain.
The name must be listed on the same form here if it is to be used.

.IP
The contents of a \fBsocks-rule\fP can be:
.IP \fBbandwidth\fP
The clients matching this rule will all share the given amount of bandwidth,
measured in bytes per second.  Requires the bandwidth module.
.IP \fBbsdauth.stylename\fP
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.
.IP \fBcommand\fP
The rule applies to the given commands.  Valid commands
are \fBbind\fP, \fBbindreply\fP, \fBconnect\fP, \fBudpassociate\fP
and \fBudpreply\fP.  Can be used instead of, or to complement,
\fBprotocol\fP.  The default is all commands valid for the protocols
allowed by the rule.
.IP \fBfrom\fP
The rule applies to requests coming from the address given as value.
.IP \fBgroup\fP
The user must belong to one of the groups given as value.
.IP \fBlibwrap\fP
The server will pass the line to libwrap for execution.
.IP \fBlog\fP
Used to control logging.  Accepted keywords are \fBconnect\fP,
\fBdisconnect\fP, \fBdata\fP, \fBioop\fP, and \fBtcpinfo\fP.
.IP \fBsession\fP
Control the max number of sessions or session establishment rate. See
.IP \fBsocksmethod\fP
Require that the connection be established using one of the given
authentication methods.  A \fBmethod\fP normally refers to the socks
client part of the rule, and thus authenticates the client, and not
the target destination (see \fBcheckreplyauth\fP for information about
authentication the target destination).  Valid values are the same as in
the global \fBsocksmethod\fP line.
.IP \fBpam.servicename\fP
What servicename to use when involving pam.  Default is "danted".

.IP \fBport\fP
Parameter to \fBfrom\fP, \fBto\fP and \fBvia\fP.  Accepts the keywords
\fBeq/=, neq/!=, ge/>=, le/<=, gt/>, lt/<\fP 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.

.IP \fBprotocol\fP
The rule applies to the given protocols.  Valid values are
\fBtcp\fP and \fBudp\fP.  The default is all supported protocols that
can apply to the given \fBcommands\fP.
.IP \fBproxyprotocol\fP
The rule applies to requests using the given proxy protocol.
Valid proxy protocols are \fBsocks_v4\fP and \fBsocks_v5\fP.
The default is all supported proxy protocols.
.IP \fBredirect\fP
The source and/or destination can be redirected using the
\fBredirect\fP statement.
Requires the redirect module.

The syntax of the redirect statement is
as follows:

.D1
\fBredirect\fP from: \fBADDRESS\fP

.D1
\fBredirect\fP to: \fBADDRESS\fP

The semantics of \fBfrom\fP and \fBto\fP vary according to
\fBcommand\fP.  See the redirect manual for detailed information.

.IP \fBtimeout.connect\fP
See the global \fBtimeout.connect\fP option.
.IP \fBtimeout.io\fP
See the global \fBtimeout.io\fP option.
.IP \fBtimeout.tcp_fin_wait\fP
See the global \fBtimeout.tcp_fin_wait\fP option.

.IP \fBto\fP
The rule applies to requests going to or using the address given as value.
Note that the meaning of this address is affected by \fBcommand\fP.

.IP \fBudp.portrange\fP
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 \fBsocks-client\fP and the \fBDante-server for UDP
packets.  Note that this has no relation to the UDP port-range
used between the \fBDante-server and external, non-socks, clients/servers.
.IP \fBuser\fP
The user must match one of the names given as value.
If no \fBuser\fP value is given for a rule requiring usernames, the
effect will be the same as listing every user in the password file.
.SH SESSION
The \fBsession\fP 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; \fBsession.max\fP, that controls the
max number of sessions that can be matched, and
\fBsession.throttle\fP, 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 \fBsession.max\fP keyword takes a number corresponding to the
highest number of allowed simultaneous connections as an argument. The
\fBsession.throttle\fP 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 \fBsession.state.key\fP keyword is used
to control how the IP-address is determined. Currently two values are
supported, \fBfrom\fP and \fBhostid\fP. 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 \fBsession.state.key.hostindex\fP 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 \fBsession.inheritable\fP to \fBno\fP.

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

.SH 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:

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

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

.RS
.IP \fBfrom\fP
Normally specifies what SOCKS client addresses/networks to monitor.
.IP \fBto\fP
Normally specifies what target addresses/networks to monitor.
.IP \fBprotocol\fP
Can be used to restrict monitoring to a certain protocol (TCP, UDP or
both). Note: only TCP should be used for now.
.IP \fBhostid\fP
Can be used to restrict monitoring to only clients with a specific
hostid value set.
.IP \fBhostindex\fP
Used along with the hostid keyword to control which of the two
possible hostid values will be used when matching.
.RE

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.

.SS \fBData alarms\fP
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:

.RS
.IP \fBinternal.alarm.data.recv\fP
Data received on Dante's internal interface (data sent from the SOCKS clients to Dante).
.IP \fBinternal.alarm.data.send\fP
Data sent out on Dante's internal interface (data sent from Dante to the SOCKS clients).
.IP \fBexternal.alarm.data.recv\fP
Data received on Dante's external interface (data sent from the target servers to Dante).
.IP \fBexternal.alarm.data.send\fP
Data sent out on Dante's external interface (data sent from Dante to the target servers).
.RE

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:

\fBinternal.alarm.data.recv: DATALIMIT in INTERVAL\fP

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.

.SS 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:

.RS
.IP \fBinternal.alarm.disconnect\fP
Connections between SOCKS clients and the Dante server.
.IP \fBexternal.alarm.disconnect\fP
Connections between the Dante server and target servers.
.RE

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.

.SH ROUTES
The routes are specified with a \fBroute\fP 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:
.IP
At present serverchaining is only supported for the \fBtcp connect\fP command.
.IP
If the route specifies that a username/password-method should be offered
to the upstream proxy, \fBDante\fP will forward the username/password received
from it's own client to the foreign upstream proxy, meaning the
upstream proxy will receive the user's username and password in cleartext
from \fBDante.
.IP
At present serverchaining does not scale well in \fBDante\fP and should not
be used for anything but minimal client loads.


.SH EXAMPLES
See the example/ directory in the distribution.
.SH FILES
.nf
.ta \w 1
/etc/danted.conf   \fBDante\fP server configuration file.
/etc/passwd       systemfile used when doing standard username/password
                  authentication.
.fi
.SH AUTHORS
For inferno Nettverk A/S:
   Michael Shuldman
   Karl-Andre' Skevik
.SH SEE ALSO
danted(8), dante.conf(5), hosts_access(5)

.PP
Information about new releases and other related issues can be found
on the \fBDante\fP WWW home page: http://www.inet.no/dante/

Information about commercial support can be found on the
\fBDante\fP WWW support page: http://www.inet.no/dante/support.html