Changing the UniFi Controller Port: A Step-by-Step Guide

Looks like you've got your UniFi setup up and running, but now you need to change the port that your UniFi Controller uses. Whether you're doing this for security reasons, to resolve a port conflict, or simply because you want to, the process is straightforward.

Let’s dive into how you can get this done with a few simple steps.

Table of Contents

• Why Change the UniFi Controller Port?
• Common Ports Used by UniFi Controller
  • Step 1: Backup Your UniFi Controller
  • Step 2: Locate and Edit the System Properties File
  • Step 3: Restart the UniFi Controller
  • Step 4: Update Firewall Rules (If Necessary)
  • Step 5: Test the New Configuration
  • Step 6: Document Your Changes
• What to Do If Things Go Wrong
• Additional Tips for Advanced Users
• Final Thoughts

Why Change the UniFi Controller Port?

Before we jump into the steps, it’s worth understanding why you might want to change the port in the first place:

1. Security: Changing default ports can help reduce the risk of attacks by making it harder for malicious users to guess which port you're using.

2. Port Conflicts: If another application on your network is using the same port as the UniFi Controller, changing the port can resolve conflicts.

3. Customization: Some users just prefer having control over every aspect of their network setup, including which ports are used for which services.

Whatever your reason, changing the port is something you can easily manage.

Common Ports Used by UniFi Controller

Before we get into changing ports, it's good to know which ports UniFi Controllers typically use by default:

• TCP 8080: Used for device management traffic.

• TCP 8443: The default port for accessing the UniFi Controller’s web interface via HTTPS.

• TCP 27117: The local MongoDB database port.

• UDP 3478: Used for STUN (Session Traversal Utilities for NAT).

Understanding these will help you identify what you might want to change and why.

Step 1: Backup Your UniFi Controller

Before making any changes, it's always a good idea to backup your UniFi Controller settings. This ensures that you can easily revert to a previous state if something goes wrong.

1. Access Your UniFi Controller:

   • Log into your UniFi Controller via the web interface.
   • Navigate to Settings > Maintenance.
   • Under Backup, click Download Backup.
   This will download a backup file of your settings. Store this file somewhere safe (and remember where you put it!).

2. Consider Automated Backups:

   • If you’re making regular changes or managing multiple networks, consider setting up automated backups. This can save you a ton of headaches down the road.

   You can set up automatic backups under the same Maintenance tab. Schedule it daily, weekly, or whatever fits your needs.

Step 2: Locate and Edit the System Properties File

The port settings for your UniFi Controller are stored in a system file called "system.properties". You’ll need to edit this file to change the port number.

1. Locate the File:

   • The "system.properties" file is typically found in the following directory, depending on your operating system:
     • Windows: "C:\Users<Your-Username>\Ubiquiti UniFi\data\system.properties"
     • macOS/Linux: "/usr/lib/unifi/data/system.properties"
   If the file doesn’t exist, don’t worry—you can create it yourself. Just make sure it's placed in the correct directory.

2. Edit the File:

   • Open the "system.properties" file with a text editor.
   • Add or modify the following lines to set your desired port numbers:

     unifi.http.port=8080
     unifi.https.port=8443
     unifi.db.port=27117
     unifi.stun.port=3478
     

     Change the numbers to whatever ports you want to use. For example, if you want to use port 8081 for HTTP, you’d change the line to:

     unifi.http.port=8081
     

3. Save the File:

   • Once you’ve made your changes, save and close the file.

4. Pro Tip: Keep a Copy of the Original File

   • Before making any changes, it’s a good idea to keep a copy of the original "system.properties" file. Just in case something goes wrong, you can easily restore the original settings.

Step 3: Restart the UniFi Controller

For the changes to take effect, you need to restart your UniFi Controller.

1. Restart the Controller Service:

   • On Windows, you can do this from the Services Manager.
   • On macOS/Linux, use the terminal:

     sudo service unifi restart
     

   The service should restart within a few seconds. If it doesn’t, or if you encounter errors, double-check that the "system.properties" file is correctly configured and that no other processes are using the new ports.

2. Check if Changes Were Applied:

   • Open your web browser and try to access the UniFi Controller using the new port, like this:

     http://<Your-IP-Address>:<New-Port-Number>
     

     For example:

     http://192.168.1.1:8081
     

3. Troubleshooting:

   • If you cannot access the controller on the new port, ensure that:
     • The port isn’t being blocked by your firewall or router.
     • There isn’t another service already using the port.
     • You saved the changes correctly in the "system.properties" file.

Step 4: Update Firewall Rules (If Necessary)

If you’re using a firewall, make sure that it’s configured to allow traffic on the new ports you’ve set. Forgetting this step could lead to blocked access to your controller, which is a real pain, especially if you’re managing a remote site.

