Use cases

Intended setup

public RDV, NATted peers

Several clients are connected to Internet. They optionally lie behind a NAT and those NAT must accept UDP hole punching.
The rendezvous server has a public IP or may also be configured behind a NAT. It sees the public endpoints of the clients which is enough thanks to the hole punching.

Corner case 1: common NAT

peers behind a common NAT

Here two clients are behind a common NAT. If one sends a packet to the other using its public address, it will fail unless the common NAT does hairpin translation. Sadly hairpin translation is not a widely spread feature.

If both peers enabled the option use_local_addr in their configuration file (which is the default), then the RDV server will tell them to use their local IP to reach each other (the RDV server 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. There is no problem with the other peers of the VPN.

Corner case 2: multiple level of NATs

peers behind multiple levels of NAT

This case involves a common NAT but also at least one peer lying behind another level of NAT.

A first method to connect the two is to disable their use_local_addr option (so that thet won't try to use their private addresses). It will work only if the common NAT supports hairpin translation.

Another method is to use the override_local_addr parameter in conjunction with the use_local_addr parameter explained above. It is used to send a fake local address to the RDV server instead of the real one. So you can define static port forwarding rules on the internal NATs and use this parameter to publish the intermediate IP after the internal NATs.

Corner case 3: rendezvous server and client behind a NAT

RDV + peer behind a NAT

If the RDV 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 RDV server will not be able to see its public address.

Installation

Dependencies

The client requires a recent version of the OpenSSL library. DTLS support was introduced in OpenSSL 0.9.8 but Campagnol requires at least 0.9.8j. The latest version is always a good choice. The client also requires the TUN/TAP driver.

Build

  1. $ ./configure
  2. $ make
  3. # make install

But you should first have a look at the configuration options with ./configure --help.
If you don't have pkg-config or if you have installed OpenSSL in a non standard directory, you should have a look at the --with-openssl* options. For instance if you want to use an /usr/local based openssl, run:

  1. $ ./configure --with-openssl=/usr/local

If you do not want to build the RDV server or the client, you can use the options --disable-server and --disable-client.

Configuration

You have to edit the configuration file shipped with the client. A few options are mandatory. The configuration 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 white-spaces around the section names, the parameters and the values are stripped. All names are case sensitive.

See the man page for the meaning of the parameters.

Here is a sample configuration file.

  1. #
  2. # Campagnol VPN example configuration file
  3. #
  4. # See the campagnol.conf(5) man page for a complete description of the
  5. # parameters.
  6. #
  7.  
  8. [NETWORK]
  9.  
  10. # Local hostname or IP address
  11. # optional
  12. # default: search for a non local IP possibly using the "interface" parameter.
  13. #local_host = 192.168.0.4
  14. # Using 0.0.0.0 will work but is incompatible with the "use_local_addr" option.
  15. #local_host = 0.0.0.0
  16.  
  17. # Local UDP port number
  18. # optional
  19. # default: no port binding
  20. #local_port=44556
  21.  
  22. # Allow the use of the local IP and UDP port.
  23. # optional
  24. # default: yes
  25. # This option is useful if this client and other clients of the VPN are behind
  26. # the same NAT. See campagnol.conf(5).
  27. # Disable this option only if you know that it's not necessary and you know what
  28. # you are doing!
  29. #use_local_addr = no
  30.  
  31. # Override the local address sent to the RDV server (use_local_address = yes)
  32. # optional
  33. # default: not enabled
  34. # In some special case, it may be usefull to use another address (for example
  35. # the public address on a NAT) instead of the real local address. See
  36. # campagnol.conf(5).
  37. #override_local_addr = 172.16.17.17 23456
  38.  
  39. # Rendezvous server hostname or IP address
  40. # mandatory
  41. server_host = 192.168.0.1
  42.  
  43. # Rendezvous server port
  44. # optional
  45. # default: 57888
  46. #server_port = 34567
  47.  
  48. # MTU of the TUN device
  49. # optional
  50. # default: 1419
  51. # This parameter must be the same for all peers
  52. # It may be interesting to change the MTU of the tun device if
  53. # you are running campagnol on a network with a unusual MTU.
  54. #tun_mtu = 1400
  55.  
  56. # Use a specific network interface
  57. # optional
  58. # This parameter is used to find the local IP address to use if the "local_host"
  59. # parameter is not set.
  60. # Linux only: if given, the UDP socket is bound to this interface.
  61. # default: no interface binding
  62. #interface = eth0
  63.  
  64. # Linux:
  65. # Give the name after-specified to the TUN device.
  66. # default: the interface is named tun%d
  67. # Cygwin:
  68. # The name of the TUN/TAP adapter to open.
  69. # default: open the first TUN/TAP adapter found.
  70. # Other OS: this parameter is ignored.
  71. #tun_device = "Local Area Connection 3"
  72.  
  73. # Cygwin only:
  74. # The name of the OpenVPN's TUN/TAP driver.
  75. # This is used to search for TUN/TAP adapters.
  76. # default: tap0901
  77. # It may work with other versions.
  78. #tap_id = "tap0801"
  79.  
  80.  
  81. [VPN]
  82.  
  83. # IP address for the VPN
  84. # mandatory
  85. vpn_ip = 10.0.0.1
  86.  
  87. # Subnetwork for the VPN
  88. # mandatory
  89. # must be the same for all peers
  90. # Use the CIDR notation
  91. network=10.0.0.0/24
  92.  
  93.  
  94. [SECURITY]
  95.  
  96. # PEM file containing the client X.509 certificate
  97. # mandatory
  98. certificate = ./box1/certificate.pem
  99.  
  100. # PEM file containing the client private key
  101. # mandatory
  102. key = ./box1/key.pem
  103.  
  104. # PEM file containing a root certificates chain
  105. # Specify at least one of ca_certificates and ca_cartificates_dir
  106. ca_certificates = ./box1/cacert.pem
  107.  
  108. # Directory containing root certificates.
  109. # It must have been prepared by the c_rehash OpenSSL's utility.
  110. # Specify at least one of ca_certificates and ca_cartificates_dir
  111. #ca_certificates_dir = ./box1/root_certs/
  112.  
  113. # PEM file containing a certificate revocation list (CRL)
  114. # optional
  115. crl_file = ./box1/crl.pem
  116.  
  117. # Maximum depth for the certificate chain verification.
  118. # optional
  119. # default: 9
  120. #verify_depth = 1
  121.  
  122. # The OpenSSL ciphers lists to use
  123. # optional
  124. # default: OpenSSL's default
  125. # must be the same for all peers
  126. # See openssl ciphers man page for more details
  127. # For RSA, cipher suites with key lengths larger than 128 bits, sorted by
  128. # strength:
  129. #cipher_list = RSA+HIGH:@STRENGTH
  130. # For Camellia, 128-bit key, RSA and SHA1:
  131. #cipher_list = CAMELLIA128-SHA
  132. # For no encryption:
  133. #cipher_list = NULL
  134.  
  135.  
  136. [CLIENT]
  137.  
  138. # Internal FIFO size
  139. # optional
  140. # The client uses one FIFO per connected peer
  141. # default: 20
  142. #fifo_size=50
  143.  
  144. # Linux only:
  145. # Length of the TUN/TAP driver's transmit queue
  146. # optional
  147. # This sets the length of the internal transmit queue on the TUN device.
  148. # default: 500 frames (current default of the TUN/TAP driver)
  149. #txqueue=100
  150.  
  151. # Linux only:
  152. # Use the TUN/TAP driver in single queue mode.
  153. # optional
  154. # This instructs the TUN/TAP driver to use its single queue mode. This is
  155. # required to work around a bug in pre-2.6.11 kernels. It can also helps with
  156. # slow hardware or slow connections by reducing the total TX queue length.
  157. #tun_one_queue=yes
  158.  
  159. # Bandwidth throttling
  160. # optional
  161. # default: disabled
  162. # Those two options allow to limit the outgoing traffic for the whole client
  163. # and/or for each connection. The values are in kilobytes/seconds.
  164. # Comment one option to disable it or use 0.
  165. # Limit the outgoing traffic to 500 kB/s and/or allow 100 kB/s per
  166. # connection:
  167. #client_max_rate = 500
  168. #connection_max_rate = 100
  169.  
  170. # Inactivity timeout before closing a session.
  171. # optional
  172. # The value is given in secs (integer)
  173. # default: 120 seconds
  174. #timeout = 120
  175.  
  176. # Period of inactivity before sending a keepalive message
  177. # optional
  178. # default: 10 seconds
  179. #keepalive = 30
  180.  
  181. # Maximum number of connections with other clients
  182. # optional
  183. # default: 100
  184. #max_clients = 20
  185.  
  186.  
  187. [COMMANDS]
  188.  
  189. # Execute the default commands to configure the TUN device
  190. # optional
  191. # default: yes
  192. # If this is set to no, the commands are specified with the "up" parameter.
  193. #default_up = no
  194.  
  195. # Execute the default commands when the TUN device is closed.
  196. # optional
  197. # default: yes
  198. # If this is set to no, the commands are specified with the "down" parameter.
  199. #default_down = no
  200.  
  201. # Add a shell command to execute when the TUN device is configured and
  202. # default_up is false.
  203. # The following special values are available:
  204. # %D - the tun device
  205. # %V - VPN IP
  206. # %M - MTU
  207. # %I - local IP
  208. # %P - local UDP port
  209. # %N - Netmask
  210. # %n - Netmask, in dot-decimal notation
  211. # %% - the '%' char
  212. #up = "echo configuring %D!"
  213.  
  214. # Default programs for Linux:
  215. #up = "ifconfig %D %V mtu %M up"
  216. #up = "ip route replace %N via %V || route add -net %N gw %V"
  217. # For FreeBSD and NetBSD:
  218. #up = "ifconfig %D inet %V %V mtu %M up"
  219. #up = "route add -net %N %V"
  220. # For OpenBSD (you do not need to setup the MTU with ifconfig, it's already
  221. # done):
  222. #up = "ifconfig %D inet %V %V up"
  223. #up = "route add -net %N %V"
  224. # For Cygwin (you do not need to setup the MTU, it's already done):
  225. #up = "netsh interface ip set address name=%D static %V %n none"
  226.  
  227. # Add a shell command to execute when the TUN device is closed and default_down
  228. # is false.
  229. # The same special values are available.
  230. #down = "echo closing %D!"
  231.  
  232. # There is no default down command on Linux, OpenBSD and Cygwin.
  233. # Default command for FreeBSD and NetBSD:
  234. #down = "ifconfig %D destroy"
  235.  

Creating the certificates

Using the ca_wrap script

Campagnol comes with a small wrapper script around the OpenSSL utilities. It can be used to:

  • create a basic OpenSSL configuration file
  • build the root certificate authority key and certificate
  • create new keys and signed certificates for your VPN
  • revoke certificates
  • generate a certificate revocation list

You first need to create the directory for your CA and to copy the script into this directory. Then you must edit the script to setup its working direcory and the default fields for the generated certificates.

Once the script is configured, create the configuration file for OpenSSL:

  1. ./ca_wrap.sh gen_conf

Then you have to create the private key, the root certificate and all the required files:

  1. ./ca_wrap.sh gen_ca

For each client on the VPN, you will have to create a new key/certificate:

  1. ./ca_wrap.sh gen_cert my_client
  2. ./ca_wrap.sh gen_cert other_client

You can also revoke an old certificate and generate a revocation list:

  1. ./ca_wrap.sh revoke_crt my_client
  2. ./ca_wrap.sh gen_crl

Sample certificates

The samples directory in the client sources contains a few certificates useful for testing purpose only.

Running

Rendezvous server

Run the rendezvous server on a publicly accessible computer (for every clients of the VPN). The server uses the default UDP port 57888. Be sure that this port is reachable. The server doesn't require superuser privileges if you do not ask for a privileged port (<1024).

The rendezvous server accepts up to 100 registered clients by default.

Start the server and adjust the maximum number of registered clients:

  1. campagnol_rdv --max-clients=20

To start the server on another port:

  1. campagnol_rdv --port=34567

To start the server as a daemon:

  1. campagnol_rdv --daemon

Client

To start a client, run:

  1. campagnol conf_file.conf

To start the client as a daemon:

  1. campagnol --daemon conf_file.conf

Send a SIGTERM or SIGINT signal to the client to kill it cleanly. If no configuration file is given, campagnol will search for a default /etc/campagnol.conf file. When campagnol is launched as a daemon, it will write its PID into /var/run/campagnol.pid (or another file defined in the configuration).

If you changed the CRL or the key/certificate used by a client, you can use:

  • SIGUSR1 to immediately kill all the connections and reload the files
  • SIGUSR2 to smoothly reload the files (they will be used for the subsequent connections)