This article only applies to advanced users running a UniFi Network Server on their own Windows/macOS/Linux machine, to help diagnose and optimize self-hosted UniFi Network Servers running under a high load. We generally recommend adding a UniFi Console for the easiest and most scalable experience.
The following settings are contained in the system.properties file of your UniFi Network application, found in the \Ubiquiti UniFi\data folder of the installation. If a setting is not already present in the file, it can be added as a new line.
Notes & Requirements:
- Ensure you are running the latest version of UniFi Network, found here.
- This article describes advanced configuration options and should only be attempted by advanced users.
- Create a backup prior to following the instructions in this article. See UniFi - Backups and Migration for more information.
Caution must be taken when self-hosting a UniFi Network Server if there are hundreds of UniFi devices connected across multiple sites. This increased system load may lead to performance degradation if certain things are not optimized.
Symptom: High CPU Usage
One of the most important metrics to monitor is the CPU usage of the UniFi Network Server. High CPU usage is the first indication that there is an issue. Unfortunately there is no easy solve for this, and merely increasing the CPU is not always the answer.
Allocating Additional Memory
Before increasing the RAM allocation on your machine, first try increasing the `XMX` and `XMS` options. By default, the UniFi Network application has these set to 1GB. The following lines set the xmx and xms to values to 2GB (2048MB):
The changes above would increase the memory that the UniFi Network application is allowed to consume from 1 to 2GB. Before moving to a machine with more CPU resources, it is recommended to max out the available memory on that machine with the above settings to see if CPU usage decreases.
If 2GB is not sufficient, administrators may want to raise the limit to 4, 8, 16, or even 32GB depending on the scale. In this case it would simply be increasing the value above in increments of 1024, i.e. 4 GB= 4096.
Note: The jstat -gcutil Java command can be used to check whether the memory allocation is sufficient on your machine. See the Oracle documentation for more information.
Increase Mongo WiredTiger Engine Cache
If you already increased the UniFi Network application memory settings to at least 4GB (xmx), you may need to also change the default Mongo WiredTiger engine cache. By default the UniFi Network Application uses:
On UniFi Network version 6.5.13 and above you can change this setting or let Mongo pick the default value by using:
For more information please refer to Mongo documentation.
Enabling High Performance Java Garbage Collector
If increasing memory does not solve the problem, administrators may consider also adding this line to the system.properties file:
This enables a new Java Garbage Collector that can help optimize performance. However, if after these changes high CPU usage does continue after memory increase, a larger machine with more CPU cores and more memory to handle the workload may be necessary.
Changing Mongo Version/Engine
In persistent cases, administrators may consider updating MongoDB to a higher version, as a means of better scaling their UniFi Network deployment. For the UniFi Network application, the minimum MongoDB version is 3.6, and the maximum MongoDB version is 4.4.
Please note that your MongoDB upgrade may require doing it in steps, depending on the starting version and new target version. Refer to the Mongo upgrade manual for more information:
Symptom: Heartbeat Missed or Slow to Provision
All devices work by communicating to UniFi Network. These regular inform messages are referred to as 'heartbeats.' By default, the application can handle 200 simultaneous device connections so heartbeats shouldn't be missed unless thousands of devices are being managed. The number of simultaneous inform messages that can be processed can be set in the system.properties file by adding the following lines and adjusting the values to best suit your needs. It does not matter where these lines are added in the file.
The default value is 200 and the max_keep_alive_requests value should always be lower than than num_thread. Try adjusting up from there. An increase in device stability should be seen, and by pushing the configuration out to other devices, become even more stable.
Database Connection Tuning
When running a large UniFi installation, it may be desired to run an external Mongo cluster to be able to scale the database independently from the UniFi Network application. Discussion on that can be found here on our Community Beta forum. If high CPU usage is seen on the Mongo process, it can indicate the need of a bigger box or the need to separate the mongodb process as mentioned above. Once that is done, the following can be tuned to see if it results in better application performance: