barefoot   Frontpage - Barefoot - Download - Usage - Status - Support - Modules - Docs - Links - Survey

Manual Page: BAREFOOTD.CONF(5)

BAREFOOTD.CONF(5)             File Formats Manual            BAREFOOTD.CONF(5)

       barefootd.conf - Barefoot server configuration file syntax

       The configuration file for the Barefoot 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 #.

       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:

       method A list of acceptable authentication methods for rules, listed in
              order of preference.  These are authentication methods that are
              to be checked immediately after the client has connected to

              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

              The default value for this keyword is none, meaning no
              authentication will be required.  Normally you should not need
              to set this keyword, as Barefoot will set it to the correct
              value by it self.

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

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

              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(s) 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: 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.

              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.

              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.

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

              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 Barefoot bind extension is enabled for the ftp-

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

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

              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:

                     Any error related to no route.

                     Any error related to DNS/hostname-resolving.

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

              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).

              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).

              This keyword allows you to configure a few options that relate
              to the srchost, i.e., the host the Barefoot 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.

              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.
              The number of seconds an established connection can be idle.
              The default is 0, meaning forever.  See also the "-n" option in
              the barefootd(8) manpage.

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

              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.

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

              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

              On platforms providing a privilege-model supported by Barefoot,
              the Barefoot 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 Barefoot server to appropriate
              values.  The Barefoot server can use two different userids, or
              three if compiled with libwrap support.  They are as follows:

              Username which will be used for doing privileged operations.  If
              you need special privileges to read the barefootd.conf file or
              to write the file (you can create it manually
              before starting barefootd), 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 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 used to execute libwrap commands.  Normally this should be
              the same as user.unprivileged

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

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

              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.

       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,

              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

       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

                     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:

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

                     netcontrol internetcontrol critic_ecp flashoverride flash
                     immediate priority routine

                     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

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

       none   This method requires no form of authentication.

       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.

              IP-based (rhosts) PAM authentication.

              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.

       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

       Rules are used to see if the client is allowed to connect to the
       Barefoot server.

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

       Rules include a pass or deny keyword.  The pass/deny keyword determines
       whether connections matching the rule are to be passed through or be

       The rules also specify a from/to address pair which gives the addresses
       the rule will match.

       In rules, from refers to the clients address, i.e., the address the
       client is connecting to the Barefoot server from.  The to address
       refers to the address the request is accepted on, i.e., a address the
       Barefoot server listens on.

       Rules are evaluated on a "first match is best match" basis.  That
       means, the first rule matched for a particular client 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: from, group, method, protocol, , to,

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

              The contents of a rule can be:

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

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

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

              The server will pass the specified parameter line to libwrap for

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

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

       method Require that the connection be "authenticated" using one of the
              given methods.

              Which servicename to use when involving pam.  Default is

       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.

              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.

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

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

       The 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.

       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: to: 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

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

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

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

       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.

       Currently 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.

       Adding an 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:

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

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

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

                     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

       The syntax is as follows: 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

       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.

       The second type of alarms is related to connection disconnections 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:

                     Connections between SOCKS clients and the Dante server.

                     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

       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.

       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
       socks.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 socks.conf(5) for information about the route

       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

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

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

       See the example/ directory in the distribution.

       /etc/barefootd.conf   Barefoot server configuration file.
       /etc/passwd       systemfile used when doing standard username/password

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

       barefootd(8), hosts_access(5)

       Information about new releases and other related issues can be found on
       the Barefoot WWW home page:

       Information about commercial support can be found on the Barefoot WWW
       support page:

                                December 8 2013              BAREFOOTD.CONF(5)

Copyright © 1998-2018 Inferno Nettverk A/S