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.

Installing a signed SSL certificate

OpenVPN Access Server’s web services secure the connection between the web browser and server using an SSL certificate. When you install Access Server, it generates a self-signed certificate. Because of this self-signed certificate, the first time you sign in to the Admin Web UI or Client UI, you must click through a warning in your browser. This is expected. We recommend replacing the self-signed certificate with your own, signed certificate, so you don’t have to continually bypass the warning message.

These are the steps you can take to install a signed SSL certificate for a fully qualified domain name (FQDN) for accessing your web services — the Admin Web UI and Client UI — in a web browser.

1. Assign an FQDN to Access Server.
2. Set the required DNS record.
3. Generate a private key.
4. Use the key to create a certificate signing request (CSR).
5. Send the CSR to a trusted party to validate and sign.
6. Install the signed certificate, private key, and intermediary file.

You can configure the certificates and keys in the Admin Web UI on the Web Server configuration page. Below are the commands if you prefer to set this up with the command line interface (CLI).The commands below require you to be logged into your server with root privileges and run them in the /usr/local/openvpn_as/scripts/ directory.

Self-signed certificate location

Access Server saves the self-signed certificates in a directory on the server: /usr/local/openvpn_as/etc/web-ssl/. It uses the following command to generate the initial, self-signed certificates:

./certool -d ../etc/web-ssl --type ca --unique --cn "OpenVPN Web CA"
./certool -d ../etc/web-ssl --type server --remove_csr --sn_off

Technically, you could replace the files in that directory with your own private key, certificate, and intermediary bundle files, but we don’t recommend that. We recommend using the configuration keys designed to hold these files. Once you define the configuration keys, the web services refer to them for the Admin Web UI and Client UI. When they don’t exist (the default), Access Server uses the self-signed certificates in the web-ssl instead. Thus, we recommend you consider the files in the web-ssl folder as a fallback in case of an issue with the certificates loaded into the configuration database.

If you replaced the self-signed certificates in the web-ssl folder, we recommend you import the files to the configuration database key values.Convert /usr/local/openvpn_as/etc/web-ssl files to configuration database key values:

./sacli --import GetActiveWebCerts

Set up the configuration database keys

The commands below set the configuration database keys for the private key, certificate, and intermediary bundle file. Ensure that each necessary file is saved to a location on the server. Our example uses a directory, /etc/webcerts/vpn.yourdomain.com/.

Note: Ensure the certificates are formatted as PEM files. Access Server doesn’t accept .p12 or .pfx formatted certificates. You can convert files from .pfx to PEM type with the DigiCert Certificate Utility for Windows.

Store the private key file in the configuration database:

./sacli --key "cs.priv_key" --value_file "/etc/webcerts/vpn.yourdomain.com/privatekey.pem" ConfigPut

Store the certificate file in the configuration database:

./sacli --key "cs.cert" --value_file "/etc/webcerts/vpn.yourdomain.com/crt.pem" ConfigPut

Store the CA bundle file in the configuration database:

./sacli --key "cs.ca_bundle" --value_file "/etc/webcerts/vpn.yourdomain.com/intermediary_bundle.pem" ConfigPut

Test the certificates

Prior to restarting the web server to begin using the new certificates, you can validate the files using the following command:

./sacli --ca_bundle=/etc/webcerts/vpn.yourdomain.com/intermediary_bundle.pem --cert=/etc/webcerts/vpn.yourdomain.com/crt.pem --priv_key=/etc/webcerts/vpn.yourdomain.com/privatekey.pem TestWebCerts

The output should display information about SSL certificates with their values, not errors or warnings.

Restart Access Server web service

Once the private key, certificate, and intermediary bundle files are all set, restart the Access Server web service and begin using the new certificates:

./sacli start

Multiple intermediary files

What if you have additional files? In many cases, you receive more files that provide the links in the chain of trust between your signed certificate and the root authority known in your web browser as a trusted party. If you’ve received more than one intermediate file, create a new text file, paste one after the other into the new file, save it, and import it.

Remove the keys and fall back to the self-signed certificates in the web-ssl directory:

./sacli --key "cs.priv_key" ConfigDel
./sacli --key "cs.cert" ConfigDel
./sacli --key "cs.ca_bundle" ConfigDel
./sacli start

Verify the web certificates

To verify that you correctly installed the web SSL certificates, we recommend using online tools such as the DigiCert SSL Installation Diagnostics Tool or Qualys SSL Labs SSL Server Test. We also recommend additional security steps, including adjusting the TLS settings and web server cipher suite string.

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.

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

1. Displaying your business logo on the Admin Web UI and Client UI login screens.
2. Adding a description text string to display on the Admin Web UI.
3. 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

Specify custom HTTP headers

The web server built into Access Server 2.9.4 and above can be provided with additional HTTP headers. This is useful for situations where security scanners test the web interface and require certain headers to be present. You can set multiple headers by specifying multiple configuration keys.

An example setting two custom headers:

./sacli --key "cs.http_headers.0" --value "Custom Header: one" ConfigPut
./sacli --key "cs.http_headers.1" --value "Another Header: one two three" ConfigPut
./sacli start

To remove a custom header:

./sacli --key "cs.http_headers.0" ConfigDel
./sacli start

Note: These new custom HTTP headers are not checked for validity. They also are not meant to override headers that Access Server already implements.

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.