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)