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