Fix UniFi Overwriting SSL Certificate: Uosserver Start Issue

by Felix Dubois 61 views

Hey guys! Ever run into that pesky issue where your UniFi setup keeps overwriting your Let's Encrypt certificate with the default self-signed one? It's super frustrating, especially when you've gone through the trouble of setting up SSL properly. Today, we're diving deep into this problem, inspired by a real-world scenario from one of our users, MiranoVerhoef, who encountered this with the UniFi-OS-Server-SSL-Import script. We'll explore why this happens and, more importantly, how to fix it. Let's get started!

Understanding the Issue

The core issue, as MiranoVerhoef pointed out, revolves around the uosserver start command. This command, crucial for starting the UniFi OS server, inadvertently triggers a process that replaces the custom unifi-core.crt certificate with the default unifi.local certificate. This usually happens shortly after the script to install Let's Encrypt certificates runs, making all your hard work seem like it vanished into thin air. Why does this happen? Well, the UniFi OS has a built-in mechanism to ensure a certificate is present for secure connections. When it detects a discrepancy or perceives an issue with the existing certificate, it falls back to the default self-signed certificate. This is a security measure, but it can be a real headache for those of us who prefer using trusted certificates from authorities like Let's Encrypt.

Why UniFi Reverts to the Default Certificate

Several factors can cause UniFi to revert to the default certificate. These include:

  • Certificate Validation Failures: If the UniFi OS cannot validate the custom certificate, perhaps due to an incorrect chain of trust or other validation errors, it will revert to the default.
  • Service Restarts: Sometimes, the simple act of restarting the UniFi OS services can trigger the certificate replacement, especially if the system is not correctly configured to persist the custom certificate across restarts.
  • Automated Renewals: If the certificate renewal process isn't set up correctly, the UniFi OS might not recognize the renewed certificate, causing it to default back to the self-signed one.

The Importance of Valid SSL Certificates

Before we delve into the solutions, let’s quickly touch on why using valid SSL certificates is crucial. SSL certificates, especially those from trusted Certificate Authorities (CAs) like Let's Encrypt, provide several key benefits:

  • Enhanced Security: They encrypt data transmitted between the client (your browser) and the server, protecting sensitive information from eavesdropping.
  • Trust and Credibility: Browsers display a padlock icon for sites with valid SSL certificates, assuring visitors that the connection is secure. Self-signed certificates, on the other hand, often trigger warnings, which can deter users.
  • SEO Benefits: Search engines like Google favor websites with HTTPS, potentially boosting your site's ranking.

Solutions and Workarounds

Now, let’s get to the good stuff: how to stop uosserver start from overwriting your precious certificates. MiranoVerhoef's initial workaround is a clever one, but let's explore it in more detail and add a few more options to your arsenal.