1. Windows Firewall:

   • Open the Windows Defender Firewall with Advanced Security.
   • Add new inbound and outbound rules for the new port numbers you’ve configured.
   • Make sure both TCP and UDP traffic is allowed on these ports.

2. Linux IPTables:

   • You can add a rule like this:

     sudo iptables -A INPUT -p tcp --dport <New-Port-Number> -j ACCEPT
     

   • Make sure to save the IPTables rules to ensure they persist after a reboot:

     sudo sh -c "iptables-save > /etc/iptables.rules"
     

3. Router Settings:

   • Log into your router’s interface and update any port forwarding rules to reflect the new port numbers.
   • If you’re using a UniFi Security Gateway (USG), you’ll also need to update the port forwarding rules through the UniFi Controller.

4. Testing Firewall Rules:

   • After updating the firewall, test the connection from a different device on your network. You should be able to access the UniFi Controller on the new port without any issues.

Step 5: Test the New Configuration

Finally, test everything to make sure it’s working as expected. This is the most crucial step—if something isn’t working right, you want to catch it now, not when you’re in the middle of a network emergency.

1. Access the UniFi Controller: Use your web browser to access the controller using the new ports.

   • Try accessing it from different devices and locations to ensure there are no connectivity issues.

2. Test Device Connectivity: Ensure that all devices managed by the controller can still connect and are being managed properly.

   • If you have remote sites, test connectivity from those locations as well.

3. Check Logs: Look at the UniFi Controller logs to ensure there are no errors related to the port change.

   • You can find the logs in the "logs" directory within your UniFi installation folder.
   • Common log files to check:
     • "server.log": General server logs.
     • "mongod.log": Logs for the MongoDB service.

4. Monitor the Network: After making these changes, keep an eye on your network for the next few days.

   • Ensure there are no connectivity issues or unexpected behavior.
   • If you notice anything odd, it might be related to the port change, so investigate promptly.

Step 6: Document Your Changes

If you’re like most IT folks, you know that documentation isn’t exactly the most thrilling part of the job. But trust me, it’s a lifesaver when something goes wrong or when you hand off the network to someone else.

1. Document the New Ports:

   • Note down the new port numbers you’ve configured along with the date of the change.
   • Include this in your network documentation or handover notes.

2. Update Any Relevant Configurations:

   • If you’re using monitoring tools or scripts that interact with the UniFi Controller, make sure these are updated to use the new port numbers.

3. Inform Team Members:

   • If other team members or stakeholders need to know about the port change, make sure they’re informed.
   • Provide them with updated instructions for accessing the UniFi Controller.

What to Do If Things Go Wrong

Sometimes things don’t go as planned. If you find that you can’t access your UniFi Controller after changing the port, here’s what you can do:

1. Revert to Backup:

   • Restore your UniFi Controller settings using the backup file you created earlier.
   • You can restore from the backup by going to Settings > Maintenance > Restore Backup.

2. Check Firewall Rules:

   • Double-check that your firewall rules allow traffic on the new port.
   • Make sure there are no conflicting rules that might be blocking access.

3. Consult Logs:

   • The UniFi Controller logs can provide insight into any issues that might be preventing the controller from running on the new port.
   • Look for any error messages related to port binding or connectivity issues.

4. Port Conflict Resolution:

   • If another service is using the port you’ve chosen, either change the port again or stop the conflicting service.
   • Use a tool like "netstat" or lsof on Linux/macOS to check which services are using which ports.

5. Seek Help from the Community:

   • The UniFi community forums are a great place to ask for help if you run into issues. Chances are, someone else has encountered the same problem and can offer advice.

Additional Tips for Advanced Users

If you’re comfortable with more advanced network configurations, there are a few more things you can do to optimize your UniFi Controller setup:

1. Using Reverse Proxies:

   • Consider setting up a reverse proxy to manage incoming traffic to your UniFi Controller. Tools like Nginx or HAProxy can help you manage multiple services on the same server without changing ports.
   • A reverse proxy can also add an extra layer of security by hiding the true port number from the outside world.

2. Custom SSL Certificates:

   • If you’re changing the HTTPS port (8443), it might be a good time to set up a custom SSL certificate to enhance security.
   • This is especially useful if you’re accessing your UniFi Controller from outside your local network.

3. Load Balancing:

   • If you’re managing a large number of devices, you might want to consider load balancing your UniFi Controller across multiple servers.
   • This can help distribute the load and ensure that your controller remains responsive, even under heavy traffic.

Final Thoughts

Changing the UniFi Controller port isn’t something you’ll do every day, but when the need arises, it’s a straightforward process. Just make sure you back up your settings, edit the "system.properties" file carefully, and don’t forget to update your firewall rules. With everything in place, you can enjoy a more secure and customized network setup.

At UniHosted, we make it easy to manage your UniFi Controllers, whether you’re changing ports or scaling up your network. Our cloud-hosted solutions take care of the technical details so you can focus on what really matters—keeping your network running smoothly.