WeOS
5.29.0

# 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:

- OpenVPN LAN Bridging HowTo
- OpenVPN Host to LAN HowTo
- OpenVPN Internal Routes HowTo

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 (Secure Socket Layer) as a protocol is no longer in active use since it has been replaced by TLS (Transport Layer Security).

### Client-Server Architecture

WeOS implements OpenVPN in a client-server, where the clients connect to the server. When used with certificate authentication, multiple clients can connect to a single server. In pre-shared key authentication mode, a single client per server is allowed.

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

### Peer Authentication Methods

WeOS supports two types of peer authentication with OpenVPN:

- Certificates
- PSK (Pre-Shared Key)

The keys or certificates must be imported to the WeOS certificate repository before they can be used in setting up a VPN tunnel.

It is possible for the server to require VPN clients to authenticate with username and password in addition to certificate/PSK. These user credentials can be verified against a remote authentication server (RADIUS) or in a local user database at the server (see WeOS AAA).

## 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”.

OpenVPN configuration context is entered via the tunnel configuration context:

    example:/config/#> tunnel
    example:/config/tunnel/#> ssl 1
    example:/config/tunnel/ssl-1/#>

### Common Options (Server & Client Mode, Certificate & PSK Authentication)

`[no] ssl ID`
  Create new OpenVPN instance, or enter the configuration context of an existing instance. `no ssl ID` removes configuration for an instance. Up to MAX_OPENVPN_INSTANCES instances can be configured.
`[no] enable`
  Activate, or deactivate, this OpenVPN instance. If deactivated, the rest of the OpenVPN configuration is kept.
`[no] description STRING`

  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).

`[no] server`
  Set OpenVPN instance in “server” or “client” 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 is invoked by issuing the no server command.
`[no] method <cert|secret>`

  Select the authentication method for tunnel establishment: Certificate (i.e. TLS mode) or PSK (Pre-shared Key), where default is `method secret`.

  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.

`[no] type <tap|tun>`

  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.

`[no] protocol <tcp|udp|mptcp>`

  Protocol to encapsulate the tunnel traffic, TCP or UDP (default).

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

  The corresponding OpenVPN option is named proto.

`[no] port 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.

`[no] auth <sha1|sha256|md5>`

  Select the hash function to be used for data authentication. Defaults to `auth sha256`.

  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.

`[no] keepalive interval <SEC> restart <SEC>`

  When this option is enabled, OpenVPN will periodically ping the remote peer across the tunnel control channel at the specified interval (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 to 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 useful when either or both 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.

`[no] compression [adaptive]`

  If compression is enabled (`compression`), 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 adaptive compression is set (`compression 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 disabled (`no compression`), the server will push its compression settings (`compression` or `compression adaptive`) to the client.

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

### Options Common to Server Mode (Certificate & PSK Authentication)

`[no] local-address <ADDRESS>`

  This server-only option allows specifying a single address that the OpenVPN server will listen for incoming connections on. If this option is not enabled, the server will accept connections on any address.

  The corresponding OpenVPN option is named local.

`[no] bind-dev IFNAME`

  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-dev.

`[no] aaa-method <remote-server ID | local ID>`

  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 (RADIUS), which should be defined in advance in the AAA subsystem.

  The option is server-only.

### Options Common to Client Mode

`[no] peer <ADDRESS|DOMAIN>`

  This option identifies the remote peer by domain name or IP address. A client must set this option in order to inititate tunnel establishment to the server.

  Note

  Dynamic DNS (DDNS) comes in handy on the server side if the server acquires its IP address dynamically.

  The corresponding OpenVPN option is named remote.

`[no] identity USERNAME password PASSWORD`

  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

### Options Only for PSK Authentication

Options common to Client and Server Mode when using PSK Authentication.

`[no] secret LABEL`

  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.

`[no] crypto <bf-cbc|des-ede3-cbc|aes-128-cbc|aes-192-cbc|aes-256-cbc>`

  Select the cipher algorithm to use for the data channel. Default is `crypto aes-128-cbc`.

  This option can also be used to disable encryption (`no crypto`), 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

  (For control channel encryption, see the TLS-Auth option.)

### Options Only for MPTCP protocol

`[no] Mptcp-monitor IFNAME1 IFNAME2 IFNAME3`

  This option is used to provide the ifname(s) to create and monitor multi path tcp connection between the client and server.

  This option requires a unique path i.e policy-route for each ifname to reach the server.

### Options Only for Certificate Authentication

This section presents settings only available when using Certificate Authentication. First options applicable both for Client and Server modes are shown. The subsections below lists further settings specific to:

- Client Mode for Certificate Authentication
- Server Mode for Certificate Authentication
- Server Settings per Connecting Client

`[no] certificate LABEL`

  In Certificate mode, this option specifies the certificate used by this unit to authenticate itself.

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

  Related OpenVPN options are: cert, key.

`[no] ca-certificate LABEL`

  In Certificate mode, this options specifies the CA-certificate used to verify the certificate presented by the remote side.

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

  The corresponding OpenVPN options is named ca.

`[no] revocation <disabled|relaxed|strict>`

  This option is used to specify the revocation checking policy. The default is `disabled`. The other options are `relaxed` and `strict`.

  disabled
    Revocation checking is disabled. This is the default.
  relaxed
    Revocation checking is enabled, but the certificate is rejected only if it is explicitly revoked in a correctly signed and present CRL list. If the CRL has expired (i.e., the NextUpdate time has passed), it is still considered a valid revocation source.
  strict
    Revocation checking is enabled. If the CRL is not present, is outdated, or fails the signature check, the connection will be rejected.
  no
    Disables revocation checking.

  If availability of the OpenVPN tunnel is paramount, the `relaxed` option is recommended. This will allow the tunnel to remain up even if the CRL could not be downloaded in time.

  See the Revocation Configuration Guide for information on how to configure CRLs.

