Advanced option settings on the command line

Introduction

This document provides information about advanced features for OpenVPN Access Server executed from the command line interface (CLI). For all of these commands, ensure you connect to your server with root privileges and run the commands from /usr/local/openvpn_as/scripts/.

Set the interface and ports for the OpenVPN daemons

You can set the interface and ports for the OpenVPN daemons from the Admin Web UI or the CLI. Use the commands below for changing this in the CLI. Before you change the default settings, ensure you understand the information below about how the daemons work with the web interface to avoid problems accessing your Admin or Client Web UIs after making changes.

An overview of the OpenVPN daemons

The OpenVPN daemons handle OpenVPN tunnel connections. These programs listen on all available network interfaces, as the default. Alternatively, you can configure the OpenVPN daemons to listen on a specific network interface. You can also change the ports the OpenVPN daemons listen on, but we recommend only doing that in unique circumstances.

Caution: Changing the interface values may mean you must reinstall your clients to connect, as these settings don’t update automatically on clients.

The OpenVPN daemons and web services

The OpenVPN daemons and web services affect each other. By default, OpenVPN Access Server comes configured with OpenVPN daemons listening on UDP port 1194 and TCP port 443. Access Server’s web services also use TCP 443 for the web interfaces. You can’t have two different processes listening on the same port on the same server so we use what we call service forwarding or port forwarding.

When you open a web browser and go to your Admin or Client Web UIs, the OpenVPN TCP daemon handles that browser request by internally redirecting the traffic to the web services that are actually running on port TCP 943.

It’s important to note that if you change the interface the OpenVPN daemons listen on, you could inadvertently deny access via this port forwarding method. To resolve this, you must use the port that the web services are actually running on: TCP 943. To access the web interface at that port, include 943 in the URL like so: https://your.vpnserver.com:943/.

A note about UDP and TCP ports

The preferred port for an OpenVPN tunnel is the UDP port, but the TCP 443 port serves as a fallback method, due to restricted internet connectivity on some networks, such as public networks. As port TCP 443 is used for HTTPS traffic, which is used by many websites by default, having an OpenVPN TCP daemon on port TCP 443 makes it so it’s more likely an OpenVPN client program on a restricted network can still make a connection to Access Server using the TCP fallback. While this isn’t guaranteed, depending on the sophistication of the firewalls, it works with most simple firewalls.

Changing the OpenVPN daemon interface or ports

You can manage the OpenVPN daemons from the Admin Web UI or the command line interface (CLI). To use the Admin Web UI:

  1. Sign in to the Admin Web UI.
  2. Click Configuration > Network Settings.
  3. Make your changes on the Server Network Settings page, then save and update the running server.

To use the CLI, use the commands below.

To set the interface name that the OpenVPN daemons should listen on:

./sacli --key "vpn.daemon.0.server.ip_address" --value <INTERFACE> ConfigPut
./sacli --key "vpn.daemon.0.listen.ip_address" --value <INTERFACE> ConfigPut
./sacli start

To set a specific port for the UDP OpenVPN daemons:

./sacli --key "vpn.server.daemon.udp.port" --value <PORT_NUMBER> ConfigPut
./sacli start

To set a specific port for the TCP OpenVPN daemons:

./sacli --key "vpn.server.daemon.tcp.port" --value <PORT_NUMBER> ConfigPut
./sacli start

To restore the default so it listens to all interfaces and ports TCP 443 and UDP 1194:

./sacli --key "vpn.daemon.0.server.ip_address" --value "all" ConfigPut
./sacli --key "vpn.daemon.0.listen.ip_address" --value "all" ConfigPut
./sacli --key "vpn.server.daemon.udp.port" --value "1194" ConfigPut
./sacli --key "vpn.server.daemon.tcp.port" --value "443" ConfigPut
./sacli start

