Having trouble with your SSL? We have an installation service for that.
Official documentation for the UniFi controller includes one method of installing an SSL. This method is relatively simple; however, there is a common issue involving an error message that doesn’t indicate the actual root.
This guide outlines various alternative installation methods, shows how to fix common errors, and provides useful security enhancement tips.
Please note, that the part /etc/ssl/private/unifi.keystore.jks should be replaced with the path to your new Keystore where the new certificate files are located.
This method is generally recommended, although it has some peculiarities, so it isn't always the most reliable.
The certificate should be installed in the folder where the CSR code was generated. Follow the steps below to complete the SSL installation using ace.jar:
Important: Make sure to start the application with administrator rights on Windows. To do this, right-click on the program icon and choose the Run as administrator option or do it this way:
Properties >> Compatibility >> mark the Run this program as an administrator >> OK.
On Linux/MacOS, you should have root or sudo user access. For this, run the following command:
sudo su -
To start the installation, open the UniFi shell to access the UDM files:
unifi-os shell
Use the following command:
java -jar lib/ace.jar import_cert *your certificate*.crt SectigoRSADomainValidationSecureServerCA.crt USERTrustRSAAddTrustCA.crt addtrustexternalcaroot.crt
Where *your certificate* is replaced with your actual file name.
If you received the intermediate and root certificates in one bundled file (.ca-bundle), you can download them separately here.
Note: that the example command above contains intermediate certificates for the standard Domain Validation type SSL.
Keep in mind that some server versions may require the whole CA Bundle to be uploaded as a single file. In such a case, you can download the corresponding bundle following the instructions in this article and use the following command:
java -jar lib/ace.jar import_cert *your certificate*.crt bundle.crt
This option does not have parsing issues and allows for some flexibility. Importing with a keytool is very similar to installation on a Tomcat server.
Inside the keystore, import the file in the PKCS#7 format (with a .p7b or .cer extension).
Follow Steps 1-3 in the Standard ace.jar method.
Save the certificate's Private key to the /data/keystore file in the default UniFi keystore after you generate the CSR code.
Enter the keystore password "aircontrolenterprise" (unless it was changed in your UniFi settings) and press Enter to complete the import.
And now you're done! You can check the installation here.
Warning: You may receive the error "Input not an X.509 certificate" while importing the SSL in the PKCS#7 format. It may be related to the extra empty strings in the file or other formatting issues. If editing the file in a text editor does not help, importing the SSL as PEM files is best.
On Windows, you can also use this solution:
Alternatively, you can import the SSL file in PEM format (.crt).
The example below uses files for a Domain Validation certificate. The process is similar for other SSL types. Find the corresponding files here.
keytool -import -trustcacerts -alias intermediate1 -file SectigoRSADomainValidationSecureServerCA.crt -keystore /data/keystore
The files are the same as for the Standard installation method with ace.jar.
You can use this option if the CSR was generated elsewhere or the OpenSSL method was used instead of the default UniFi tool during the process.
In this case, a private key (.key) is created separately. You need to import the key file into the keystore along with the certificate (.crt) and chain (.ca-bundle ) files.
Steps 1-3 are the same as in the Standard method with ace.jar.
If you prefer carrying out the process through command line, follow these steps:
Technically, you can put them in different folders; if you do, add the full paths to the files in the commands in the following steps where these files are used.
If you prefer generating the PFX elsewhere (e.g. our converter), do the following:
PLEASE NOTE: For the PFX file without an alias assigned, 1 is used as the default alias. Also, ensure you include -srcalias and -destalias in the command to avoid the error, "Alias unifi does not exist". The *password* value should be replaced with your actual password for the UniFi keystore.
There is a small chance that the default alias is different. If you encounter an error, you can check the alias with any of the following commands:
openssl pkcs12 -in *your certificate*.pfx -info
keytool -list -storetype pkcs12 -keystore *your certificate*.pfx -v
For UDM-pro you only need to replace the default private key and self-signed certificate and restart UDM.
Settings >> Network Settings >> Device Authentication >> Turn it on and set up the username and password (or generate an access key, which is an alternative option that you will be offered at the last step).
There are two files inside the folder:unifi-core.crt and unifi-core.key. These are a self-signed certificate and a Private key, respectively.
To install the valid SSL they should be replaced with an actual certificate received from the CA and a corresponding Private key
You can combine the .crt and .ca-bundle files you received from the CA in multiple ways:
To open it in the command line, use any provided Linux editor like nano or vi (for example, run nano unifi-core.crt ).
All installation methods described for UDM-base work similarly on older UniFi controller versions. However, a few methods cannot be used for UDM even though they were valid in the past. They are described below.
The process is generally the same as on Linux: you upload the files to the server and run the keytool commands to install them in the keystore. However, there is one difference. Unlike Linux-based servers, Windows requires a full path to be specified when you are running an application. Because keytool.exe, certificate files, and the keystore may be located in different folders, make sure to use the full path unless the file is in the folder where you run the command.
To import the files in the PKCS#7 format by running this command:
"*Java base folder*\bin\keytool.exe" -import -trustcacerts -alias unifi -file *your certificate*.p7b -keystore "C:\Users\*account username*\Ubiquiti UniFi\data\keystore
*Java base folder* is specified during the Java installation on the server. By default, it is something like "C:\Program Files\Java\*Java version*\".
Alternatively, run the command below to switch to the Java base folder:
cd *Java base folder*
If UniFi is configured as a Windows service, run these commands:
net stop "UniFi Controller"
net start "UniFi Controller"
The certificate should now be installed.
Importing PEM certificates can be performed as described in the Importing PEM section, specifying the full path to the files in all commands.
The easiest way to import the PFX on UniFi on Windows is with the help of "Keystore Explorer". (It can also be used for Linux/Mac OS, though it is best suited for Windows).
TIP: You can open the system.properties file and add your custom password to it:
app.keystore.pass=*password*
Restart the controller to apply the changes.
On Linux:
service unifi restart
On Windows, close the UniFi application and start it again using the application icon or, if UniFi is configured as a Windows service, use the commands:
net stop "UniFi Controller"
net start "UniFi Controller"
WARNING: Sometimes, the keystore may get corrupted because of multiple imports. If the process does not work properly, delete the initial keystore file and restart UniFi to create a new one, and only proceed with the PFX import when this is done.
This process is similar to installation on Linux. The PFX file can be generated by doing the following:
*OpenSSL path* pkcs12 -export -out *your certificate*.pfx -inkey *your certificate*.key -in *your certificate*.crt -certfile *your certificate*.ca-bundle -name "unifi"
Default OpenSSL path on Windows (if you have it installed) is "C:\*OpenSSL version*\bin\OpenSSL.exe".
The SSL should now be installed.
The following list includes features not directly related to SSL setup but related to site security and different ways to configure it.
unifi.https.hsts=false - set to true to enable HSTS
unifi.https.hsts.max_age=*value* - you can specify the duration for how long HSTS is cached (in seconds)
unifi.https.hsts.preload=false - set to true only if you do not plan to remove the HSTS, as it will add your UniFi hostname to the preload list, deletion from which should be requested specifically
unifi.https.hsts.subdomain=false - set to true if you would like to apply an HSTS policy for the subdomains of your domain name, as well as for the main domain name
Uncomment the corresponding (above-mentioned) strings, save the file, and restart UniFi to complete the process.
Permitted cipher suites and SSL/TLS versions can be enabled on UniFi in the system.properties file using the following parameters:
unifi.https.ciphers=cipher1, cipher2, etc. - replace the values with the actual cipher names you want to enable
unifi.https.sslEnabledProtocols=protocol1, protocol2, etc. - replace the values with the actual protocol names you want to enable
Uncomment the corresponding (above-mentioned) strings, save the file, and restart UniFi to complete the process.
Check the optimal configurations for UniFi here.
Need help? We're always here for you.