Managing settings for the web services from the command line
OpenVPN Access Server includes web services that provide you with a powerful web-based administrative GUI for managing your VPN configurations and a clean download page for your users to download OpenVPN Connect and connection profiles. This document provides commands for configuring options and settings for these web services. You can also configure the web services in the Admin Web UI.
Managing SSL certificates
To read more about how OpenVPN Access Server manages the self-signed certificate and how to install a valid signed certificate (recommended) refer to these two documents below. They include command line parameters.
- SSL web certificate behavior in Access Server
- Installing a valid SSL web certificate in Access Server
Note: The SSL web certificates are not related to VPN certificates. VPN certificates are separate and managed differently. Alterations to the web certificates will have no effect on VPN certificates.
Branding — change logo on web interface
OpenVPN Access Server supports the following branding options:
- Displaying your business logo on the Admin Web UI and Client UI login screens.
- Adding a description text string to display on the Admin Web UI.
- Removing the “powered by OpenVPN” footer.
Refer to Branding configurations on the Admin and Client web server interfaces for detailed steps on how to make these changes.
Note: There are no branding options for our free VPN client, OpenVPN Connect.
Web server identification string
You can change the "Server" HTTP header that the Access Server's built-in web server uses to identify itself to clients (browsers). One reason for modifying this would be for an automated scan attempting to determine the web server software used and attempting to use exploits on that gets confused and can’t determine what software is being used. Making this change doesn’t affect security very much, other than security through obscurity, but some security scan programs can 'fail' on this and therefore we have made it possible to customize this identification string.
Set a custom web server name:
./sacli --key "cs.web_server_name" --value "HAL9000" ConfigPut ./sacli start
Web session timeout
By default, whenever you authenticate to the CWS (Client Web Service or Client UI) or the AWS (Admin Web Service or Admin Web UI) your session remains active for a limited time. As long as you stay active on the web interface by navigating, refreshing pages, or submitting changes, you remain logged on, but the inactivity threshold is set to 30 minutes, by default. This setting can be altered to any value in seconds. So for example if you wanted to set a timeout of 10 minutes, you would set it to 600 (60*10). The server assumes the default value of 1800 (30 minutes) if the configuration key sa.session_expire doesn't exist.
See the current setting (if nothing shows it's the default of 1800 seconds):
./sacli ConfigQuery | grep -i "sa.session_expire"
Set the web session inactivity timeout to five minutes:
./sacli --key "sa.session_expire" --value "300" ConfigPut ./sacli start
Remove the key so it resets to its default of 30 minutes:
./sacli --key "sa.session_expire" ConfigDel ./sacli start
Selecting a custom cipher suite string for the web server
Web services protected with HTTPS must define which encryption ciphers they support. This is always a balance of security versus compatibility. If the security is very high, older platforms like Windows XP won’t be able to access the web interface. We try to choose a default that supports operating systems and currently supported web browsers. You may adjust this cipher suite string to your needs.
For information about what the cipher suite string can contain, refer to OpenSSL’s site:
https://www.openssl.org/docs/man1.1.0/apps/ciphers.html
The default cipher suite string in Access Server as of 2.0.14 is DEFAULT:!EXP:!PSK:!SRP:!LOW:!RC4.
The default cipher suite string in Access Server as of 2.9.1 is DEFAULT:!MEDIUM:!LOW:!kDH:!kECDH:!DSS:!PSK:!SRP:!kRSA
List the current string (if nothing shows the default above applies):
./sacli ConfigQuery | grep -i "cs.openssl_ciphersuites"
Set a custom example string:
./sacli --key "cs.openssl_ciphersuites" --value 'DEFAULT:!MEDIUM:!LOW:!kDH:!kECDH:!DSS:!PSK:!SRP:!kRSA' ConfigPut ./sacli start
Note: You must use single quotes instead of double quotes around the cipher suite string.
The cluster API port on TCP 945 for inter-node communication in a cluster has a separate configuration key for the cipher suite string as of Access Server 2.9.1. By default, it inherits whatever is set for the main web services, but it can be specified separately with the ssl_api.openssl_ciphersuites configuration key.
Verify which ciphers your web server supports using the nmap tool:
nmap --script ssl-enum-ciphers -p 443 vpnserver.yourdomain.com
Reset the cipher suite string settings to default by deleting the configuration keys:
./sacli --key "cs.openssl_ciphersuites" ConfigDel ./sacli --key "ssl_api.openssl_ciphersuites" ConfigDel ./sacli start
Selecting SSL and TLS levels on the web server
The TLS level for the web server can be configured in the Admin Web UI — click Configuration > TLS Settings. To set the TLS levels using the command line, use these commands in this section. We recommend using TLS 1.2 or higher. We suggest not altering TLS-level settings for the OpenVPN daemons unless you know what implications this can have for existing installations. We recommend reading about setting the TLS level on the OpenVPN daemons for that particular setting.
List the current TLS level (if nothing is shown, TLS 1.1 applies as default starting with Access Server 2.1.12):
./sacli ConfigQuery | grep -i "cs.tls_version_min"
The cluster API port on TCP 945 for inter-node communication in a cluster has a separate configuration key for the minimum TLS level version as of Access Server 2.9.1. By default, it inherits whatever is set for the main web services, but it can be specified separately with the ssl_api.tls_version_min configuration key.
Set the web services minimum requirement of TLS 1.2 or higher:
./sacli --key "cs.tls_version_min" --value "1.2" ConfigPut ./sacli start
Valid values for the cs.tls_version_min and ssl_api.tls_version_min setting are:
- 1.0 - require TLS 1.0 or higher.
- 1.1 - require TLS 1.1 or higher.
- 1.2 - require TLS 1.2 or higher.
- 1.3 - require TLS 1.3 or higher.
Note: The OpenSSL library that comes with your operating system that your Access Server is installed on must support the selected value. On older operating systems, OpenSSL did not yet support TLS 1.3, so it will not function on those platforms. On newer operating systems, TLS 1.0 and TLS 1.1 are automatically upgraded by OpenSSL to TLS 1.2.
Reset the minimum TLS level settings to default by deleting the configuration keys:
./sacli --key "cs.tls_version_min" ConfigDel ./sacli --key "ssl_api.tls_version_min" ConfigDel ./sacli start
Set the interface and ports for the web services
There are three web services in total in Access Server:
- Admin Web UI — Administrative web interface on port TCP 943/443.
- Client Web UI — End-user interface for the client program on port TCP 943/443.
- Cluster web API — Inter-cluster API communication on port TCP 945.
The cluster web API is only used when Access Server is in cluster mode, where multiple nodes work together to create a high-availability and load-balancing solution. By default, the Client UI and Admin Web UI are both present on the same port with the Client UI at the root / URL and the Admin Web UI at the /admin URL.
The OpenVPN TCP daemons are on port TCP 443, by default, which is also the standard HTTPS port for web services. We chose this port for the TCP OpenVPN daemons because it is likely that simpler firewalls allow this through, whereas UDP 1194 where the UDP daemons live, might be blocked. To allow an easier user-experience, the OpenVPN TCP daemons can recognize web browser requests and internally forward these to where the Client UI and Admin Web UI services actually reside. We call this service forwarding (more on this below). This allows accessing the web services through a URL like https://vpn.example.com/ without a need to specify the exact port.
If you turn off or change the service forwarding settings, or alter the OpenVPN TCP daemon port, this automatic internal redirection of browser requests on port TCP 443 won’t work. If you then stop the OpenVPN daemons, you won’t be able to access the web services on the default HTTPS port. In such a case you must connect to the web services directly at their default port TCP 943 in the web browser:
https://your.vpnserver.com:943/
By default, the web services and OpenVPN daemons listen on all interfaces. You can change this in the Admin Web UI — click Configuration > Network Settings. You can even set different interfaces and ports for the Admin Web UI and the Client UI. All of these settings are also available on the command. You can change the interface and ports where the OpenVPN daemons listen for incoming OpenVPN tunnel connections. The command line examples below show you how to change where the web services listen.
Set the interface and port for the Admin Web UI:
./sacli --key "admin_ui.https.ip_address" --value <INTERFACE> ConfigPut ./sacli --key "admin_ui.https.port" --value <PORT_NUMBER> ConfigPut ./sacli start
Set the interface and port for the Client UI:
./sacli --key "cs.https.ip_address" --value <INTERFACE> ConfigPut ./sacli --key "cs.https.port" --value <PORT_NUMBER> ConfigPut ./sacli start
Set the interface and port for the cluster web API:
./sacli --key "ssl_api.local_addr" --value <INTERFACE> ConfigPut ./sacli --key "ssl_api.local_port" --value <PORT_NUMBER> ConfigPut ./sacli start
Restore the default settings:
./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 start
Note: When you set the Admin Web UI and Client UI on different interfaces or ports, the Admin Web UI moves to the root URL and no longer uses /admin in the URL. Adding /admin to the URL is only used when Access Server listens on the same interface and port as the Client UI.
Change the web service forwarding settings
The OpenVPN TCP daemon and the web services are connected. This is done with service forwarding which internally redirects web browser requests made to the OpenVPN TCP daemon, running on the default HTTPS port TCP 443, to where the web services are actually running. Service forwarding can be disabled if you want to.
When you install Access Server it is configured by default with an OpenVPN TCP daemon on port TCP 443, and with the web services on port TCP 943. The Client UI and Admin Web UI are by default on the same port, but separated by a slightly different URL (/admin for the Admin Web UI). To make things a little easier we have created an internal automatic redirection for web browser requests that come in on the OpenVPN TCP daemon running on TCP 443 to point to where the web services run. If we didn't do this then you would always have to manually specify the port to make a connection to the web services, whereas with service forwarding enabled the address is simply https://vpn.yourserver.com/ instead of with the port manually specified as https://vpn.yourserver.com:943/.
When you change the interface or port settings where the web services listen, but leave service forwarding enabled, you can still access the web services on the interface and port where the OpenVPN TCP daemon is listening. And if you change settings related to where the OpenVPN TCP daemon is listening, then you have to be aware that if you were contacting the web services through that daemon, then you may lose connection to the web services depending on your configuration. But you can of course still reach the web services at the actual interface and port they are listening on.
An important note about the Client UI: this web service is used for the server-locked connection profiles that come included by default in the OpenVPN Connect app for Windows and Macintosh. If you make the client web UI completely unreachable for your users, by for example disabling service forwarding and blocking access to port TCP 943 where the web services run, then server-locked profiles can no longer work. Users receive a message about the XML-RPC interface being unreachable and they can't authenticate and connect. You must either keep the Client UI reachable for your users or to have all users obtain a user-locked or auto-login type profile from the administrator of the server and import this file into the OpenVPN client program. It's worth noting that you can keep the client UI online and working with server-locked profiles, while denying them the ability to login at the web page itself by restricting logins at the Client UI to admin users only.
Disable service forwarding for the Admin Web UI, but leave it enabled for the Client UI only:
./sacli --key "vpn.server.port_share.enable" --value "true" ConfigPut ./sacli --key "vpn.server.port_share.service" --value "client" ConfigPut ./sacli start
Disable service forwarding for the Client UI, but leave it enabled for the Admin Web UI only:
./sacli --key "vpn.server.port_share.enable" --value "true" ConfigPut ./sacli --key "vpn.server.port_share.service" --value "admin" ConfigPut ./sacli start
Disable service forwarding for both the Admin Web UI and Client UI:
./sacli --key "vpn.server.port_share.enable" --value "false" ConfigPut ./sacli --key "vpn.server.port_share.service" --value "custom" ConfigPut ./sacli start
Enable service forwarding for both the Admin Web UI and Client UI (default):
./sacli --key "vpn.server.port_share.enable" --value "true" ConfigPut ./sacli --key "vpn.server.port_share.service" --value "admin+client" ConfigPut ./sacli start
Note: When you set the Admin Web UI forwarding on but disable Client UI forwarding, it no longer requires /admin at the end of the URL when accessing through service forward. That is because there are no longer two services co-existing on the same web service.
Configure a custom redirection — only works with IP addresses on the server itself, nothing external:
./sacli --key "vpn.server.port_share.enable" --value "true" ConfigPut ./sacli --key "vpn.server.port_share.service --value "custom" ConfigPut ./sacli --key "vpn.server.port_share.ip_address --value <LOCAL_IP> ConfigPut ./sacli --key "vpn.server.port_share.port --value <PORT> ConfigPut ./sacli start
Using the method above, you might run the OpenVPN TCP daemon on port TCP 443, have the Access Server web services on its standard port TCP 943, and at the same time serve pages from an Apache2 or Nginx web server (or other SSL capable web server) through port TCP 443 via service forwarding. And technically, if you really wanted to for some reason, you can make service forwarding to an external address possible by using iptables to redirect a port on a local interface to an external system.
To reset the web services and daemons back to their defaults, refer to the corresponding section on Advanced option settings on the command line.