|
| |
Manual Page: BAREFOOTD.CONF(5)
BAREFOOTD.CONF(5) File Formats Manual BAREFOOTD.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,
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:
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
Barefoot.
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.
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
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(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: 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.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 Barefoot 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 Barefoot 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.
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).
srchost
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.
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 barefootd(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.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.
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. If
you need special privileges to read the barefootd.conf file or
to write the barefootd.pid 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.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 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
information.
bandwidth
The bandwidth module gives control over how much bandwidth the
Barefoot 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 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.
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.
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
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
blocked.
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,
user.
The list of action keywords is: bandwidth, libwrap, log, session,
redirect, timeout.connect, timeout.io, and timeout.tcp_fin_wait.
The contents of a 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.
from The rule applies to requests coming from the specified address.
group The user must belong to one of the groups given as value.
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.
method Require that the connection be "authenticated" using one of the
given methods.
pam.servicename
Which servicename to use when involving pam. Default is
"barefootd".
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.
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.
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.
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 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.
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:
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
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
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, 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.
EXAMPLES
See the example/ directory in the distribution.
FILES
/etc/barefootd.conf Barefoot 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
barefootd(8), hosts_access(5)
Information about new releases and other related issues can be found on
the Barefoot WWW home page: http://www.inet.no/barefoot/
Information about commercial support can be found on the Barefoot WWW
support page: http://www.inet.no/barefoot/support.html
December 8 2013 BAREFOOTD.CONF(5)
| |
