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

Manual Page: BAREFOOT.CONF(5)

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



NAME
       barefootd.conf - Barefoot server configuration file syntax

DESCRIPTION
       The configuration file for the Barefoot server controls both access
       controls and logging.  It is divided into three parts; server settings
       and 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 it's value by a ':' character.

       child.maxidle
              Maintains a rough maximum on how many children of each type can
              remain idle waiting for clients.  This is used to reduce the
              amount of idle processes after a "client burst" has passed.  The
              default is yes (maintain a maximum on how many processes can be
              idle), which is the recommended value for optimal resource
              usage.

              It can be set to no if it is desirable to never shut down idle
              processes.  This can be used if client bursts are frequent and
              it is important to serve them as fast as possible, with no delay
              waiting for new server processes to be created, or to see how
              many processes were used to handle the peak load.


       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 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.rotation
              If more than one external address is given, this governs which
              address is selected as the source address for outgoing
              connections to a given destination.  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.

              same-same indicates the source address for a given destination
              should be the same address as the Barefoot server accepted the
              clients connection 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).


       socket This keyword allows you to configure a few low-level socket
              options that relate to the socket buffers the Barefoot server
              will use when communicating with clients and target hosts.  Note
              that these buffers will normally use kernel memory and the
              kernel may or may not honour the Barefoot server's request.

              Normally there should be no need to set these values, and the
              default values should suffice.

              The keywords you can set are socket.recvbuf.udp,
              socket.sendbuf.udp, socket.recvbuf.tcp, socket.sendbuf.tcp.

              These control what socket buffersize the Barefoot server will
              ask the kernel to use for the sockets.  The numeric argument
              given to the keyword indicates the size of the socket buffer in
              bytes.  You can set different values depending on the protocol
              (tcp or udp), and on whether it is for receving (recvbuf) or
              sending (sendbuf) data.


       srchost
              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 UDP-replies matches that which is set in the
              rule.  Authentication possibilities are limited to pam (using
              only the IP address and port number).  Default is to not 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 86400 (24 hours).  Set it to 0 for forever.  See
              also the "-n" option in the barefootd(8) man page.

              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.tcp_fin_wait
              The timeout for the equivalent of TCP's FIN-WAIT-2.


       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.


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


       user.privileged
              Username which will be used for doing privileged operations.  On
              many systems, this will need to be root as barefootd wants to
              open a raw socket to receive ICMP errors for sent UDP packets.

              If barefootd is unable to open a raw socket it will have to rely
              on the configured UDP timeout to delete UDP-sessions, which on a
              busy server might mean it will have reject new UDP clients, even
              though older clients have terminated without the barefootd
              server knowing due to no raw socket.


       user.unprivileged
              User which the server runs as most of the time.


       user.libwrap
              User used to execute libwrap commands.



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.
       Each address can be followed by an optional port specifier.


RULES
       Rules start with either the client pass or client block keyword and
       control whether clients are allowed to connect to the Barefoot server
       or not.

       All rules need to include a from/to address pair which gives the
       addresses the rule will match.  In addition, if the rule is a pass
       rule, a bounce to keyword and address must be given.

       from means the clients address.

       to means the address the requests are accepted on, i.e. the address the
       Barefoot server listens on.

       bounce to means the address the data from the client should be
       forwarded, or bounced, to.

       In addition to these addresses there is a set of optional keywords that
       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, the actions are executed.

       The complete list of condition keywords is: from, to, method, and
       protocol.

       The list of action keywords is: bounce to, libwrap, log,
       timeout.connect,  and timeout.io.


              The meaning of the keywords is as follows:

       bounce to
              Clients matching this rule will have their data bounce to the
              given address.

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


       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 and iooperation.  The default is no
              logging.


       method Require that the connection is "authenticated" using one of the
              given methods. Supported values are none, rfc931 and pam. The
              client has no way to specify a password, limiting the PAM
              modules that can be used to mainly host based authentication.


       pam.servicename
              Which servicename to use when involving pam.  Default is
              "barefootd".


       protocol
              The rule applies to the given protocols.  Valid values are tcp
              and udp.  The default is all supported protocols.


       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.


       timeout.connect
              See the global timeout.connect option.

       timeout.io
              See the global timeout.io option.


       to     The rule applies to requests going to the specified address.

              Limit the number of active sessions allowed by this rule.


ROUTES
       The routes are specified with a route keyword and can be used to
       forward a connection attempt via a supported proxy protocol.  A set of
       keywords control the behavior of the route command, with these keywords
       placed inside a pair of parenthesis ({}).  Each route can contain three
       address specifications; from, to and via.  A route is selected for a
       connection based on the values within the route block.

       When searching for a route to match the clients request, the library
       will first look for a direct route.  Then for a socks_v5 route, a
       socks_v4 route, and lastly for a http route.

       Depending on how the library is configured, there may or may not be an
       automatic fallback to an auto-generated direct route if no other route
       is found.

       The route block can contain the following:


       ADDRESSES
              Each address field can consist of an IP address (and where
              meaningful, a netmask, separated from the IP address by a '/'
              sign), a hostname, a domainname (designated by the leading '.'),
              or an interface name (where meaningful).  Each address can be
              followed by a optional port specifier.


       from   The route is used only for requests coming from the address
              given as value.

       to     The route is used only for requests going to the address given
              as value.

       via    Address of the proxy server that should be used as a gateway for
              the connection, or the special value direct to indicate the
              connection should be made directly rather than by going via a
              proxy server.


       port   Parameter to from, to and via.  Accepts the keywords eq/=,
              ne/!=, 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
              #>.



       Options

       command
              The server supports the given commands.  Valid commands are
              connect, udpassociate and udpreply.  The default is all commands
              supported by the protocols set for the route.  Can be used
              instead of, or to complement, protocol.

       method List of authentication methods the client supports and should
              offer to the proxy server.  Currently supported values are none
              and username.  The default is all supported methods.

       protocol
              The protocols the server supports.  Supported values are tcp and
              udp.  The default is all supported protocols.

       proxyprotocol
              The proxy protocols the server supports.  Currently supported
              values are socks_v4, socks_v5, and http.  The default is
              socks_v4 and socks_v5.  Note that if with SOCKS, if the proxy
              server requires any form of authentication, it is necessary to
              explicitly set this value to socks_v5 because SOCKSv4 does not
              support authentication.


EXAMPLES
       See the example/ directory in the distribution.

FILES
       /etc/barefootd.conf
       Barefoot server configuration file.

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

SEE ALSO
       barefootd(8), hosts_access(5) Information about new releases and other
       related issues can be found on the WWW home page:
       http://www.inet.no/barefoot/



                                February, 2011                BAREFOOT.CONF(5)



Copyright © 1998-2018 Inferno Nettverk A/S