Important: When you change the interfaces, the OpenVPN UDP and TCP daemons must listen on the same interface. It’s not possible to have them listening on two separate interfaces. If you want to change this, use iptables to internally redirect traffic on a specific port and interface to the correct port and interface.

Disable multi-daemon mode and use only TCP or UDP

The OpenVPN 2 code base is single-thread — an OpenVPN process can run on only one CPU core and doesn't know how to make use of multi-core systems — OpenVPN Access Server comes with the ability to launch multiple OpenVPN daemons at the same time. Ideally, your server has one OpenVPN daemon for every CPU core. However, to make it possible for OpenVPN clients to establish a connection via the UDP protocol or the TCP protocol, this requires additional OpenVPN daemons:

  • We recommend one TCP and one UDP daemon per CPU core.

Example:

On a system with four CPUs, that’s eight daemons running: two per CPU core; one TCP and one UDP.

Access Server performs a sort of internal load balancing. When connections come in, Access Server decides which CPU core and thus which OpenVPN daemon is least busy, and connects you to that daemon.

In some rare cases it can be desirable or necessary to turn off multi-daemon mode and simply launch one TCP or UDP OpenVPN daemon to handle all incoming OpenVPN tunnel connections through one single OpenVPN daemon. This may have some negative side effects:

  1. You block access to your Admin and Client Web UIs because this change affects service forwarding browser requests (explained above about web services).
  2. On restrictive networks that block UDP connections but TCP 443 (the default HTTPS port) is still open, if you only run a UDP OpenVPN daemon, you can’t make a connection from such a restrictive network.
  3. And if you decide to use TCP daemons only, then the TCP Meltdown phenomenon may adversely affect your connection.

To disable multi-daemon mode and use only 1 TCP daemon:

./sacli --key "vpn.server.daemon.enable" --value "false" ConfigPut
./sacli --key "vpn.daemon.0.listen.protocol" --value "tcp" ConfigPut
./sacli --key "vpn.server.port_share.enable" --value "true" ConfigPut
./sacli start

To disable multi-daemon mode and use only 1 UDP daemon:

./sacli --key "vpn.server.daemon.enable" --value "false" ConfigPut
./sacli --key "vpn.daemon.0.listen.protocol" --value "udp" ConfigPut
./sacli --key "vpn.server.port_share.enable" --value "false" ConfigPut
./sacli start

Reset multi-daemon mode and number of TCP/UDP daemons

The commands below use the sacli GetNCores command to output the number of CPU cores detected on the system. With that information, you can configure the number of TCP and UDP daemons to spawn when Access Server starts.

Note: The characters around the sacli GetNCores command below are backticks, not single quotes, and this makes a significant difference in how the command is executed. We recommend copying and pasting the commands to ensure they execute properly. We also reset the default setting here to use multi-daemon mode where multiple OpenVPN daemons launch.

Restore the default of using multi-daemon mode, with the amount of processes same as CPU cores (recommended):

./sacli --key "vpn.server.daemon.enable" --value "true" ConfigPut
./sacli --key "vpn.daemon.0.listen.protocol" --value "tcp" ConfigPut
./sacli --key "vpn.server.port_share.enable" --value "true" ConfigPut
./sacli --key "vpn.server.daemon.tcp.n_daemons" --value "`./sacli GetNCores`" ConfigPut
./sacli --key "vpn.server.daemon.udp.n_daemons" --value "`./sacli GetNCores`" ConfigPut
./sacli start

Reset OpenVPN web services and daemons to defaults

These commands help in two scenarios:

  1. To undo any wrong settings that may lock you out of access to your web services.
  2. For restoring an Access Server backup configuration from one system to another but the interface names on the old server aren’t the same as the new server.

As an example of the second scenario, your old server listens only to eth0, but the new server only has ens192. When you switch servers, you can’t reach the Admin Web UI to correct these settings, but can fix that with the below commands.

These commands reset the interface names to "all", meaning that OpenVPN Access Server listens to all available interfaces, and at the default ports (TCP 443, TCP 943, UDP 1194).

