The Linux Configuration File
All configuration for the Linux client as done via a configuration file which is passed to the Firedrill client as a single command line option when it is run. For example:
firedrill config-file.cfg
The description of the configuration file format and options given here assumes you are using the latest version of the Firedrill software. Some options may not be supported or may work differently in earlier versions.
Overview
The configuration file is split into sections, the start of which is denoted by the section name (in capital letters) within square brackets. At a minimum a complete configuration file must contain exactly one [GLOBAL] section and at least one [CLIENT] or [SERVER] section. If so desired you may configure multiple clients and/or servers by including additional [CLIENT] or [SERVER] sections, although this would probably only be useful in fairly advanced tunnelling scenarios.
Any lines in the configuration file after the start of the current section and before the start of a subsequent section are considered to be within that labelled section. A line may then either contain a configuration option for that section, be a comment, or be blank.
A configuration option line must not contain any whitespace at the start or end of the line, it must begin with the name of the option being specified (in lowercase), and any arguments for the option must be listed on the same line separated by single spaces.
A comment line must begin with a '#' and everything else on that line is ignored. A blank line must contain no other characters.
The [GLOBAL] section
The first section within the configuration file must be the [GLOBAL] section. This section may be empty, or may contain the following options:
debug <level>: This option controls the level of logging performed by Firedrill. The debug level can be between 0 (minimal logging) and 5 (verbose logging).
pidfile <pidfile file>: This option instructs Firedrill to create the specified file containing our PID at startup, and remove it again at shutdown.
nodaemon: This option instructs Firedrill not to run as a daemon (the default behaviour is for the Firedrill client to daemonize at launch).
dotest: This option instructs Firedrill to perform periodic tests on the connection to the other end of the tunnel so as to try and determine the best tunneling parameters to use. The testing enabled by this option is currently very experimental, and while it may help in some situations it is disabled by default.
The [CLIENT] section(s)
A [CLIENT] configuration file section specifies the behaviour of a Firedrill client side instance. This section may contain the following options:
fixed <host> <port> [udp]: This option tells the Firedrill client to configure a fixed (as opposed to SOCKS) HTTP tunnel. A fixed tunnel is one where the ultimate destination for tunnelled traffic is fixed for all time. The address and port for the ultimate tunnelled traffic destination is given by the <host> and <port> arguments. If a third argument of udp is specified, then Firedrill will tunnel UDP data instead of the normal TCP connections. A [CLIENT] section must contain either a 'fixed' configuration option or a 'socks' configuration option.
socks: This option tells the Firedrill client to run a SOCKS server for client applications to connect to and to create SOCKS HTTP tunnels. A SOCKS server allows connecting client applications to control where the ultimate destination for tunnelled traffic is on a connection by connection basis. SOCKS tunnels are therefore more flexible than fixed tunnels and generally easier to configure and use. A [CLIENT] section must contain either a 'socks' configuration option or a 'fixed' configuration option.
listen [<ip>] <port>: This option tells the Firedrill client what IP address and port it should listen for incoming connections from client applications on. If you do not specify an IP address here Firedrill will listen for incoming connections on any interface. If your are configuring a SOCKS tunnelling client you will probably want to specify the standard SOCKS port 1080 here.
tunsvr <host> [<port>]: This option tells the Firedrill client the address of the corresponding Firedrill server it should connect to. If you do not specify a port it will assume it should connect on the standard HTTP port 80.
proxy <host> <port>: This option tells the Firedrill client the address of an explicit proxy server it should route all traffic via.
proxyauth <user> <passwd>: This option tells the Firedrill client what username and password to use if the proxy it is routing via requires authentication. The same username and password is used for basic, digest or NTLM authentication. If you need to also specify a domain to which the user belongs (sometimes necessary if you are going via a Windows proxy requiring NTLM authentication), you can combine the domain name with the username using a '\'. For example; DomainName\UserName.
cliauth <user> <passwd>: This option tells the Firedrill client what username and password to use to authenticate itself at the Firedrill server.
ssl: This options tells the Firedrill client to create a secure encypted (SSL) tunnel between itself and the Firedrill server. Please note that the public Firedrill servers listen for incoming SSL connections on the standard HTTPS port 443, therefore you should use port 443 (instead of the default HTTP port 80) with the tunsvr config option if you wish to use secure tunnelling to one of our public servers.
The [SERVER] section(s)
A [SERVER] configuration file section specifies the behaviour of a Firedrill server side instance. If you are only configuring a Firedrill client to connect to one of our public Firedrill servers then you will not need one of these sections in your configuration file. If you wish to run your own Firedrill server however then this section may contain the following options:
listen [<ip>] <port>: This option tells the Firedrill server what IP address and port it should listen for incoming connections from Firedrill clients on. If you do not specify an IP address here Firedrill will listen for incoming connections on any interface. Typically you will probably want to specify a standard HTTP port here, such as 80 or 8080.
svrauth: This option tells the Firedrill server that it should only accept connections from Firedrill clients who successfully authenticate themselves. Only file based authentication is currently supported in the free version of Firedrill (see the user configuration option below). A version supporting MySQL based authentication may be purchased if required.
user <user> <passwd> <max tunnels> <max bandwidth>: This option allows you to specify the authentication details for connecting Firedrill clients. The <user> and <passwd> fields are the username and password for the connecting client and correspond to the <user> and <passwd> arguments to the cliauth option in the [CLIENT] configuration. The <max tunnels> field specifies the maximum number of active tunnels that user will be permitted to have running at once. The <max bandwidth> field specifies the total maximum bandwidth (in Kb/s) that user will be permitted to use over all their currently active tunnels. A value of 0 for either <max tunnels> or <max bandwidth> means there is no limit imposed for that user. Multiple users can be configured simply by including multiple user configuration lines.
denyips <ip>[,<ip>...]: This option tells the Firedrill server to block any attempts to create tunnels to the specified IP address(es). A limited form of wildcard is supported for addresses ending in .* (for example; 127.*).
denyports <port>[,<port>...]: This option tells the Firedrill server to block any attempts to create tunnels to the specified port(s).
ssl <certificate file> <private key file>: This option tells the Firedrill server to create a secure encrypted (SSL) tunnel between itself and any connecting Firedrill clients, and specifies the location of the SSL certificate file and private key file to use in negotiating the secure connection.
A complete example
Here we show a complete example configuration file for a Firedrill client. This example contains typical client configurations for a range of situations with comments to explain what is being done. The most commonly required scenario of a SOCKS HTTP tunneling client with a direct connection (ie; no explicit HTTP proxy in the way) to a Firedrill server is shown first.
##############################
## Example client configuration file.
##############################
##############
## Global options
##############
[GLOBAL]
# No global options specified
####################
## Client configuration
####################
# SOCKS client with direct connection to server. Client runs a SOCKS
# server on port 1080, the tunnel server endpoint is at tun1.fire-drill.com
# (default port 80), the HTTP tunneling server requires authentication:
[CLIENT]
socks
listen 1080
tunsvr tun1.fire-drill.com
cliauth MyUserName MyPasswd
# Basic client with direct connection to server. Client listens on
# port 2222, the tunnel server endpoint is on host nibbler port 80,
# ultimate traffic destination is host amy port 22, the HTTP tunneling
# server requires authentication:
#[CLIENT]
#fixed amy 22
#listen 2222
#tunsvr nibbler 80
#cliauth MyUserName MyPasswd
# Client going via explicit proxy. Client listens on port 2222,
# the tunnel server endpoint is on host nibbler (default port 80),
# ultimate traffic destination is host amy port 22, proxy is on host
# hermes port 8080, proxy requires authentication:
#[CLIENT]
#fixed amy 22
#listen 2222
#tunsvr nibbler
#proxy hermes 8080
#proxyauth ProxyUserName ProxyPasswd
# SOCKS client going via an explicit proxy. Client runs a SOCKS server
# on port 1080, the tunnel server endpoint is at tun2.fire-drill.com
# (default port 80, requires authentication), proxy is on host hermes
# port 8080:
#[CLIENT]
#socks
#listen 1080
#tunsvr tun2.fire-drill.com
#cliauth MyUserName MyPasswd
#proxy hermes 8080
# A fixed client tunneling UDP data. Client listens on UDP port 4000,
# the tunnel server enpoint is on host zap port 80, ultimate traffic
# destination is host amy UDP port 5000:
#[CLIENT]
#fixed amy 5000 udp
#listen 4000
#tunsvr zap 80
# SOCKS client with direct connection to server, using HTTPS secure
# tunneling. Client runs a SOCKS server on port 1080, the tunnel server
# endpoint is on host zap port 443, HTTP tunneling server
# requires authentication:
#[CLIENT]
#socks
#listen 1080
#ssl
#tunsvr zap 443
#cliauth MyUserName MyPasswd