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
orAdaptive
) to the client.The related OpenVPN options are comp-lzo and comp-noadapt.
Connection Related Options
- 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.
Security Related Options
- 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 |