Reset web services, service forwarding, and OpenVPN daemons to default ports and listen on all interfaces:

./sacli --key "admin_ui.https.ip_address" --value "all" ConfigPut
./sacli --key "admin_ui.https.port" --value "943" ConfigPut
./sacli --key "cs.https.ip_address" --value "all" ConfigPut
./sacli --key "cs.https.port" --value "943" ConfigPut
./sacli --key "ssl_api.local_addr" --value "all" ConfigPut
./sacli --key "ssl_api.local_port" --value "945" ConfigPut
./sacli --key "vpn.server.port_share.enable" --value "true" ConfigPut
./sacli --key "vpn.server.port_share.service" --value "admin+client" ConfigPut
./sacli --key "vpn.daemon.0.server.ip_address" --value "all" ConfigPut
./sacli --key "vpn.daemon.0.listen.ip_address" --value "all" ConfigPut
./sacli --key "vpn.server.daemon.udp.port" --value "1194" ConfigPut
./sacli --key "vpn.server.daemon.tcp.port" --value "443" ConfigPut
./sacli start

Optionally, you can specify “IP address” to listen on specific addresses instead of "all".

XML-RPC interface

OpenVPN Access Server uses XML-RPC internally between web services and core components, and between OpenVPN Connect apps and the XML-RPC interface on the web services (at /RPC2 URL).

OpenVPN Connect only uses the XML-RPC interface in a limited fashion to check credentials, and to obtain a user-locked profile for connecting, when OpenVPN Connect uses a server-locked profile.

If the XML-RPC interface setting is changed to full support, either in the Client Settings page in the Admin Web UI, or via the command line with the configuration option shown below, then you can remotely control all functionality of Access Server using XML-RPC calls instead. Authentication is done via HTTP basic authentication over a secure SSL connection. To retrieve a user-locked profile a standard user's credentials are sufficient, but for other functions only an admin user's credentials are sufficient.

We do not provide documentation or support for the XML-RPC interface.

However, we can give you the tools to determine what calls to make and how, and you can use that information to use or make XML-RPC capable programs that can remotely control the Access Server.

To see XML-RPC calls on the command line with the sacli VPNSummary function:

OPENVPN_AS_DEBUG_XML=1 ./sacli VPNSummary

You will get a result which shows the XML query, and the response. This system of getting information works for pretty much every sacli function. And sacli controls just about everything that the Access Server can do.

To change the XML-RPC function support:

./sacli --key "xmlrpc.relay_level" --value <NUMBER> ConfigPut
./sacli start

Where <NUMBER> is:

  • 0 - disable the XML-RPC API via web services entirely, and will break server-locked profile type connections.
  • 1 - enable XML-RPC API via web services in a limited fashion, for server-locked profile type connections only (default).
  • 2 - fully enable XML-RPC API via web services, allows full remote control of the Access Server's function.

Logging of XML-RPC API calls is by default not enabled, but can be enabled with an XML-RPC debug flag.

Limit total maximum amount of VPN tunnels

By default the Access Server allows 2048 VPN tunnels on a single installation of Access Server. This is normally enough, but if you want to, you can increase that limit. Please note that if you change this value, even a warm restart of Access Server will restart the OpenVPN daemons, meaning all your VPN clients get kicked off and they will need to reestablish their connection, which should happen automatically.

Change maximum amount of active incoming VPN tunnels:

./sacli --key "vpn.server.max_clients" --value <NUMBER> ConfigPut
./sacli start

Where <NUMBER> is the maximum amount of connected VPN tunnels. This configuration key by default is not present in Access Server, and when it is not present, it will be assumed to be 2048. It can be set to any valid number of your choice.

UCARP/VRRP failover advanced settings

