Introduction
This document provides information about Access Server's advanced features executed from the command line interface (CLI). For all 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 to change 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, 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:
- Sign in to the Admin Web UI.
- Click Configuration > Network Settings.
- 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, and it's impossible 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 — 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 launch one TCP or UDP OpenVPN daemon to handle all incoming OpenVPN tunnel connections through one single OpenVPN daemon. This may have some adverse side effects:
- You block access to your Admin and Client Web UIs because this change affects service forwarding browser requests (explained above about web services).
- 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 connect from such a restrictive network.
- 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 you execute the command. 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 number of processes the 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:
- To undo any wrong settings that may lock you out of access to your web services.
- 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 you can fix that with the below commands.
These commands reset the interface names to "all", meaning that 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
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.
Suppose you change the XML-RPC interface setting to full support in the Admin Web UI Client Settings page or via the CLI with the configuration option below. In that case, you can remotely control all Access Server functionality using XML-RPC calls instead. Authentication is done via HTTP basic authentication over a secure SSL connection. A standard user's credentials are sufficient to retrieve a user-locked profile, but only an admin user's credentials are adequate for other functions.
Important: We don't 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
The result shows the XML query and the response. You can use this way of getting information for pretty much every sacli function. And sacli controls just about everything that 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, which breaks 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, allowing full remote control of Access Server's function.
Logging of XML-RPC API calls is disabled by default but can be enabled with an XML-RPC debug flag.
Set maximum number of authentication and database connection QueuePool size
Access Server has default values for the authentication and database threads, which handle requests during active connections. It's possible you could encounter an issue with not having enough threads in these scenarios:
- Out-of-band MFA where an external authentication server (using RADIUS, SAML, or LDAP) processes the extra authentication step, and Access Server isn't aware of or part of the process, which leaves Access Server waiting for that response to complete the authentication process.
- A slower authentication system handling a very high load.
You can use the commands below to increase the authentication and database threads for these situations. We recommend that you increase both so they stay the same number. Increasing the queue sizes resolves cases where the authentication or database calls exceed normal limits.
Set the max database connection QueuePool size:
./sacli --key "mysql.max_overflow" --value "25" configput
service openvpnas restart
The command above sets the number to 25 — increase as needed. The default is 10.
Note: Make sure you restart the service to apply this parameter.
Set the max parallel authentication thread:
./sacli --key "auth.module.max_parallel" --value "25" configput
./sacli start
The command above sets the number to 25 — increase as needed. The default is 8.
Limit total maximum number of VPN tunnels
By default, Access Server allows 2048 VPN tunnels on a single installation, which is usually enough, but if you want to, you can increase that limit. 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 need to reestablish their connection, which should happen automatically.
Change the maximum number of active incoming VPN tunnels:
./sacli --key "vpn.server.max_clients" --value <NUMBER> ConfigPut ./sacli start
Where <NUMBER> is the maximum number of connected VPN tunnels. By default, this configuration key isn't present in Access Server, and when it is not present, it will be assumed to be 2048. You can set it to any valid number of your choice.
UCARP/VRRP failover advanced settings
When you enable and configure Access Server's built-in failover mode, the primary node sends heartbeat signals to the local network. The secondary node monitors these heartbeat signals and takes over if the primary node fails. However, if you have multiple active pairs on the same network or other systems using UCARP/VRRP for automatic failover, the system needs a way to differentiate the signals. For this, Access Server uses 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, change the value of the ucarp.vhid configuration key with the command below, but beware that you should follow the steps carefully 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 two failover events. 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 to ensure that the primary node has had a chance to create a new configuration backup file and relay it to the secondary node. For a brief moment, both nodes will try to be the primary 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 come back online correctly, and the secondary node should be in standby mode again.
Finally, advanced users can pass additional parameters to the UCARP process using 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 to ensure it goes back to 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 containing what you want to pass to UCARP.
Suppose, for example, you want to override the standard scripts that Access Server uses when the node becomes active or has to be a standby node. In that case, you can pass new --upscript and --downscript parameters directly to UCARP and specify new scripts instead. For example, you could 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. If you edit the scripts directly, they will be reset to standard whenever you upgrade or reinstall Access Server. Thus, we recommend creating copies of the up/down scripts to customize instead with the following commands.
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 you can't route private IP addresses on the internet, when VPN clients are connected to Access Server and have been given instructions to send traffic for public IP addresses through the VPN server, Access Server chooses the network interface with the default gateway on it and uses NAT to send traffic out through there. In some cases, it is desirable to disable this NAT behavior, such as 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 to the internet. You can implement the NAT behavior further in the connection chain before it goes onto the public internet. For this, you use a global setting that applies to the entire server for outgoing traffic through NAT. Disabling this setting or specifying a different IP address for outgoing NAT or even a range of addresses randomly selected for outgoing NAT operations is possible. Binding a specific public IP for outgoing NAT operations to a specific VPN client isn't possible.
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 the IP address of a specified interface name.
- interface:number — Source NAT using the IP address of the alias number of the specified interface name.
- interface:begin-range:end-range — Source NAT traffic at random using a range of IP addresses.
The randomization of that last option is done using the Linux/Netfilter to-source algorithm. You must use interfaces and IP addresses that are available, configured, and working correctly on your system. We provide examples of specifying the interface and address for outgoing NAT below.
./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
You can specify multiple rules 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
Settings related to iptables
Access Server heavily uses 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, Access Server prepends to standard chains, which remains the default. Prepending means it tries to come first in an existing list of iptables settings to ensure Access Server works properly. However, you can change this behavior to append instead of prepend using the following config key. This can 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's also possible to completely disable Access Server's activities regarding iptables. However, this may lead to insecure situations as traffic may be allowed through that you didn't permit, and things may no longer function as intended. 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 may completely fail. 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 three distinct iptables items that Access Server manages, all enabled by default, but you have the option to disable them:
- 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)
We don't recommend using Access Server in layer 2 bridging mode. It's considered a deprecated feature. Bridging mode disables much of Access Server's functionality as it no longer implements access control, IP address assignment, etc.
For more about layer 3 and layer 2 refer to our short explanation of the OSI Layer model.
If you still wish to continue and enable layer 2 bridging, use the below command. Only use this with on-premise hardware, as it won't function with cloud-based servers. It's important to note that we don't provide support for this functionality.
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 have Access Server operating on layer 2 bridging mode and upgrade to the latest version, the setting remains intact. An upgrade doesn't break the functionality.
Switching an existing Access Server installation to layer 2 bridging mode requires new connection profiles for VPN clients.
Note: The added complexity of implementing layer 2 bridging mode can cause problems with external equipment, and we don't offer support for this deprecated functionality.
Allow UDP multicast and IGMP to pass through
Access Server transfers information by unicast: only traffic with a specific destination IP address can pass through the VPN server. Access Server blocks multicast or broadcast traffic with a to-whom-it-may-concern characteristic. You can lift the restriction on UDP multicast and IGMP packets allowing these to pass freely between VPN clients and the VPN server. Some software programs use these to auto-detect network systems or services, so this option may be necessary for 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