| Subtotal | $0.00 |
USD
U.S. DollarEuroBritish PoundCanadian DollarsAustralian DollarsIndian RupeesChina Yuan RMBMore Info →
| Subtotal | $0.00 |
Official documentation for UniFi controller describes one way to install the SSL. This method is relatively simple although there is a common issue related to it where the error message does not indicate the actual root. This guide is meant to describe a variety of alternative installation methods, how to fix these common errors, and provide useful security enhancement tips.
Important note: When installing SSL on Unifi CloudKey, a default server certificate is sometimes used instead of the installed one which may cause security warnings in browser. In order to avoid this situation, please complete the below steps:
service unifi stop
rm /usr/lib/unifi/data/keystore && cp /etc/ssl/private/unifi.keystore.jks /usr/lib/unifi/data/keystore
/etc/default/unifiUNIFI_SSL_KEYSTORE=/etc/ssl/private/unifi.keystore.jks
service unifi start
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:
cmd or PowerShell (connected via remote desktop if needed).Important: Make sure that you start the application with administrator rights on Windows. To do this, right-click the program icon and choose 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, you can run the following command on the Linux-based system:
sudo su -
cd *Unifi base folder*
The *Unifi base folder* needs to be replaced with the following:
/usr/lib/unifi//opt/unifi/~/Library/Application Support/UniFi"%USERPROFILE%/Ubiquiti Unifi" or "C:\Users\*account username*\Ubiquiti UniFi"
java -jar lib/ace.jar import_cert *your certificate*.crt SectigoRSADomainValidationSecureServerCA.crt USERTrustRSAAddTrustCA.crt addtrustexternalcaroot.crt
Note: *your certificate* should be replaced with your actual file name. UniFi will ask to enter the keystore password (aircontrolenterprise unless it was changed in your UniFi settings) and confirm the certificate’s import.
Tip: Add sudo at the beginning of the command on Linux/MacOS if you are not logged in as root.
service unifi restart
On Windows, simply close the UniFi application and start it again using the application icon.
If UniFi is configured as a Windows service, you can do this with the following commands:
net stop "UniFi Controller"
net start "UniFi Controller"
The restart process may take a bit of time depending on your machine and a number of applications running. And now you’re done!
Important: There is a known bug on some of the most common modern UniFi versions: after importing the files on the server, an error “Unable to import the certificate into keystore” shows up.
The issue is related to the fact that ace.jar on these UniFi versions is unable to parse the new string (\n) symbol.
On Linux and MacOS, this issue can be resolved by removing such symbols with a simple command:
tr -d '\n\r' < *file name* > *temporary file name* && mv *temporary file name* *file name*
Replace the *file name* with the full name of the required file. Apply the command to your certificate, to each of intermediate certificates, and to the root certificate.
The *temporary file name* is required as a temporary file because the command does not allow it to save the modified content in the same file directly. Therefore it’s required to save it in a temporary place and then replace the old one with it.
Alternatively, you can use this command:
tr -d '\n\r' < *file name* | echo $(cat -) > *file name*
On Windows, the certificate files can be fixed using Notepad++:
ctrl+F and go to the tab Replace.
\n in the form and click Replace All.
\r.This option is the most reliable since it’s relatively simple, does not have parsing issues, and allows for some flexibility. Import process with a keytool is very similar to the installation on Tomcat server.
The simplest option is to import the file in PKCS#7 format (.p7b or .cer extension) inside the keystore.
Steps 1-2 are described above.
The Private key for the certificate should be saved in the default UniFi keystore in the file /data/keystore after the CSR generation.
keytool -import -trustcacerts -alias unifi -file *your certificate*.p7b -keystore /data/keystore
Enter the keystore password aircontrolenterprise (unless it was changed in your UniFi settings) and press Enter to complete the import.
service unifi restart
And now you’re done!
Warning: You may receive the error “Input not an X.509 certificate” while importing the SSL in 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, the best solution is to import the SSL as PEM files.
On Windows, it’s also possible to use this solution:
Alternatively, you can import the SSL file in PEM format (.crt). The example below is for the standard Domain Validation certificate:
keytool -import -trustcacerts -alias root -file addtrustexternalcaroot.crt -keystore /data/keystore
keytool -import -trustcacerts -alias intermediate2 -file USERTrustRSAAddTrustCA.crt -keystore /data/keystore keytool -import -trustcacerts -alias intermediate1 -file SectigoRSADomainValidationSecureServerCA.crt -keystore /data/keystore
unifi: keytool -import -trustcacerts -alias unifi -file *your certificate*.crt -keystore /data/keystore-storepass *password* at the end of the command. Replace the *password* with your actual password for the UniFi keystore. service unifi restartThe files are the same as for the Standard installation method with ace.jar.
In general, the process is exactly the same as it is on Linux. There is one component that should be taken into account, though. Windows requires the full path to be specified if you are running an application or need to access the file that’s not located in the same folder where you run the command.
The PKCS#7 import command will look like this:
“*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 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*
and then:
keytool -import -trustcacerts -alias unifi -file “C:\Users\*account username*\Ubiquiti UniFi\*your certificate*.p7b” -keystore “C:\Users\*account username*\Ubiquiti UniFi\data\keystore”
start it again using the application icon. net stop "UniFi Controller"
net start "UniFi Controller"
Import for PEM certificates can be done as described above, specifying the full path to the files in all commands.
The easiest way is to import the PFX on UniFi on Windows is with the help of “Keystore Explorer” (it can be used for Linux/Mac OS also, though, it is best suited for Windows).
aircontrolenterprise or the one used by the controller.system.properties file and add your custom password in it: app.keystore.pass=*password*
data subfolder of UniFi base folder.unifi entry.
unifi.
aircontrolenterprise unless it was changed in your UniFi settings). service unifi restart
net stop "UniFi Controller" net start "UniFi Controller"
This option can be used if the Certificate Signing Request (CSR) was generated elsewhere or the OpenSSL was used during the process instead of default UniFi tool.
In such a case, a private key (.key) is created separately. It’s required to import the key file into the keystore along with the certificate (.crt) and chain (.ca-bundle) files.
Steps 1-2 are the same as above.
If you prefer doing all process through the command line:
3. Upload the PEM security certificate file (.crt), and chain file (.ca-bundle) received in an archive from the Certificate Authority into the UniFi base folder. Move or upload the previously generated private key file in the same folder for your convenience.
Technically, you can put them in different folders; however, in such a case, make sure to add the full path to the files in command.
4. Generate the PKCS#12 (PFX) file using the similar OpenSSL command:
openssl pkcs12 -export -out *your certificate*.pfx -inkey *your certificate*.key -in *your certificate*.crt -certfile *your certificate*.ca-bundle -name "unifi"
5. Import the created PFX file into the keystore:
keytool -importkeystore -srckeystore *your certificate*.pfx -srcstoretype PKCS12 -destkeystore /data/keystore -deststoretype jks -deststorepass *password*
Replace the *password* with your actual password for the UniFi keystore.
6. Restart the UniFi controller to apply the changes:
service unifi restart
If you prefer generating the PFX elsewhere (e.g. our converter):
3. Generate the PKCS#12 (PFX) file using any convenient tool.
4. Upload the PFX file on the server where UniFi controller is installed (in the UniFi base folder).
5. Import the created PFX file into the keystore:
keytool -importkeystore -srckeystore *your certificate*.pfx -srcstoretype pkcs12 -srcalias 1 -destkeystore /data/keystore -deststoretype jks -destalias unifi -deststorepass *password*
6. Restart the UniFi controller to apply the changes:
service unifi restart
PLEASE NOTE: For the PFX file without an alias assigned, 1 is used as the default alias. Ensure you specify the -srcalias and -destalias to avoid an error “Alias unifi does not exist”. Replace the *password* with your actual password for the UniFi keystore.
There is a small chance that default alias is different. If you face an error with it, 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
The process is similar to the installation on Linux. The PFX file can be generated this way:
cmd or PowerShell: certutil -mergepfx *your certificate*.p7b *your certificate*.pfx *OpenSSL path* pkcs12 -export -out *your certificate*.pfx -inkey *your certificate*.key -in *your certificate*.crt -certfile *your certificate*.ca-bundle -name "unifi"
“C:\*OpenSSL version*\bin\OpenSSL.exe”. “*Java base folder*\bin\keytool.exe” -importkeystore -srckeystore *your certificate*.pfx -srcstoretype pkcs12 -srcalias 1 -destkeystore “C:\Users\*account username*\Ubiquiti UniFi\data\keystore” -deststoretype jks -destalias unifi -deststorepass *password*
*Java base folder* is specified during the Java installation on server. By default, it is something like “C:\Program Files\Java\*Java version*\”. net stop "UniFi Controller" net start "UniFi Controller"Here we list some features not directly related to the SSL setup although they’re related to site security and different ways to configure them.
*hostname*:8080 in system.properties) then, if the SSL is already installed on UniFi, you’ll be forwarded to the https:// link (by default, https://*hostname*:8443).4.x.system.properties file by modifying these parameters:unifi.https.hsts=false - set to true to enable HSTSunifi.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 specificallyunifi.https.hsts.subdomain=false - set to true if you would like to apply HSTS policy for subdomains of your domain name, as well as for the main domain nameunifi.https.ciphers=cipher1, cipher2, etc. - replace the values with the actual cipher names you want to enableunifi.https.sslEnabledProtocols=protocol1, protocol2, etc. - replace the values with the actual protocol names you want to enableNeed help? We're always here for you.