CAMPAGNOL.CONF

NAME

campagnol.conf - Campagnol VPN client configuration file

SYNOPSIS

/usr/local/etc/campagnol.conf

DESCRIPTION

campagnol(8) reads its configuration datas from /usr/local/etc/campagnol.conf (or another file specified in the command line).

This file has an INI-like syntax with extensions.

SYNTAX

Section name are written between square brackets ([ and ]). All the parameters written after a section declaration belong to that section. The remaining text on the line after the declaration is ignored. The white spaces around the section names are ignored. The name are case sensitive.

Comments start with a ‘;’ or a ‘#’ and continue to the end of the line.

Parameters are defined with the syntax ‘name = value’. The white spaces around the name and the value are stripped. The name are case sensitive.

Values may be quoted between double quotation marks. A quoted value can expand over multiple lines. A ‘\’ at the end of the line is treated as a line continuation. It is removed and the parser continue to read the value with the next line. Several quoted or unquoted values on the same line are concatenated.

Special characters in the section names, parameters and values can be escaped with ‘\’. The C escape sequences are accepted (\, \n, \xhh...) in addition to \#, \;, \[, \] and \=.

[SOME_SECTION]
  param        = value        # comment
  other_param  = a few words
  quoted_value = "some chars \t\"\#  "


[MULTILINE 1]
# The following definitions are equivalent
a = "aze rty uio"
b = aze " rty " uio
c = "aze"\
    " rty "\
    "uio"
d = aze\
    " rty "\
    uio
e = "aze\
 rty \
uio"



[MULTILINE 2]
# The following definitions are equivalent
a = "aze\n  rty\n uio"
b = "aze
  rty
 uio"
c = "aze\n"\
    "  rty\n"\
    " uio"

Inside a section, the syntax ${param} can be used to reference another value (param) from the same section. To protect a ‘${..}’ sequence from being expanded, it can be escaped with ‘$${..}’.

[SECURITY]
basedir = "/etc/campagnol_certs"
certificate = ${basedir}/cert.pem  # expands to
                                   # "/etc/campagnol_certs/cert.pem"
key = ${basedir}/key.pem           # expands to
                                   # "/etc/campagnol_certs/key.pem"

The configuration file defines the following sections:

PARAMETERS

This is a list of all the available parameters, with their default value if they are optional and their expected format.

[NETWORK] section
local_host = [IP address or hostname]

optional, default: search for a non local IP

This parameter set the local IP address used by campagnol. If it is left undefined, the local IP address will firstly be searched with the interface parameter. If interface is not set, the IP address will be the first non local IP found. Setting this parameter to “0.0.0.0” will work but it is not compatible with the use_local_addr option.

local_port = [port number]

optional, default: no port binding

Bind the local UDP socket to this port number.

server_host = [IP address or hostname]

mandatory

The rendezvous server hostname or IP address.

server_port = [port number]

mandatory

The rendezvous server port.

tun_mtu = integer

optional, default: 1419

This parameter set the MTU of the TUN device. This value must be the same on every clients.

It may be interesting to change the MTU of the tun device if you are running campagnol on a network with a unusual MTU. The default value is the highest value which should yield packets smaller than 1500 bytes (the usual MTU for ethernet) whichever cipher algorithm is used. The optimal value depends on the total overhead of campagnol. This is described in the source file include/communication.h.

interface = [a network interface name]

optional, default: no interface binding

This parameter is used to find the local IP address to use if the local_host parameter is not set. On cygwin, the intefaces’ names are as specified in the Network Connections settings panel.

LINUX ONLY: if this parameter is defined, the UDP socket is also bound to this interface.

use_local_addr = [yes/no]

optional, default: yes

This parameter allows the client to publish its local IP and UDP port. It’s useful if this client and others clients of the VPN are behind a common NAT:

[peer A] ---|   |
            |NAT|---(net)-- [RDV]
[peer B] ---|   |

In this configuration and if this parameter is enabled, the two peers will use their local IP and port to reach each other. Otherwise they will use their public address (as with the other clients of the VPN).

If peer A send a packet to peer B using its public address and port, the common NAT needs to do UDP hairpin translation which is not a widely implemented feature. By using the local address, the NAT doesn’t need to do hairpin translation so leaving this option to the default value is probably what most users want.

If the VPN configuration involves peers behind multiple level of NAT, see the next parameter override_local_addr. Disable this option only if you know what you are doing!

override_local_addr = “IP port”

optional, default: not enabled

This option is used to define the local IP that will be published to the rendezvous server (if use_local_addr is enabled). The format of the value is the IP address (or a hostname) and the port number, separated by spaces.

This option is useful when peers are behind multiple level of NATs:

[peer A] ---|NAT_A|---|   |
                      |NAT|---(net)-- [RDV]
        [peer B] -----|   |

In this case, the two peers are behind a common NAT but A is also behind another NAT. If A and B use their local IP to open a connection (use_local_addr enable), it will fail. If they use their public IP (use_local_addr disabled) it will work only if the common NAT does UDP hairpin translation.

With this parameter, you can send a fake local address to the rendezvous server instead of the real one. So another way to connect the two peers is to define a static port forwarding for A on NAT_A and to use override_local_addr to publish its intermediate IP address and port on NAT_A. When B tries to open a new connection with A, it will now use its address on NAT_A.

tun_device = [Name of the TUN interface]

optional, default: none

CYGWIN - The name of the TUN/TAP adapter to use (as it appears in Windows’ "Network Connections" panel). If this is not defined, the first adapter found is used.

