3 Client’s configuration

You need to create a configuration file for each client. Usually, large part of the file will be the same for all the clients. In most cases, you will only have to change the host VPN IP and the key and certificate paths.

The main source of documentation of the configuration file is its man page ‘campagnol.conf(5)’ which describes the full syntax and the options.

3.1 Configuration file

The easiest way is to start with the sample configuration file which describes every option. A few options are mandatory.

By default Campagnol uses ‘/etc/campagnol.conf’, an other config file might be used by giving its name as a command line argument.

This file has an INI-like syntax. Comments start with a ‘;’ or a ‘#’ and continue to the end of the line. Values may be quoted between double quotation marks ("...") and special characters can be escaped with ‘\’ (\\, \n, \# ...).

The configuration file has the following sections:

[NETWORK]: The public and local network related options such as the rendez-vous server address, the VPN MTU or the local interface.
[VPN]: This section defines the IP address and netmask used on the VPN.
[SECURITY]: All the DTLS-related parameters (key, certificates and CRL, …)
[CLIENT]: This section is used to adjust the client’s behavior.
[COMMANDS]: This section defines the commands executed when the TUN device is opened or closed.

3.2 Basic options

Every client will have to look at the following options. They should be enough for most setup.

[NETWORK]

‘local_host’: This option is used to define the local IP (or hostname). Leaving this option commented out enable the auto-detection of the IP. You should set this option if the host has several network interfaces.
‘server_host’: The IP address or hostname of the rendez-vous server.
‘server_port’: The UDP port of the rendez-vous server (the default is 57888).
‘interface’: The primary use of this option is to help with the auto-detection of the local IP (when ‘local_host’ is commented out) by giving the name of the interface to use. On Linux, this option also enable interface binding (the UDP socket is bound to this interface).
‘tun_device’: On Cygwin, this parameter is used to set the name of the TUN/TAP interface to use. If the parameter is not defined, the client will use the first adapter found.

[VPN]

‘vpn_ip’: The IP address for the VPN.
‘network’: The subnetwork for the VPN in CIDR notation (e.g. ‘10.0.0.0/24’). This value must be the same for all the clients of the VPN.

[SECURITY]

‘certificate’: The PEM file containing the public certificate.
‘key’: The PEM file containing the private key.
‘ca_certificates’: The PEM file containing a root certificate chain

3.3 Advanced configuration

[NETWORK]

‘local_port’

Set the local UDP port. Useful if you have some firewall or NAT rules to define.

‘tun_mtu’

This parameter set the MTU of the TUN device (i.e. the MTU of the VPN). It’s recommended to use the same value for all the clients although it’s not strictly required, unless you have an OpenBSD or NetBSD client in the network (it seems that their TUN driver doesn’t accept IP frames larger than the MTU). Using different MTU sizes has an impact on the performance.

The default value (1419) is the highest value which should yield packets smaller than 1500 bytes (the usual MTU for ethernet) whichever cipher algorithm is used (see section IP-layer VPN).

‘use_local_addr’

When enabled, this parameter allows the client to publish its local IP address and port. It is enabled by default. This option is required when several clients are behind a common NAT (see section Common NAT).

‘override_local_addr’

This parameter is used in conjunction with ‘use_local_addr’. It is used to override the local endpoint published by ‘use_local_addr’. See section Multiple levels of NATs.

‘tap_id’

For Cygwin only. This parameters defines the name of the TAP driver. The name is used when searching for TAP adapters. The Cygwin port of Campagnol was developed and tested with the “tap0901” driver but other versions may also work.

[SECURITY]

‘ca_certificate_dir’

To specify the CA root certificate chain, you can use either ‘ca_certificate’ or ‘ca_certificate_dir’. The latter is used with a directory name. This directory must contain all the required certificates and it must be prepared with the c_rehash OpenSSL’s utility.

It both ‘ca_certificate’ and ‘ca_certificate_dir’ are defined, ‘ca_certificate’ is searched first.

