OpenVPN Guide

Introduction

A VPN tunnel is a mechanism for sending private data over a public network. WeOS includes the open source OpenVPN suite to provide VPN tunnel services. More in-depth information about OpenVPN can be found at the website https://openvpn.net.

For example use-cases see the OpenVPN HowTos:

Client-Server Architecture

WeOS implements OpenVPN in a client-server architecture with one server and multiple clients, where the clients connect to the server. (In PSK mode, only one client per server is allowed.)

It is possible to run multiple OpenVPN tunnels on a single WeOS device as long the tunnels use different TCP or UDP ports. If so, the device can act either as server or as client on a per-tunnel basis.

Peer Authentication Methods

WeOS supports two types of peer authentication with OpenVPN:

  • PSK (Pre-Shared Key)
  • Certificates

The keys or certificates must be imported to WeOS before they can be used in setting up a VPN tunnel. Generating and importing keys and certificates is beyond the scope of this document. See [Placeholder: reference] for further information.

The WeOS administration interface in many places refers to SSL when working with OpenVPN tunnels, such as the show tunnel ssl command. This is for legacy reasons. SSL as a protocol is no longer in active use since it has been replaced by TLS.

Configuration

This section provides more information about the various configuration options available for VPN tunnels. OpenVPN provides a plethora of options and WeOS supports a useful subset of these.

Most WeOS options translate to an OpenVPN option as documented in the option descriptions. When searching for an option in the OpenVPN documentation or manual page, prepend -- to the option name to reduce the number of search hits. For example, search for --remote rather than remote.

General Options

Description

This is a short text description of the tunnel. The default is set to ssl followed by the tunnel ID (e.g. ssl0). The description is displayed when listing tunnels using CLI or Web. It is limited to 15 characters and may not contain spaces.

This is a WeOS-specific option (not passed to OpenVPN).

Server Mode
A new tunnel endpoint is by default in server mode. A tunnel endpoint in client mode can be brought to server mode by issuing the server command in the tunnel configure context.
Client Mode
A new tunnel endpoint is by default in server mode. Client mode is invoked by issuing the no server command in the tunnel configure context.
Max Clients

This option limits the number of clients allowed to be simultaneously connected to a Server.

This option is only available on the server.

The corresponding OpenVPN option is named max-clients

Compression

If compression is enabled, OpenVPN will try to compress all data to be sent across the tunnel. If the data is already compressed, this will be a waste of CPU cycles and compression should be disabled. If the option value is set to Adaptive, OpenVPN will periodically sample the compression ratio and disable compression for a period of time when the ratio is low.

Unless a client is configured with compression Off, the server will push its compression settings (On or Adaptive) to the client.

The related OpenVPN options are comp-lzo and comp-noadapt.

Method (Authentication Method)

Select the authentication method for data channel traffic: Certificate (i.e. TLS mode) or PSK (Pre-shared Key).

This option can also be used to disable authentication.

The option must have the same value for both client and server.

In PSK mode, the corresponding OpenVPN option is named secret. In Certificate mode, tls-server or tls-client.

Protocol

Protocol to encapsulate the tunnel traffic. TCP or UDP.

Both server and client must use the same value for this option.

The corresponding OpenVPN option is named proto.

Type (tun|tap)

Determines the protocol layer which is transmitted across the tunnel.

  • tap makes the tunnel endpoint a tap device which acts as a virtual port, receiving and transmitting link layer packets, including link layer multicast and broadcast packets.
  • tun makes the tunnel endpoint a tun device which acts as an interface, receiving and transmitting IP packets.

The option must have the same value for both client and server.

The corresponding OpenVPN option is named dev-type.

Listen

This server-only option allows specifying a single interfaces where the OpenVPN server will listen for incoming connections. If this option is not enabled, the server will listen on all available interfaces.

The corresponding OpenVPN option is named bind-iface. This is a Westermo addition to OpenVPN, which is why it may not yet be included in public documentation.

Keepalive

When this option is enabled, OpenVPN will periodically ping the remote peer across the tunnel control channel (only if there is no other traffic being sent across the tunnel). This ping may serve to keep ports open in a stateful firewall as well as detect a broken connection.

The second value represents the restart timeout - If no successful ping reply is received within this time, the tunnel will restart, causing any domain name lookups to be carried out again. This is is useful when either or booth peers are using dynamic IP addresses.

When configured on a server, the option values will also be pushed to the client(s).

The default configuration is for Keepalive to be enabled, with a ping period of 10 seconds and a restart timeout of 60 seconds.

The corresponding OpenVPN option is named keepalive.

Port

This option defines the TCP or UDP port on which the OpenVPN server will listen. This option needs to be configured if multiple servers should run on the same WeOS unit, or if the default port (1194) cannot be used.

Matching values have to be configured for client and server.

The corresponding OpenVPN option is named lport.

Peer

This option identifies the remote peer by domain name or IP address. A client must use this option to identify the server.

The corresponding OpenVPN option is named remote.

Pool

In certificate mode, an OpenVPN server may act like a DHCP server and assign IP addresses to clients. This option configures the IP range and size of the pool.