When the built-in failover mode of the Access Server is configured and in use, the primary node will send out heartbeat signals onto the local network. The secondary node monitors these heartbeat signals, and if it fails, takes over the tasks from the failed node. But if multiple such pairs are active on the same network, or if other systems also use UCARP/VRRP for automatic failover, then the system needs a way to differentiate the signals. This is done with a VHID which is a unique number embedded in the heartbeat signals. Each failover pair needs its own ID. By default this number is 94 on an Access Server failover pair. To adjust it to another number adjust the value of the ucarp.vhid configuration key with the command below, but beware that you should follow the steps carefully as described below for both nodes, and that this will lead to having to restart the Access Server service on each node in turn, causing a total of 2 failover events. So plan this appropriately.

On the primary node adjust the VHID:

./sacli --key "ucarp.vhid" --value <NUMBER> ConfigPut
service openvpnas restart

Where <NUMBER> is a number from 1 to 255.

Now wait a full minute. This is to ensure that the primary node has had a chance to create a new configuration backup file and to relay it to the secondary node. There will now be a brief moment where both nodes try to be the master node, as each does not see the other anymore due to the mismatched VHID number.

Now go to the secondary node and restart the Access Server service:

service openvpnas restart

The primary node should now come back online properly and the secondary node should now be in standby mode again.

Finally, for advanced users, it is possible to pass additional parameters to the UCARP process. This is done with the ucarp.extra_parms configuration key. See the command below on how to pass extra parameters to the UCARP process that Access Server manages. Please note that changing this will result in a failover event and you will then have to restart the Access Server service on the secondary node as well to ensure it goes back the primary node.

Define extra parameters for Access Server to pass to UCARP:

./sacli --key "ucarp.extra_parms" --value <PARAMETERS> ConfigPut
service openvpnas restart

Where <PARAMETERS> is a string of text that contains what you want to pass to UCARP.
If for example you want to override the standard scripts that OpenVPN Access Server uses for when the node becomes active or has to be a standby node, then you can do so by passing new --upscript and --downscript parameters directly to UCARP, and specifying new scripts instead. You could for example copy the original ucarp_standby and ucarp_active up/down scripts in the /usr/local/openvpn_as/scripts/ directory and edit them to suit your needs. It is of course possible to edit the scripts directly but that would mean during an upgrade or reinstallation that these scripts are reset to standard. Using the method described to create your own copies of the up/down scripts that you can customize is the better method if you want to customize these up/down scripts.

Override up/down scripts with new scripts (make sure to create them of course):

./sacli --key "ucarp.extra_parms" --value "--upscript /root/up --downscript /root/down" ConfigPut
service openvpnas restart

And to revert to the default scripts:

./sacli --key "ucarp.extra_parms" ConfigDel
service openvpnas restart

Global NAT behavior setting

Since private IP addresses cannot be routed on the Internet, when VPN clients are connected to the Access Server and have been given instructions to send traffic for public IP addresses through the VPN server, the Access Server will choose the network interface with the default gateway on it and NAT traffic out through there. In some cases it is desirable to disable this NAT behavior, for example when you wish to implement a firewall system that logs the VPN clients private IP addresses as the traffic passes from the VPN client, through the VPN server, through the firewall, and then goes to the Internet. The NAT behavior can then be implemented further on in the connection chain before it goes onto the public Internet. This is a global setting that applies to the entire server for outgoing traffic through NAT. It is possible to disable this setting, or to specify a different IP address to use for outgoing NAT, or even a range of addresses that will be randomly selected for outgoing NAT operations. It is impossible to bind a specific public IP for outgoing NAT operations to a specific VPN client.

Disable NAT for outgoing public traffic (enabled by default):

./sacli --key "vpn.server.nat" --value "false" ConfigPut
./sacli start

Re-enable NAT (restore default):

./sacli --key "vpn.server.nat" ConfigDel
./sacli start

Specify interface/address for outgoing NAT:

./sacli --key "vpn.server.routing.snat_source.N" <INTERFACE-ADDRESS> ConfigPut
./sacli start