‘crl_file’

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’

The maximum depth for the certificate chain verification (default: 9).

‘cipher_list’

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. The syntax is explained in the openssl-ciphers(1) man page.

[CLIENT]

‘fifo_size’: The client uses one transmit and one receive queue per connection. This set the length of the queue (number of packets). The default is 20.
‘txqueue’: For Linux only. The length of the transmit queue of the TUN/TAP device. The current default value of the driver is 500 packets. Setting a smaller value is useful with a slow internet connection or with severe rate limiting since it will reduce the maximum latency.
‘tun_one_queue’: For 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. 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’: Limit the total outgoing traffic of the client. The value is in kilobytes/second.
‘connexion_max_rate’: Limit the outgoing traffic allowed for each connection. The value is in kilobytes/second.
‘timeout’: The inactivity timeout (in seconds) before closing a connection. All the clients should use the same timeout value but it’s not mandatory.
‘keepalive’: The client must send some keepalive messages when a connection is inactive to maintain the contexts in the traversed NATs and firewalls. This set the timeout before sending a keepalive message.
‘max_clients’: The maximum number of connections allowed.

[COMMANDS]

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.

See the man page ‘campagnol.conf(5)’ for a detailed description of this section and the default commands.

‘default_up’: Use the default commands when the TUN device is opened instead of the commands defined in this section.
‘default_down’: Use the default commands when the TUN device is closed instead of the commands defined in this section.
‘up’: Add a shell command to execute when the TUN device is opened and ‘default_up’ is false. The parameter can be specified multiple times.
‘down’: Add a shell command to execute when the TUN device is closed and ‘default_down’ is false. The parameter can be specified multiple times.

3.4 Main difficulties

3.4.1 Common NAT

 [peer A] ---|   |   (         )---|NAT|--- [peer C]
             |NAT|---( NETWORK )
 [peer B] ---|   |   (         )--- [RDV]

This configuration involves two clients A and B which are on the same network behind a common NAT.

If A sends a packet to B using B’s public endpoint (i.e. the associated port on the NAT and the NAT’s public IP), this will fail unless the common NAT does hairpin translation. Sadly hairpin translation is not a widely spread feature.

The two clients A and B must use their private endpoint. This is done by setting the option ‘use_local_addr’ in their configuration file (this is the default).

If the option is enabled, the rendez-vous server will tell them to use their local endpoint to reach each other. It will actually sees that they both have the same public IP thus are behind the same NAT equipment. This works around the problem and the NAT doesn’t need to do hairpin translation.

The two clients will sill use the public endpoints to talk with C.

3.4.2 Multiple levels of NATs

 [peer A] ---|NAT_A|---|     |   (         )
                       |NAT_C|---( NETWORK )
 [peer B] ---|NAT_B|---|     |   (         )--- [RDV]

In addition to a common NAT, this case involves at least one peer lying behind another level of NAT. With this configuration, the two clients A and B can’t talk to each other by using their private address.

A first method to connect A and B is to disable their ‘use_local_addr’ option (so that they won’t try to use their private addresses). It will work only if NAT_C supports hairpin translation.

The second method supposes that you can configure the inner NATs NAT_A and NAT_B. We need to use the ‘override_local_addr’ parameter in conjunction with the ‘use_local_addr’ parameter. It is used to send a fake local address to the rendez-vous server instead of the real one. So you can define static port forwarding rules on NAT_A and NAT_B and use ‘override_local_addr’ to publish the intermediate IP on NAT_A and NAT_B.

3.4.3 Non public rendez-vous server

              ---(         )   |   |--- [RDV (+ peer)]
  other peers ---( NETWORK )---|NAT|
              ---(         )   |   |--- [peer]

If the rendez-vous server is behind a NAT, you can’t run a client behind this NAT neither on the same host nor on another host. It is likely to fail since the rendez-vous server will not be able to see its public address and this would break the UDP hole punching. There is no solution for this setup.

This document was generated using texi2html 5.0.