Server setup

This page describes a typical server configuration, offering basic port bouncing functionality.

The configuration described in this document is not the smallest possible configuration, but is structured to make debugging and later extension easy. Each section of the server configuration file is discussed separately. The complete file is listed at the end of the page. Subsequent pages build on the minimal configuration listed here.

Usage scenario

The configuration described in this document corresponds to the usage scenario of having a Barefoot server available from the Internet, with several addresses bound by the Barefoot server being bounced to other machines. These other machines are assumed to be accessible from the Barefoot server, but inaccessible from the Internet.

Three services are bounced via Barefoot in the example configuration described here: HTTP (TCP), HTTPS (TCP, and DNS (UDP). Clients from the 10.0.0.0/8 network are specifically denied access to the HTTP server, traffic from all other clients are forwarded. TCP connections are additionally made via a SOCKS server at the IP-address 192.0.2.1.

External clients only need to be able to reach the Barefoot server. The communication between the Barefoot server and the machines running the actual services is not visible to the external clients, nor is there any way for the external clients to talk directly with the machines running the actual services.

Configuration file sections

The standard name for the Barefoot configuration file is /etc/barefootd.conf and this file controls the behavior of the server. The first part of the file contains global options such as log files and server identities. The second part specifies the rules that determine how the server should forward data. An optional third part may contain routing rules for relaying forwarded connections through a supported proxy server.

Global options

A configuration file should start with this section, which can have many different elements. Only mandatory and most likely to be needed fields are described here, the manual should be consulted for a full overview.

Logging

logoutput: /var/log/barefootd.log
#debug: 1

These statements control the logs generated by the server, with logoutput specifying the file that the logs are written to. It is possible to also send log output via syslog, or stdin/stdout. The commented out debug keyword can be enabled to increase the verbosity of the information written to the logfile, but should only be needed to diagnose problems.

The rules later in the configuration include additional log statements that can be commented out to provide more information on specific actions performed by the server.

Server address specification

#address specification (source address for bounced traffic)
external: eth1

The external keyword is used to specify the addresses that the Barefoot server should use when bouncing/forwarding traffic. This will become the source address of the traffic relayed by the Barefoot server. The argument can be an IP address, an interface name as in the example above, or a hostname.

Server identities

#server identities (not needed on Solaris)
#user.privileged    : root
user.notprivileged : barefoot
#user.libwrap       : libwrap

NOTE: This section is not used on Solaris, where the Solaris privilege API is used instead.

For platforms other than Solaris, these keywords specify the identities that the Barefoot server should use for different types of operations. We recommended that a special user, such as barefoot, is created for this purpose.

Special privileges will usually be needed to bind to ports below 1024, and to receive ICMP error messages for UDP traffic, which can aid in freeing up resources related to UDP clients that are no longer active.

In scenarios such as the one described here, where the only privileged operation that the server needs to perform is to bind to privileged ports, it is sufficient to start the barefoot server as root and set the user.notprivileged keyword to ensure that the Barefoot server changes to this user after having bound the ports.

The user.libwrap user can be specified if libwrap is used in the configuration (for e.g., RFC931 username lookups).

Reverse DNS

#no reverse dns lookup
#srchost: nodnsmismatch

If domain names are used for access control in the server forwarding rules, it might be useful to set the global srchost option to the value nodnsmismatch, which will use a reverse-DNS lookup to verify that the IP-address actually belongs to the domain. The default behavior is to not do this reverse lookup, and it is not enabled in this configuration example either.

Note that many machines on the Internet lack proper reverse host names.

Authentication methods

#no authentication methods
clientmethod: none

There is limited room for authentication in a port bouncer such as Barefoot, but possible approaches are covered in the authentication page.

Setting clientmethod: none explicitly specifies that authentication should not be used (which is the default).

Interaction with libwrap

If compiled with libwrap, it is possible to use several of the operations provided by the libwrap library in Barefoot, such as access control based on /etc/hosts.allow. This is covered in more detail in the libwrap page.

Barefoot rules

The forwarding operation of the Barefoot server is controlled by the Barefoot client rules, which are used to determine whether a given connection or packet should be forwarded or blocked.

#block http from the 10.0.0.0/8 network
client block { 
        from: 10.0.0.0/8 to: eth1 port = http
        protocol: tcp
        log: connect disconnect error # iooperation data
}

#bounce http (unless matched by block rule above)
client pass { 
        from: 0.0.0.0/0 to: eth1 port = http
        bounce to: internal.example.org port = http
        protocol: tcp
        log: connect disconnect error # iooperation data
}

#bounce https
client pass {
        from: 0.0.0.0/0 to: eth1 port = https
        bounce to: internal2.example.org port = https
        protocol: tcp
        log: connect disconnect error # iooperation data
}

#bounce dns
client pass {
        from: 0.0.0.0/0 to: eth1 port = domain
        bounce to: dns.example.org port = domain
        protocol: udp
        log: connect disconnect error # iooperation data
}

These four rules show examples of bouncing traffic for three different protocol/port pairs to three different internal machines.

The value of the from keyword is matched against the source address of the client, and the value of the to keyword against the destination address, which is the Barefoot server. For each rule, the Barefoot server will bind to the address corresponding to the address given in the to field, using the specified protocol.

The rules determine the port numbers to which the server binds. Each UDP packet/incoming TCP connection is then matched sequentially against the rules, until one matches. A match will result in the data being redirected to the value of the bounce to keyword if the rule is a client pass rule and dropped otherwise.

UDP packets are simply retransmitted, with the value of the global external keyword as the new source address. For TCP, a new TCP connection is established to the specified destination, having the value of the global external keyword as the source address.

Connections or packets that do not match any of the rules will not be forwarded, but can be logged if desirable.

The above client pass rules match all source addresses, due to the source (from) address specifications all being 0.0.0.0/0, but the rule syntax supports a full range of network value types, allowing one to limit the addresses clients will be accepted from. One can specify a subnet (such as 10.0.0.0/8), a single address (192.0.2.22), a host name (ftp.example.org), or a domain name (.example.org). A domain name specification will match any host in that domain. The client block rule only blocks connections from the specified network.

The iooperation and data keywords have been commented out in the log keywords, but can be added if additional logging is desired. The current configuration logs connections being established and ending, in addition to errors, but not data transmissions.

Proxy based forwarding

In addition to simply forwarding data directly, Barefoot supports forwarding via a proxy server. The route statement below shows how a Barefoot server can be configured in this way. Note that forwarding of UDP is currently not supported. The protocol keyword is used in the example to illustrate this by specifying that only TCP traffic should be forwarded.

Connections can be forwarded via SOCKS (version 4 and 5), or HTTP proxies supporting (and allowing) the CONNECT operation.

#forward TCP connections via SOCKS server
route {                                                                        
        from: 0.0.0.0/0 to: 0.0.0.0/0 via: 192.0.2.1 port = 1080            
        proxyprotocol: socks_v4 socks_v5
        protocol: tcp #udp not supported
        method: none
}

The route statements are applied to matching client pass rules, meaning TCP connections from clients with a from address matching the from address in the route, and a bounce to address matching the to address in the route. When bouncing data from these clients, the data bounced is forwarded via the SOCKS server specified in the matching route. The SOCKS server will then establish the connection to the address specified in the bounced to keyword.

Data will thus pass from the client, to the Barefoot server, to the proxy, and finally to the remote server.

The route statement in the example above will cause all bounced TCP connections to be forwarded via the SOCKS server at 192.0.2.1, due to the use of wildcard addresses in both the from and to keywords.

Using authentication when connecting to a SOCKS server is possible, but not currently supported. For this reason it is recommended to disable authentication, by specifying method: none.

Full configuration

Combining the statements described above results in the following server configuration:

logoutput: /var/log/barefootd.log
#debug: 1

#address specification (source address for bounced traffic)
external: eth1

#server identities (not needed on Solaris)
#user.privileged    : root
user.notprivileged : barefoot
#user.libwrap       : libwrap

#no reverse dns lookup
#srchost: nodnsmismatch

#no authentication methods
clientmethod: none

##
## Barefoot rules
##

#block http from the 10.0.0.0/8 network
client block { 
        from: 10.0.0.0/8 to: eth1 port = http
        protocol: tcp
        log: connect disconnect error # iooperation data
}

#bounce http (unless matched by block rule above)
client pass {
        from: 0.0.0.0/0 to: eth1 port = http
        bounce to: internal.example.org port = http
        protocol: tcp
        log: connect disconnect error # iooperation data
}

#bounce https
client pass {
        from: 0.0.0.0/0 to: eth1 port = https
        bounce to: internal2.example.org port = https
        protocol: tcp
        log: connect disconnect error # iooperation data
}

#bounce dns
client pass {
        from: 0.0.0.0/0 to: eth1 port = domain
        bounce to: dns.example.org port = domain
        protocol: udp
        log: connect disconnect error # iooperation data
}

#forward TCP connections via SOCKS server
route {                                                                        
        from: 0.0.0.0/0 to: 0.0.0.0/0 via: 192.0.2.1 port = 1080            
        proxyprotocol: socks_v4 socks_v5
        protocol: tcp #udp not supported
        method: none
}