Where N is a number starting from 0 and logically increments, for multiple definitions.
And where INTERFACE-ADDRESS is one of the following:

  • interface:address - Source NAT traffic using IP address of a specified interface name.
  • interface:number - Source NAT using IP address of alias number of specified interface name.
  • interface:begin-range:end-range - Source NAT traffic at random using range of IP addresses.

The randomization of that last option is done using the Linux/Netfilter to-source algorithm. It is of course required that the interfaces and IP addresses you intend to use are actually available and configured on your system and are by themselves working properly. Examples of specifying the interface and address for outgoing NAT are given below.

For example NAT eth2 traffic via 1.2.3.4:

./sacli --key "vpn.server.routing.snat_source.0" --value "eth2:1.2.3.4" ConfigPut
./sacli start

Or NAT eth0 traffic via the eth0:4 address:

./sacli --key "vpn.server.routing.snat_source.0" --value "eth0:4" ConfigPut
./sacli start

Or NAT ens192 traffic using a range of public IPs from 76.49.27.18 to 76.49.27.22:

./sacli --key "vpn.server.routing.snat_source.0" --value "ens192:76.49.27.18:76.49.27.22" ConfigPut
./sacli start

Multiple rules can be specified for multiple interfaces, for example:

./sacli --key "vpn.server.routing.snat_source.0" --value "eth0:76.49.27.18:76.49.27.22" ConfigPut
./sacli --key "vpn.server.routing.snat_source.1" --value "eth1:3" ConfigPut
./sacli start

The Access Server makes heavy use of Linux iptables to enable NAT functionality and enforce VPN-level access control rules, however it also tries to play well with other applications that use iptables by maintaining its own chains and making minimal additions to standard chains such as INPUT, OUTPUT, and FORWARD. By default, the Access Server prepends to standard chains, and this remains the default. Prepending means it tries to come first in an existing list of iptables settings, to ensure Access Server works properly. However by using the following config key, this behavior can be changed to append, to make it easier to develop custom rules which take priority over Access Server-generated rules.

To make Access Server add rules after existing ones (append instead of prepend):

./sacli --key "iptables.append" --value "True" ConfigPut
./sacli start

Restore default behavior:

./sacli --key "iptables.append" ConfigDel
./sacli start

It is also possible to completely disable Access Server's activities in regards to iptables. However, this may lead to insecure situations as traffic may be allowed through that you didn't give permission for, and things may then simply not function as intended anymore. Disabling iptables means you're taking away one of the pillars on which the Access Server functionality is based and you are then expected to take care of the required actions in iptables yourself. If you do not, the Access Server will likely just completely fail to function. We do not recommend disabling Access Server managing the iptables settings. But if you must, for whatever reason, and you have the required knowledge to get things working, then the option is available. There are 3 distinct iptables items that Access Server manages and these that are all enabled by default, but can optionally be disabled:

  • iptables.vpn.disable.filter
  • iptables.vpn.disable.nat
  • iptables.vpn.disable.mangle

Example for disabling one of the three above settings:

./sacli --key "iptables.vpn.disable.filter" --value "True" ConfigPut
./sacli start

Restoring the value to its default:

./sacli --key "iptables.vpn.disable.filter" ConfigDel
./sacli start

Choosing Layer 3 (routing) or Layer 2 (bridging)

Before we explain this setting further, we want to make it clear that layer 2 VPN mode or bridging is not a recommended method of using OpenVPN Access Server, and you may encounter problems with it that are related to MAC address spoofing or promiscuous mode which are security related settings in hardware and software that may need to be adjusted or enabled in order for this to work at all. We also want to warn you that using bridging mode disables a lot of the functionality of the Access Server because it simply does not apply anymore. In layer 3 mode, the recommended mode, the Access Server functions as a router with firewall functions built-in to ensure traffic can't go to places it shouldn't be able to go. But with layer 2, you're basically turning the Access Server into a software-based network switch with encryption where all connected VPN clients can communicate freely with each other and the network the Access Server is attached to. There's no control here over what traffic is allowed to go where, and the Access Server also plays no role in assigning IP addresses or specific access rules to the VPN clients. In other words, if you don't know what you're doing, do not use this mode and stick to the default Layer 3 routing mode, please.