LINUX - Give this name to the TUN interface. If the parameter is not defined, the default name is similar to "tun0" (the number is incremented as needed).

tap_id = [Name of the OpenVPN’s TAP driver]

optional, default: tap0901

CYGWIN ONLY - This parameters defines the name of the TAP driver. This is used to search for TAP adapters. The Cygwin port of Campagnol was developed and tested with the “tap0901” driver but other versions may also work.

[VPN] section
vpn_ip = [IP address]

mandatory

The IP address for the VPN.

network = [netmask in CIDR notation]

mandatory

The subnetwork for the VPN. This value must be the same for all peers. It’s given using the CIDR notation, for example “10.0.0.0/24”.

[SECURITY] section
certificate = path

mandatory

The PEM file containing the client’s X.509 certificate.

The PEM file containing the client’s private key.

ca_certificates = path

optional, default: none

The PEM file containing the root certificates chain in PEM format. This file can contain several CA certificates. Also see the next parameter ca_certificates_dir.

ca_certificates_dir = path

optional, default: none

A directory containing the root certificates in PEM format. This directory must be prepared with the c_rehash OpenSSL’s utility. See SSL_CTX_load_verify_locations(3) for a description of the format. At least one of ca_certificates and ca_certificates_dir must be defined. If both are defined, ca_certificates is searched first.

crl_file = path

optional, default: none

A PEM file containing a certificate revocation list (CRL). When a new connection is opened, the remote peer’s certificate is checked against this CRL.

verify_depth = integer

optional, default: 9 (OpenSSL’s default)

This parameter defines the maximum depth for the certificate chain verification.

cipher_list = [OpenSSL’s cipher list]

optional, default: OpenSSL’s default

The OpenSSL ciphers lists to use. If this value is defined, then it must be the same for every clients of the VPN, or at least the values must be compatible. openssl-ciphers(1) explains the syntax for this parameter and how to determine a cipherlist.

[CLIENT] section
fifo_size = integer

optional, default: 20

The internal queue length of Campagnol. The client uses one transmit and one receive queue.

txqueue = integer

optional, default: 500

LINUX ONLY - The length of the TX queue of the TUN/TAP device. If the parameter is not set, the default value of the driver is used. This sets the same value than the txqueuelen parameter of ifconfig. Set this parameter to a smaller value if running with a slow ethernet connection or with severe rate limiting.

tun_one_queue = [yes/no]

optional, default: no

LINUX ONLY - Set the TUN/TAP driver in single queue mode. When running in single queue mode, the TUN/TAP driver drops the packets by itself when its internal queue is full instead of rescheduling the packets. The size of the internal queue is also set with the txqueue parameter. This mode is required to work around a bug in pre-2.6.11 kernels. It may also help on slow hardware or with slow connection speed since it will de facto reduce the maximum transmit queue length.

client_max_rate = float

optional, default: not enabled

This option allows to limit the outgoing traffic for the whole client. The value is in kilobytes/seconds. If this parameter is commented out or set to 0, it is disabled.

connection_max_rate = float

optional, default: not enabled

This option allows to limit the outgoing traffic for each connection to other peers. The value is in kilobytes/seconds. If this parameter is commented out or set to 0, it is disabled.

timeout = integer

optional, default: 120 seconds

This set the inactivity timeout before closing a session. The value is given in seconds. It’s better to ensure that all the clients share the same value for this option.

keepalive = integer

optional, default: 10 seconds

This set the interval the client waits before sending a keepalive message to another client when the connection is inactive. This is required to maintain the contexts of the involved NATs and firewalls.

max_clients = integer

optional, default: 100

The maximum number of simultaneously opened connections with other clients.

[COMMANDS] section
This section defines the programs that are launched when the TUN device is opened or closed. It can be used to configure the TUN device with ifconfig, set the MTU, add a route, open some port on the firewall...

Campagnol can also execute some platform-dependent default commands to setup the interface, its MTU and add a route.
default_up = [yes/no]

optional, default: yes

Use the default commands when the TUN device is opened instead of the commands defined in this section.

default_down = [yes/no]

optional, default: yes

Use the default commands when the TUN device is closed instead of the commands defined in this section.

up = shell command

optional, default: platform-dependent

A shell command executed when the TUN device is opened and default_up is false. This parameter can be defined multiple times.

Inside the command, the following special variables are available:

down = shell command

optional, default: platform-dependent

A shell command executed when the TUN device is closed and default_down is false. This parameter can be defined multiple times.

The same spacial variables are available.

This is the default up commands for Linux:

up = "ifconfig %D %V mtu %M up"
up = "ip route replace %N via %V || route add -net %N gw %V"

This is the default up commands for FreeBSD and NetBSD:

up = "ifconfig %D inet %V %V mtu %M up"
up = "route add -net %N %V"

This is the default up commands for OpenBSD (note that you do not need to manually set the MTU with ifconfig for OpenBSD):

up = "ifconfig %D inet %V %V up"
up = "route add -net %N %V"

This is the default up command for Cygwin (note that the MTU is already set by Campagnol by changing its value in the registry):

up = "netsh interface ip set address name=%D static %V %n none"

There is no default down command on Linux, OpenBSD and Cygwin.

This is the default down command for FreeBSD and NetBSD:

down = "ifconfig %D destroy"

SEE ALSO

campagnol(8), campagnol_rdv(8), openssl-ciphers(1)

AUTHORS

Florent Bondoux <fbondoux@users.sourceforge.net>