1. File Permissions and Ownership (MiranoVerhoef's Workaround)

MiranoVerhoef's solution involves changing the ownership and permissions of the unifi-core.crt and unifi-core.key files. Here's a breakdown of how this works and why it's effective:

  • Changing Ownership: By setting the owner to root, you prevent the UniFi OS from directly modifying the files using its own user context.
  • Setting Permissions: Allowing group read access ensures that the UniFi OS can still read the certificate and key for secure connections but can't overwrite them.

Here’s how you can implement this workaround:

chown root:root /usr/lib/unifi/data/keystore/unifi-core.crt
chown root:root /usr/lib/unifi/data/keystore/unifi-core.key
chmod 440 /usr/lib/unifi/data/keystore/unifi-core.crt
chmod 440 /usr/lib/unifi/data/keystore/unifi-core.key

Explanation:

  • chown root:root: This command changes the owner and group of the files to root.
  • chmod 440: This command sets the permissions to read-only for both the owner (root) and the group, while denying any permissions to others.

This method is a quick and effective way to prevent the UniFi OS from overwriting the certificate files. However, it’s more of a workaround than a permanent solution. A more robust solution would involve configuring UniFi to properly manage and persist the custom certificate.

2. Configuring UniFi to Persist Custom Certificates

A more sustainable solution involves configuring UniFi to recognize and persist the custom certificate across restarts and service operations. This typically involves adjusting the UniFi configuration files.

Steps:

  1. Locate the UniFi Configuration File: The main configuration file is usually located at /usr/lib/unifi/data/system.properties.

  2. Edit the Configuration: Add or modify the following lines to point to your custom certificate and key files:

    unifi.ssl.enabled=true
unifi.ssl.keystore=/usr/lib/unifi/data/keystore
unifi.ssl.certfile=/usr/lib/unifi/data/keystore/unifi-core.crt
unifi.ssl.keyfile=/usr/lib/unifi/data/keystore/unifi-core.key

    Ensure these paths match the actual location of your certificate and key files.

  3. Restart UniFi Services: After making these changes, restart the UniFi services to apply the new configuration:

systemctl restart unifi


This approach explicitly tells UniFi where to find the custom certificate, ensuring it persists across service restarts.

### 3. **Automated Certificate Renewal with Post-Renewal Hooks**

If you're using Let's Encrypt, you likely have an automated renewal process in place. However, the UniFi OS might not automatically recognize the renewed certificate. To address this, you can use post-renewal hooks.

A post-renewal hook is a script that runs after the certificate is successfully renewed. This script can be used to copy the new certificate files to the UniFi keystore and restart the UniFi services.

**Example Post-Renewal Hook (using Certbot):**

```bash
#!/bin/bash
date=`date +%Y-%m-%d_%H.%M.%S`

# Paths
CERT_PATH="/etc/letsencrypt/live/yourdomain.com"
KEYSTORE_PATH="/usr/lib/unifi/data/keystore"

# Copy the new certificate and key
cp $CERT_PATH/fullchain.pem $KEYSTORE_PATH/unifi-core.crt
cp $CERT_PATH/privkey.pem $KEYSTORE_PATH/unifi-core.key

# Set correct owner and permissions
chown root:root $KEYSTORE_PATH/unifi-core.crt
chown root:root $KEYSTORE_PATH/unifi-core.key
chmod 440 $KEYSTORE_PATH/unifi-core.crt
chmod 440 $KEYSTORE_PATH/unifi-core.key

# Restart UniFi service
systemctl restart unifi

logger -t letsencrypt "UniFi certs renewed $date"

Explanation:

  • This script copies the fullchain.pem (certificate chain) and privkey.pem (private key) from the Let's Encrypt directory to the UniFi keystore.
  • It then sets the correct ownership and permissions, as discussed earlier.
  • Finally, it restarts the UniFi service to load the new certificate.

To configure Certbot to use this hook, you can add the --post-hook option to your renewal command:

certbot renew --post-hook "/path/to/your/hook-script.sh"

4. Using UniFi's GUI to Import Certificates

UniFi's web interface provides a way to upload custom certificates. While this method might seem straightforward, it sometimes fails to persist the certificate across updates or restarts. However, it's worth trying if the other methods seem too complex.

Steps:

  1. Access UniFi Controller: Log in to your UniFi controller's web interface.
  2. Navigate to Settings: Go to Settings > System Settings > Certificates.
  3. Upload Certificate: Click on Upload Certificate and upload your unifi-core.crt and unifi-core.key files.
  4. Apply Changes: Save the changes and restart the UniFi services.

Remember to monitor if the certificate persists after a restart. If not, you might need to resort to one of the other methods.

Troubleshooting Common Issues

Even with these solutions, you might encounter some hiccups. Here are a few common issues and how to troubleshoot them:

  • Certificate Chain Issues: Ensure your unifi-core.crt file contains the full certificate chain, including the intermediate certificates. You can usually obtain this from your Certificate Authority.
  • Incorrect File Paths: Double-check that the paths specified in the system.properties file and the post-renewal hook script are correct.
  • Permission Problems: Verify that the UniFi process has the necessary permissions to read the certificate and key files.
  • Configuration File Syntax Errors: Errors in the system.properties file can prevent UniFi from starting correctly. Ensure the syntax is correct.

Conclusion

Dealing with SSL certificates can be tricky, but with the right approach, you can ensure your UniFi setup uses trusted certificates and provides a secure experience. We've covered several methods to prevent uosserver start from overwriting your custom certificates, from simple file permission changes to more robust configuration adjustments and automated renewal hooks. By implementing these solutions, you can keep your UniFi network secure and avoid those annoying certificate warnings. If you guys have any more questions or run into other issues, don't hesitate to ask! Happy networking!