`[no] tls-auth label <LABEL> [direction <0|1>]`

  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.

`[no] renegotiation-timeout SEC`

  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.

`[no] data-ciphers <CIPHER[,CIPHER ...]>`

  List of ciphers to include in cipher negotiation between clients and servers. Defaults to the same default as the included OpenVPN version.

  See “help data-ciphers” for a list of available ciphers.

`[no] data-ciphers-fallback <CIPHER>`

  Fallback cipher to use when connecting to peers without support for negotiation.

  See “help data-ciphers” for a list of available ciphers.

`[no] tls-version-min <1.0|1.1|1.2|1.3>`
  Minimum TLS version accepted from peers.

#### Client Specific Settings for Certificate Authentication

This section presents settings only available in client mode for Certificate Authentication.

`[no] 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.

#### Server Specific Settings for Certificate Authentication

This section presents settings only available in server mode for Certificate Authentication. See also the following section presenting Server Settings per Connecting Client.

`[no] max-clients NUM`

  This option limits the number of clients allowed to be simultaneously connected to a Server. When this number is reached, the server will reject an incoming request. Defaults to 25. `no max-client` will remove the limit. NOTE: After automatic renewal of client certificate the server will see the client as if it is a new client.

  This option is only available on the server.

  The corresponding OpenVPN option is named max-clients

`[no] pool start IPADDR <num NUM | end IPADDR> [netmask NETMASK]`

  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.

`[no] push-network NETWORK/LEN`

  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.

`[no] 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.

`[no] duplicate-cn`

  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.

#### Server Settings per Connecting Client

In server mode when using certificate authentication, it is possible to assign/push a specific IP address to the connecting client. The Common Name in the client’s certificate is used to identify the client.

    example:/config/#> tunnel
    example:/config/tunnel/#> ssl 1
    example:/config/tunnel/ssl-1/#> server
    example:/config/tunnel/ssl-1/#> method cert
    example:/config/tunnel/ssl-1/#> client-configuration 1
    example:/config/tunnel/ssl-1/client-config-1/#>

`[no] client-configuration ID`

  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. ID is a number to identify the sub-context. Up to MAX_CLIENT_CONFIGURATIONS configurations can be configured.

  This option is valid on the server only.

  Related OpenVPN option is client-config-dir, see also `common-name` setting below.

`[no] common-name COMMON-NAME`

  The X.509 certificate common name (CN) used to match this CN binding.

  The corresponding OpenVPN option is named client-config-dir.

`[no] address ADDRESS/LEN`

  The IPv4 address to push to the client with this common name.

  The corresponding OpenVPN option is named ifconfig-push.

`[no] iroute ADDRESS/LEN`

  Configure an internal route to a specific client.

  This command can be used when a specific client may have another network behind it. What the iroute command will do is to inform the server which client is responsible for handling the specifically provided network.

  It is worth noting that this is a route internal to openvpn, it has nothing to do with the device’s general routing table.

  Because of the above reason it is still necessary to add a route for the specific network to the device’s routing table. The reason we need this is because we need a route for the packets to reach openvpn. When the frames reach openvpn iroute will be used to direct the frames to the correct client.

  As an example, we add an iroute for the network 10.0.0.0/24, then we also require a route for the network to reach the ssl interface. This can be achieved by adding a static route, under the IP context, in the following manner (Assuming the tunnel is named ssl1):

  route 10.0.0.0/24 ssl1

  If we do not add the route like in the above example, the frame will not reach the openvpn, and the iroute will serve no purpose.

  This option is valid for tun type tunnels.

  MAX_IROUTES iroute entries can be configured per client-configuration.

  The corresponding OpenVPN option is named client-config-dir.

### Summary of Options

In the table below, C and S refer to Client and Server modes.

WeOS Option | OpenVPN option(s) | PSK | Cert
--- | --- | --- | ---
enable | N/A | C,S | C,S
description | N/A | C,S | C,S
[no] server | N/A | C,S | C,S
method | secret, tls-server, tls-client | C,S | C,S
type | dev-type | C,S | C,S
protocol | proto | C,S | C,S
port | lport, remote | C,S | C,S
crypto | cipher | C,S | C,S
auth | auth | C,S | C,S
keepalive | keepalive | C,S | C,S
compression | comp-lzo, comp-noadapt | C,S | C,S
local-address | local | S | S
bind-dev | bind-dev | S | S
aaa-method | N/A | S | S
peer | remote | C | C
identity | auth-user-pass | C | C
Mptcp-monitor | N/A | C | C
secret | secret | C,S |
certificate | cert, key |  | C,S
ca-certificate | ca |  | C,S
revocation | crl-verify |  | C,S
tls-auth | tls-auth |  | C,S
renegotiation-timeout | reneg-sec |  | C,S
pull | pull |  | C
max-clients | max-client |  | S
pool | ifconfig-pool |  | S
push-network | push route |  | S
client-to-client | client-to-client |  | S
duplicate-cn | duplicate-cn |  | S
client-configuration | client-config-dir |  | S
common-name | client-config-dir |  | S
address | ifconfig-push |  | S
iroute | client-config-dir |  | S

## Feature Parameters

- MAX_OPENVPN_INSTANCES: 8
- MAX_CLIENT_CONFIGURATIONS: 100
- MAX_IROUTES: 8

« Previous Next »