To learn about what Layer 3 and Layer 2 means see our short explanation on what the OSI Layer model is.

The configuration parameter vpn.general.osi_layer controls the behavior of the Access Server. It can operate on Layer 2 in bridging mode, and in Layer 3 in routing mode (the default). In the past, in Access Server versions older than version 2.5, it was possible to set this option in the Admin UI, but we have since hidden this option further to prevent people from trying it out accidentally, as it is a very advanced feature and likely to cause the product to appear not to function anymore, unless you know what you're doing. But the option for Layer 2 bridging mode can still be enabled.

Switch to Layer 2 bridging mode:

./sacli --key "vpn.general.osi_layer" --value "2" ConfigPut
./sacli start

Restore to Layer 3 routing mode:

./sacli --key "vpn.general.osi_layer" ConfigDel
./sacli start

If you had Access Server installed and operating on Layer 2 bridging mode already, and you have just upgraded your Access Server to the latest version, this setting will remain intact and your server will continue to function in Layer 2 bridging mode. So an upgrade will not break this functionality.

If you had all your VPN clients installed and operating on Layer 3 routing mode already, and you now switch your server to Layer 2 bridging mode, any VPN clients that have a stored copy of the user-locked or auto-login type connection profiles will need to obtain a new copy of the connection profile before they are able to successfully connect again. The most common problems we encounter with Layer 2 are that the VPN client does not get an IP address assigned. The most common reason for this is that you now need a DHCP server running either on the Access Server itself or on the network that the Access Server is connected to (but not both at the same time), and that either such a DHCP server does not exist, or is unreachable because the network or the device that the DHCP server runs on has a security feature that is called MAC address spoofing or promiscuous mode set to a safe level. These terms both describe the same idea, where a single computer, in this case the Access Server, pretends to be multiple systems at the same time, which makes sense in this case, because it tries to handle traffic for multiple VPN clients that all want connectivity to the connected network. On virtual platforms like ESXi or HyperV you may need to look into these settings on the virtual switch and allow this type of behavior on the network before Layer 2 bridging mode can function. Please note that due to the added complexity of implementing Layer 2 bridging mode where external equipment is usually the cause of the problem, we may not be able to offer you adequate support in resolving this issue. We can only ensure the Access Server and the OpenVPN clients can make a connection, but IP addressing and traffic transmission issues that pass the boundary where Access Server connects to your network, and doesn't function from there on, is not something we can resolve from our end.

Allow UDP multicast and IGMP to pass through

By default in Layer 3 routed mode, which is what the Access Server uses normally, all traffic is unicast. That means that only traffic that has a specific destination IP address will be allowed to pass through the VPN server. Multicast traffic, or broadcast traffic that has a to-whom-it-may-concern characteristic, is blocked. It is possible to lift the restriction on UDP multicast packets and IGMP packets, so that these pass freely between VPN clients and the VPN server. Some software programs use these to auto-detect systems or services on the network, and so this option may be useful in such a situation. The configuration key vpn.routing.allow_mcast allows this traffic to pass through. It is disabled by default. Enable UDP multicast and IGMP traffic passthrough:

./sacli --key "vpn.routing.allow_mcast" --value "true" ConfigPut
./sacli start

Restore the default setting:

./sacli --key "vpn.routing.allow_mcast" ConfigDel
./sacli start

This setting implements these iptables rules on the VPN server, which is what allows the traffic to pass through:

ACCEPT udp   -- anywhere  base-address.mcast.net/4 udp
ACCEPT igmp  -- anywhere  anywhere
ACCEPT udp   -- anywhere  base-address.mcast.net/4 udp
ACCEPT igmp  -- anywhere  anywhere