erroneous.netlify.app

To get an SSL certificate, a Certificate Signing Request (CSR) code is required.

On UniFi controller software, a CSR code is generated along with the default UniFi keystore. Follow these steps to generate the keystore:

1. The username, password, and SSH keys can all be managed from the same place. To modify the credentials, do the following: Log into the UniFi controller. Go to Settings (the gear icon in the bottom-left of the page). Go to the Site section (this is the default section you go to when going to the Settings page).
2. Sep 08, 2016  This video is aimed at using SSH RSA private/public keys as an alternative to password authentication on a Ubiquiti EdgeMax device. The program used in this video is puttygen.
3. Aug 22, 2019  Reconfiguring UniFi controller after a move to new host or a server can be a pain. Wouldn't it be awesome if you were able to migrate UniFi controller to a new server without having to configure everything from scratch? Here is how to do it. Ubiquiti UniFI controller is a web-based management interface for managing several of Ubiquiti.

This article describes how to install an issued SSL certificate on Ubiquiti Unifi server. The methods are grouped by the preferred one for each system (though each method can technically be used for each system with some modifications). General installation method with ace.jar tool SSL Installation options for UniFi.

Step 1: First, connect to the server where the controller is installed with the help of the appropriate command prompt.

1. 1. For Linux-based servers, multiple command prompt (SSH) applications exist. The most common one is Putty. There are versions of Putty for each server type, including Linux servers and Windows servers, as well as the multiple analogues for Android.
   2. For MacOS, use the Terminal application.
   3. For Windows servers, you can connect via remote desktop and use either cmd or PowerShell.

Note: Run all further commands with administrator rights (on Windows) or under the root or sudo user (on Linux/MacOS):

1. To run commands with administrator rights on a Windows server, right-click on the program icon and choose the option Run as administrator. Alternatively, you can click Properties -> Compatibility -> Mark the option ‘Run this program as an administrator’ -> confirm (OK).
2. On Linux-based systems, run sudo su – to set up the required access, or you can start each command with sudo.

Step 2: Generate the CSR code, using the following command:

java -jar *UniFi root*/lib/ace.jar new_cert example.com “Company” “Location (city)” “State or province” “Country code”
(for Linux/Mac OS)

or

java -jar “*UniFi root*libace.jar” new_cert example.com “Company” “Location (city)” “State or province” “Country code”
(for Windows)

1. 1. Type your actual domain or subdomain for UniFi (the certificate common name) instead of example.com.
      Use something like *.example.com for wildcard type certificate.
   2. Company: enter your company name. If you have an Organization or Extended Validation certificate, Certificate Authorities will verify the company information supplied in the CSR code. Domain Validation SSLs don’t have company information embedded into their code. If you are using a DV certificate and don’t have a company, you can just enter N/A.
   3. Location (city): enter your city or locality.
   4. State or province: enter your state or region.
   5. Country: enter the appropriate 2-letter country code from this list.

Important:If any of the CSR values have more than one word, put them in quotation marks (“). Otherwise, the second word will be moved to the value of the next field, which may invalidate the CSR. However, it should be noted that the server will not show an error message if this happens.

Note: The *UniFi root* depends on the system you have UniFi controller installed on:

1. /usr/lib/unifi/ (for UniFi Cloud Key, Ubuntu, and other Debian-based Linux distributions);
2. /opt/unifi/ (for CentOS, RedHat, Fedora, and other RHEL Linux distributions)’;
3. ~/Library/Application Support/UniFi (for Mac OS);
   “%USERPROFILE%/Ubiquiti Unifi” or (which is the same) “C:Users*account username*Ubiquiti UniFi” (for Windows).

Useful tip: Alternatively, open the UniFi root folder first, using the command cd *Unifi root*, and then run the CSR generation command in it. This way you won’t need to specify the full path in the command itself.

You will then receive two files: unifi_certificate.csr.pem and unifi_certificate.csr.der in the /*Unifi root*/data folder. The second file has different formatting and is not used normally.

The text code from the unifi_certificate.csr.pem file can be used for the SSL activation.

Important: Instead of a Private key, UniFi creates a keystore file named keystore in /*UniFi root*/data/ (or simply *UniFi root* on some systems), to which you will only need to upload the certificate files after the issuance.

Step 3: To open the file and extract the text code, do one of the following:

1. On Linux, you can use the command: cat /*UniFi root*/data/unifi_certificate.csr.pem
2. On Mac OS, you can do the same, or go to the data subfolder -> right-click on the unifi_certificate.csr.pem file -> Open with -> choose TextEdit.
3. On Windows, go to the data subfolder -> right-click on unifi_certificate.csr.pem-> Open with -> choose Notepad.
4. Alternatively, you can just use the command:
   notepad “*UniFi root*/data/unifi_certificate.csr.pem”

