UniFi - Explaining the system.properties File


This article describes what the system.properties file is used for and how to edit it.

NOTES & REQUIREMENTS:This article includes some advanced configurations that should only be performed by advanced users. Advanced configurations are not supported by our Support team. The Community is the best place to find experts to guide you with advanced configurations.

Table of Contents

  1. Introduction
  2. Default Ports
  3. Manually Specify the IP Interface for Controller Communication
  4. Advanced Database Configuration
  5. User Tips & Notes
  6. Related Articles


Back to Top

The system.properties file, found within <unifi.base> in the data folder, is the file inside the UniFi server installation directory, which defines system-wide parameters for the UniFi Network Controller. Here are just a few notable examples of supported configuration changes for UniFi Network Controller made in the system.properties file:

  • Manual override of the Controller IP Interface (the address to which Devices send inform packets).
  • Advanced Database adjustments.
  • Port Assignments, for purposes of the UniFi Network Controller communicating with Managed Devices, redirecting Guest Portal traffic, etc.
WARNING: Before editing the system.properties file, remember to create a backup of your controller and download it to a safe place. It is also necessary to stop the controller before performing any change in the file to avoid errors after changes are made.

The system.properties file can be edited directly via any text editor. Keep in mind that lines preceded by hash-tags (#) exist as comments and are non-operational. Make edits at the bottom of the file. After changing this file, you'll need to manually trigger provisioning on each site in order to make these effective. See UniFi - How to Trigger a Provision for more information.

NOTE:The system.properties file is created when the UniFi Network Controller runs successfully. If you cannot find the file within the <unifi_base>, create it by running the Controller software, or in the event of a port conflict, run the UniFi Discovery Utility. Either option will generate the system.properties file. Windows or Mac will have an icon for the UniFi Discovery Utility but Linux will not. Users on Linux will have to load it via CLI: java -jar /usr/lib/unifi/lib/ace.jar discover  

Default Ports

Back to Top

To change default ports for Controller and UAPs (see the linked article for detailed explanation). Otherwise, the default ports are listed below:

  • unifi.shutdown.port=8081   # for management purpose
  • unifi.http.port=8080           # device inform
  • unifi.https.port=8443         # controller UI / API
  • portal.http.port=8880        # portal redirect port for HTTP
  • portal.https.port=8843      # portal redirect port for HTTPs
  • unifi.db.port=27117          # local-bound port for DB server
  • unifi.stun.port=3478         # UDP port used for STUN

Manually Specify the IP Interface for Controller Communication

Back to Top

If a Controller machine has multiple IP interfaces, the following configuration can manually set the exact IP interface that adopted APs should communicate to the Controller:

  • system_ip=a.b.c.d           # the IP devices should be talking to for inform

Advanced Database Configuration

Back to Top

Below are advanced database configurations that most users will never need. Note: We do not perform tests on these configurations, they are enabled for the convenience of database experts. One possible usage scenario is where few people run their Controllers on a NAS, which has a smaller footprint than a normal server, hence there's a need to reduce the required resources.

  • unifi.db.nojournal=false    # disable mongodb journaling
  • unifi.db.extraargs            # extra mongod args

The configuration below is used to facilitate Controller installation. Again, most users will never need to set this. When the is_default is set to true, the Controller will start with factory default configuration. For normal, everyday users, an uninstallation and then fresh re-installation is recommended over this.

  • is_default=true

(v5.1.0+) As of v5.1.0, we added an auto backup function to the Controller UI. From the UI you can configure the backup frequency, amount of backups to store, time of backup, etc. At the time of writing this, you cannot change the storage location via the UI. We do have a variable in the system.properties if you wish to change the storage location. Currently, the default points to:

1. For Cloud Key: /data/autobackup (where SD card is mounted as /data by default)
2. For software installs: {data.dir}/backup/autobackup

  • autobackup.dir=/some/path

The UAP-AC-EDU is recommended to be managed from a local Controller. The current communication from the EDU mobile app relays from app to Controller to EDU. If the mobile device is remote to the EDU, then you just need to open the appropriate ports. If the Controller is remote to the EDUs, then you need to add the following line to system.properties.

  • stream.playback.url.type=inform

(5.5.15+/5.6.7+) We've added HSTS support to the controller. Do note that it is default disabled. This should only be enabled if you know what you're doing with it. This will only ever be a system.properties value so it can be easily disabled in case of issues. If you run into issues, you likely will need to clear your browser's cache after disabling this and restarting the service. To enable HSTS support add the following:

  • unifi.https.hsts=true
  • unifi.https.hsts.max_age=31536000
  • unifi.https.hsts.preload=false
  • unifi.https.hsts.subdomain=false 
NOTE: Currently no characters after the custom line(s) are allowed. This includes spaces, pound/sharp signs/comments, etc.

User Tips & Notes

Back to Top

  • If receiving error, it's possible there are hash tags (#) present in front of commands. Hash tags indicate comments, and will make commands not work until hash tag is removed.
  • If you want to reduce the logging frequency on your RPi UniFi Controller, see this Community thread
    ATTENTION:Without logs, it is impossible to receive appropriate support. Use this tip under your own discretion. See how to extract logs in our UniFi - How to View Log Files article.
  • If you cannot find the system.properties file, it might not have been created yet. This file is created once the UniFi app runs successfully. If you cannot run the app for some reason, running the UniFi Discovery Tool will also create it. However, if you need to change port numbers because of a port clash, it doesn't count as a successful launch and does not create the file, so you can't alter the port numbers to avoid the clash.

Related Articles

Back to Top

UniFi - Where is <unifi_base>?

UniFi - Changing Default Ports for Controller and UAPs

Was this article helpful?
19 out of 22 found this helpful
Can't find what you're looking for?
Visit our worldwide community of Ubiquiti experts for more answers
Visit the Ubiquiti Community