bionic (5) danted.conf.5.gz

Provided by: dante-server_1.4.2+dfsg-2build1_amd64 bug

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.

              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 if it is  to
              be used.

              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

SEE ALSO

       danted(8), dante.conf(5), hosts_access(5)

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

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

                                                  July 29 2013                                    DANTED.CONF(5)