Footnotes:

If you use the option “Auto-activate” during the SSL activation, this whole process can be skipped. However, it will require a specific installation process.

As a general rule, for UniFi on Windows the “Auto-activate” option may be more convenient, while in other cases it is easier to use the CSR created on UniFi.

This article describes how to install an issued SSL certificate on Ubiquiti Unifi server. The methods are grouped by the preferred one for each system (though each method can technically be used for each system with some modifications).

• SSL Installation options for UniFi on Linux/MacOS
  

General installation method with ace.jar tool

This is the only method described in the official documentation for UniFi. The process itself is relatively simple — just add the SSL files to the keystore created along with the CSR code by following these steps:

Step 1. First, connect to the server where the controller is installed with the help of the appropriate command prompt:

1. 1. For Linux-based servers, multiple command prompt (SSH) applications exist. The most common one is Putty. There are versions of Putty for each server type, including Linux servers and Windows servers, as well as the multiple analogues for Android.
   2. For MacOS, use the Terminal application.
   3. For Windows servers, you can connect via remote desktop and use either cmd or PowerShell.

Important: It is necessary to run all further commands with administrator rights on Windows, or have root or sudo user access on Linux/MacOS.

To run commands with administrator rights on a Windows server, you can right-click the program icon and choose the Run as administrator option, or click Properties -> Compatibility -> Mark the option ‘Run this program as an administrator’ -> confirm (OK).

To set up the required access on Linux-based systems, run sudo su – or just start each command with sudo.

Step 2. Upload the PEM certificate (the .crt file you received from the Certificate Authority), root certificate, and the two intermediate certificates from the downloaded archive on your server. if you received a combined .ca-bundle file instead of separate intermediate and root files, you can open the file with any text editor and save the codes from inside it as separate files.

For any Domain Validation type SSL (like PositiveSSL), the command will look like this:

1. for Linux/Mac OS:java -jar /*UniFi root*/lib/ace.jar import_cert /*Some path*/example.crt /*Some path*/SectigoRSADomainValidationSecureServerCA.crt /*Some path*/USERTrustRSAAddTrustCA.crt /*Some path*/addtrustexternalcaroot.crt
2. for Windows:java -jar “*UniFi root*libace.jar import_cert “*Some path*example.crt” “*Some path*SectigoRSADomainValidationSecureServerCA.crt” “*Some path*USERTrustRSAAddTrustCA.crt” “*Some path*addtrustexternalcaroot.crt”

Note: Replace ‘example.crt’ and ‘Some path…’ with your actual SSL file name and paths to each file. Next, you will need to type in the keystore password (this is aircontrolenterprise, unless it was changed in your UniFi settings) and confirm the certificate’s import.

Important: The root folder name depends on the system UniFi controller is installed on:

1. /usr/lib/unifi/ – for UniFi Cloud Key, Ubuntu, and other Debian-based Linux distributions;
2. /opt/unifi/ – for CentOS, RedHat, Fedora, and other RHEL Linux distributions;
3. ~/Library/Application Support/UniFi – for Mac OS;
4. “%USERPROFILE%/Ubiquiti Unifi”
   or (which is the same)
   “C:Users*account username*Ubiquiti UniFi” – for Windows.

Alternatively, you can open the UniFi root folder first using the command cd *Unifi root*, move all the files there, and then run the installation command in it. By doing it this way you won’t need to specify the full paths in the command itself.

Step 3. Restart the UniFi controller for the changes to apply:

1. 1. On Linux/MacOS, this is: service unifi restart.
   2. On Windows, just close the UniFi application and start it again by clicking on the corresponding icon.

The restart process may take a bit of time depending on your machine and the number of applications running.

And now you’re done!

Important: Some versions of UniFi may show the error, “Unable to import the certificate into keystore”. This is related to the ace.jar inability to parse the new line symbols (n and r) on these particular versions of UniFi.

On Linux and MacOS, you can fix this by simply removing these symbols from each file using the command:

tr -d ‘nr’ < * your file name* echo $(cat -) > *your file name*

Use the name of certificate, intermediate certificate, or root file instead of *your file name*. Apply the command to each file.

On Windows, the certificate files can be fixed using Notepad++:

1. 1. Open the file with Notepad++.
   2. Click ctrl+F and go to the Replace tab.
   3. Click the Extended option to replace the required symbols.
      
   4. Type n in the “Find what” box and click Replace All.
      
   5. Repeat this process using the value r.
   6. Save the file.

SSL Installation options for UniFi on Windows (Keystore Explorer)

The easiest way to install an SSL on UniFi on Windows is to use the “Keystore Explorer”. The process is simple:

