UniFi - system.properties File Explanation

Overview


Found under<unifi_base>/data (the "Data" folder inside the UniFi server installation directory, the system.properties file defines system-wide parameters for the UniFi Controller. Here are just a few notable examples of supported configuration changes for UniFi 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;
  • and most commonly, Port Assignments, for purposes of the UniFi Controller communicating with Managed Devices, redirecting Guest Portal traffic, etc.

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 (for example, uncheck/re-check uplink monitor).

info_i_25x25.png Note: The location <unifi_base> will vary depending on your operating system. See this article for more information.


Table of Contents


  1. Default Ports
  2. Manually Set IP Interface for Controller Communication
  3. Advanced Database Configurations
  4. User Notes & Tips

Default Ports


Back to Top

To change default ports for controller and UAPs (see 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 Set IP Interface for Controller Communication


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 Configurations


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=false

(v3.1.7+) The configuration below is used to fix an earlier bug where, in earlier v3 versions, the controller allows you to delete the super admin account (the one created during installation) and this super admin cannot be restored back. We later fix this issue (super admin cannot be deleted any more). However, some might have accidently already done this hence we created below config to allow promoting of a super admin. We expect most users will never need to set this.

  • super_admin.name=account_id_to_be_promoted

(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 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 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 

Currently you cannot have any character after the custom line(s) too, this includes spaces, pound signs/comments, etc.


User Notes & Tips


Back to Top

These notes have been added thanks to user collaboration. Have anything to contribute? Click on the Give Feedback button below!

  •  If you want to reduce the logging frequency on your RPi UniFi Controller, see this Community threadNote: without logs it is impossible to receive appropriate support. Use this tip under your own discretion.