This is a server-only option.

The corresponding OpenVPN option is named ifconfig-pool.

Push-Network

This option allows definition of a set of networks which should be reachable by a client. The server will push these networks to the client, which will create static routes to direct traffic across the tunnel to reach the networks.

This is a server-only option. It only works in Certificate mode.

The corresponding OpenVPN option is named push route.

Pull

This option only applies to clients running in certificate mode. Setting no pull will inhibit all pushed configurations (such as network routes) from the server.

Pull is enabled by default.

The corresponding OpenVPN option is named pull.

Client To Client

In certificate mode, it is possible for the OpenVPN server to act as a router and forward traffic from one client to another instead of passing all incoming traffic to the tunnel endpoint. This option enables the client-to-client routing behaviour.

This option is server-only and is not available in PSK mode.

The corresponding OpenVPN option is named client-to-client.

Client Configuration

In certificate mode, each client is associated with a common name encoded in its certificate. This sub-context allows the server to assign a fixed IP addresses to each client based on the client’s common name.

This option is valid on the server only.

Related OpenVPN options are client-config-dir and ifconfig-push

Duplicate CN (Common Name)

In certificate mode, each client is associated with a common name encoded in its certificate. This option allows multiple clients to use the same common name.

If this option is not enabled, the default behaviour is for the server to disconnect any previous client using the same common name as the one connecting.

This option is available on the server only.

The corresponding OpenVPN option is named duplicate-cn.

Auth (Authentication Hash)

Select the hash function to be used for data authentication.

The hash is calculated over the encrypted package and combined with a key, which is the pre-shared key (in PSK mode) or auto-generated (in TLS mode), to produce a digital signature. The signature is then appended to the packet. The receiver performs the same calculation and compares the calculated signature to the received one. If they do not match, the package is dropped.

The corresponding OpenVPN option is named auth.

Secret

When using PSK mode, this option is used to specify the key to use for data channel encryption/decryption as well as for authentication. (Both keys will be extracted from the same key file.)

This option requires a static key which must have been previously imported into the WeOS device using the certificate import function. The same key must be present on both client and server.

Certificate and CA-Certificate

In Certificate mode, these options specify the certificate and CA-certificate used to identify the tunnel endpoint.

The certificates are specified using the labels assigned when they were imported to the WeOS certificate storage.

Related OpenVPN options are: ca, cert, key.

Crypto

Select the cipher algorithm to use for the data channel. (For control channel encryption, see the TLS-Auth option.) This option can also be used to disable encryption, in which case data will be transmitted in clear text.

This option must have the same value for client and server.

The corresponding OpenVPN option is named cipher

TLS-Auth

This option is used to add authentication for OpenVPN TLS control channel packets when operating in Certificate mode. It does not work in PSK mode.

The option works to harden the tunnel security and provides resilience to DoS (Denial of Service) attacks where a fake client tries to make the OpenVPN server waste system resources on processing of fake connection attempts.

This option requires a static key which must have been previously imported into the WeOS device using the certificate import function. The same key must be present on both client and server.

An optional direction parameter can be specified. If so, different keys are used for server-to-client vs client-to-server traffic. Both keys will be extracted from the same key file.

Both client and server must use the same value for this option, with the exception for the optional direction which should have opposite values for server vs clients (e.g. 0 for server and 1 for clients).

The corresponding OpenVPN option is named tls-auth.

Renegotiation Timeout

In certificate mode, this option determines the period at which the data channel encryption key is renegotiated. The default value is 3600 seconds. If client and server use different values for this option, the lower value will be used.

The corresponding OpenVPN option is named reneg-sec.

Identity

This option is used to provide a user name and password to be used as an additional level of authentication.

This option is client-only and must be provided if the server is configured to require such authentication (See AAA-Method).

The corresponding OpenVPN option is named auth-user-pass

AAA-Method

This option defines how user authentication works in conjunction with OpenVPN. If enabled, it will cause the server to request clients to send access credentials (e.g. username and password), and will then ask WeOS to validate these before allowing the connection to succeed.

The configuration accepts either a local-db id or a server-id, which should be defined in advance in the WeOS AAA subsystem.

The option is server-only.

Summary of Options

General Options

WeOS Option OpenVPN option(s) Client/Server
description N/A both
[no] server N/A
max-clients max-client server
compression comp-lzo, comp-noadapt both

Connection Related Options

WeOS Option OpenVPN option(s) Client/Server
method secret, tls-server, tls-client both
protocol proto both
type dev-type both
listen N/A server
keepalive keepalive both
port lport server
peer remote client
pool ifconfig-pool server
push-network push route server
[no] pull pull client
client-to-client client-to-client server
client-config client-config-dir, ifconfig-push server
duplicate-cn duplicate-cn server

Security Related Options

WeOS Option OpenVPN option(s) Client/Server
auth auth both
secret secret both
certificate cert, key both
ca-certificate ca both
crypto cipher both
tls-auth tls-auth both
renegotiation-timeout reneg-sec both
identity auth-user-pass client
aaa-method N/A server