1. For SSL activation choose the option “Auto-activate” as you will create a new keystore anyway.
2. Open the current UniFi keystore file in Keystore Explorer using the default password aircontrolenterprise or the one set* for the controller.*Note: The password can be set in the file system.properties in/*UniFi root*/data/with the following parameter:app.keystore.pass=*password*
3. Create the PFX file from the saved Private key file and SSL files. To do this, use this online converter or another similar tool. Alternatively, you can do the following:Put both the certificate and the Private key files in one folder using the same file names and correct extensions.For example, example_com.p7b, example_com.key.Use the following command in cmd or PowerShell to generate the PFX file:certutil -mergepfx example_com.p7b example_com.pfx

   Note: There is no need to mention the key file as it is fetched by default if the key and the certificate files have the same names and corresponding extensions. You will be asked to enter the new password. Set any password for this.Warning: the certutil command may fail sometimes because of how the files are formatted. If this happens, try using another method.

   If you have OpenSSL installed, you can do it the same way:
   “*OpenSSL path*” pkcs12 -export -out “*Some path*example.pfx” -inkey “*Some path*example.key” -in “*Some path*example.p7b” -name “unifi”

4. Go back to Keystore Explorer and delete the unifi entry from your keystore.
   
5. Choose the option: Tools -> Import Key Pair -> PKCS12.Locate your PFX file (example_com.pfx) and import it. Use the same password you set during the PFX creation (step 3).
   
6. For the Key Pair Entry Alias, use unifi.
   
7. Provide the new password. For this, use your default keystore password (this is always aircontrolenterprise, unless you changed it in system.properties).
8. Save the modified keystore file with File -> Save (or simply click on the Save icon).
9. Close the UniFi application and start it again with the corresponding icon to apply changes.Warning: Sometimes, the keystore may get corrupted due to multiple imports. The solution is to delete the initial keystore and restart UniFi to create a new one. You will be able to do the setup after this.
   Note: This tool is also available for Linux/MacOS. However, both systems also have ready-to-use command line options for the process.

SSL Installation options for UniFi on Linux/MacOS

SSL Import using Keytool

This option is quite simple. It doesn’t have parsing issues, and allows for some flexibility. The process itself is similar to the certificate installation on Java-based servers like Tomcat.

Importing PKCS7 file

The most convenient option is to import the file in PKCS#7 format (.p7b or .cer extension) inside the UniFi keystore.

Steps 1-2 are as above.

The Private key for the certificate should be saved in the default UniFi keystore in the file /*UniFi root*/data/keystore after the CSR generation.

3. Upload the certificate file in PKCS#7 format from the received archive on your server.

4. Use the following command to import this file into the keystore:

keytool -import -trustcacerts -alias unifi -file /*Some path*/exmple.p7b -keystore *Unifi root*/data/keystore

Enter the keystore password aircontrolenterprise (unless it was changed in your UniFi settings) and press Enter to complete the import.

5. Restart the UniFi controller to apply the changes:

service unifi restart

Alternatively, you can open the UniFi root folder first using the command cd *Unifi root*. Put all the files in the folder and then run the installation command in it. This way you won’t need to specify the full paths in the command itself.

Warning: You may get the error “Input not an X.509 certificate” during the certificate import. It may be related to the extra empty lines in the file or another formatting issue. If editing the file in a text editor doesn’t help, the best solution is to import the certificate as separate PEM files as described in the next section.

Import with PEM files

If importing the PKCS#7 file results in an error, you can use PEM files (.crt) instead. The following are commands for any Domain Validation SSL type (like PositiveSSL):

1. Import the root certificate first:keytool -import -trustcacerts -alias root -file /*Some path*/addtrustexternalcaroot.crt -keystore /data/keystore
2. Import intermediate certificates one by one, using a separate alias for each:keytool -import -trustcacerts -alias intermediate2 -file /*Some path*/USERTrustRSAAddTrustCA.crt -keystore /data/keystoreandkeytool -import -trustcacerts -alias intermediate1 -file /*Some path*/SectigoRSADomainValidationSecureServerCA.crt -keystore /data/keystore
3. Import your certificate file using the alias unifi:keytool -import -trustcacerts -alias unifi -file /*Some path*/example.crt -keystore /data/keystoreNote: You will need to enter the keystore password after running each command and press Enter to complete the import.

   Tip: To avoid entering the password multiple times, add the argument -storepass *password* at the end of each command. Use your actual password for the UniFi keystore.

4. Restart the UniFi controller to apply the changes:service unifi restart

The files are the same as for the installation method using ace.jar.

Note: The same method can be used on Windows and the process is very similar. However, it should be noted that Windows requires you to use the full path to the keystore application and each file is imported in Windows format.

Import in PKCS#7 will look like this, for example:

“*Java base folder*binkeytool.exe” -import -trustcacerts -alias unifi -file “*some3 path*example.p7b” -keystore “C:Users*account username*Ubiquiti UniFidatakeystore”

SSL import using PFX file

This option should be used if the Certificate Signing Request (CSR) was generated elsewhere, or if you used the “Auto-activate” option during the SSL activation. In this case, a Private key (.key or _key.txt) is provided to you during the process.

You will need to create one PFX file from this key and the SSL files to use later in the process.

Steps 1-2 are described above.

If you prefer doing this process using the command line, the next steps will be:

3. Upload your certificate file (.crt), and chain file (.ca-bundle) or a PKCS#7 file (.p7b/.cer) on the server. Move or upload the previously created Private key file to the same folder for your convenience.

Generate Ssh Key Github

Note: Technically, it is possible to have the files in different folders too; however, this will make the process more complicated.

4. Create the PKCS#12 (PFX) file with this similar OpenSSL command:

openssl pkcs12 -export -out /*Some path*/example.pfx -inkey /*Some path*/example.key -in /*Some path*/example.crt -certfile /*Some path*/example.ca-bundle -name “unifi”

Or openssl pkcs12 -export -out /*Some path*/example.pfx -inkey /*Some path*/example.key -in /*Some path*/example.p7b -name “unifi”

5. Add the created PFX file into the keystore:

keytool -importkeystore -srckeystore /*Some path*/example.pfx -srcstoretype PKCS12 -destkeystore *UniFi root*/data/keystore -deststoretype jks -deststorepass *password*

Use your actual UniFi *password*.

6. Restart the UniFi controller to apply the changes:

service unifi restart

If you prefer generating the PFX elsewhere (for example, with this online tool), your next steps will be: Vault generate new unseal keys.

3. Generate the PKCS#12 (PFX) file using a suitable separate tool.
4. Upload the PFX file on the same server where UniFi controller is installed.
5. Import the created PFX file into the keystore:

keytool -importkeystore -srckeystore /*Some path*/example.pfx -srcstoretype pkcs12 -srcalias 1 -destkeystore /*UniFi root*/data/keystore -deststoretype jks -destalias unifi -deststorepass *password*

Note: For the PFX file generated elsewhere 1 is used as the default alias. Please specify the -srcalias and -destalias to avoid the error, “Alias unifi does not exist”. Use your actual UniFi *password*.

Sometimes the default alias is different. In such a case you can check the alias with any of the following commands:

openssl pkcs12 -in example.pfx -info

keytool -list -storetype pkcs12 -keystore *example.pfx -v

Ubiquiti Ssh Commands

6. Restart the UniFi controller to apply the changes:

service unifi restart

Note: The same process can be done on Windows. For details on how to create the PFX file check the recommended installation method for Windows.

The import itself can be done with a similar command:

“*Java root*binkeytool.exe” -importkeystore -srckeystore “*Some path*example.pfx” -srcstoretype pkcs12 -srcalias 1 -destkeystore “C:Users*account username*Ubiquiti UniFidatakeystore” -deststoretype jks -destalias unifi -deststorepass *password*

*Java root* is specified during the Java installation on your server. By default, it looks like “C:Program FilesJava*Java version*”.

Additional SSL features and tips

Points to consider when setting up an SSL on UniFi:

1. It is not possible to use the ECC certificates on UniFi. The system will allow you to import this kind of file, but the SSL will not work.
2. Server Name Indication (SNI) is also not supported. So, only one keystore with a certificate can be present on the server at the same time.

Additional SSL-related features allowed on UniFi:

1. All versions of UniFi version from 4.x onward automatically enables HTTPS redirect once an SSL is set up. If you enter the default UniFi admin link (by default, https://*UniFi domain name*:8080 in system.properties) then, if the SSL is already installed, you’ll be forwarded to the https:// link (by default, https://*UniFi domain name*:8443).This option works on all UniFi versions starting from 4.x.
2. HSTS can be also enabled on UniFi in the system.properties by uncommenting and modifying these lines:unifi.https.hsts=false – use true to enable HSTS.unifi.https.hsts.max_age=*value* – this specifies how long HSTS is cached for (in seconds).unifi.https.hsts.preload=false – set this to true to add your “UniFi domain name” to the preload list. The HSTs will work until you request its removal from the list.unifi.https.hsts.subdomain=false – set this to true if you would like to also apply HSTS policy for subdomains of your domain name, and not only for the main domain name. Generally, this option is not required as UniFi admin normally uses only one hostname.
3. You can limit cipher suites and SSL/TLS versions used on UniFi in the system.properties by uncommenting and modifying these lines:unifi.https.ciphers=c1, c2, etc. – replace the values c1, c2, etc. with the actual names of the ciphers you want to;useunifi.https.sslEnabledProtocols=p1, p2, etc. – replace the values p1, p2, etc. with the actual names of the protocols you want to use.

   Note: The recommended and light (supports outdated browsers) configurations for UniFi can be checked here.