Ubiquiti 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. Manually Specify the IP Interface for UniFi Network Application Communication
  3. Advanced Database Configuration
  4. SMTP Related Settings
  5. User Tips & Notes


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 application. Here are just a few notable examples of supported configuration changes for UniFi Network application made in the system.properties file:

  • Manual override of the Application IP Interface (the address to which Devices send inform packets).
  • Advanced Database adjustments.
  • Port Assignments, for purposes of the UniFi Network application communicating with Managed Devices, redirecting Guest Portal traffic, etc.

WARNING:Before editing the system.properties file, remember to create a backup of your system and download it to a safe place. It is also necessary to stop the application 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.NOTE:The system.properties file is created when UniFi Network runs successfully. If you cannot find the file within the <unifi_base>, create it by running the UniFi Network application .

Manually Specify the IP Interface for UniFi Network Application Communication

If a UniFi OS Console (or device hosting the application) has multiple IP interfaces, the following configuration can manually set the exact IP interface that adopted APs should communicate to the Network application:

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

Advanced Database Configuration

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 application 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 UniFi Network application installation. Again, most users will never need to set this. When the is_default is set to true, the application will start with factory default configuration. For normal, everyday users, an uninstallation and then fresh re-installation is recommended over this.

  • is_default=true

From the UniFi Network application you can configure the autobackup frequency, amount of backups to store, time of backup, etc. At the time of writing this, you cannot change the storage location via the application. 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 application. The current communication from the EDU mobile app relays from app to Network application to EDU. If the mobile device is remote to the EDU, then you just need to open the appropriate ports. If the UniFi Network application 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 application. 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.

SMTP Related Settings

By default, SMTPS validates certificates and will reject self-signed or untrusted certificates. If your mail server uses an untrusted certificate, you must disable certificate verification with the following: smtp.checkserveridentity=false

Starting with UniFi Network version 6.1, STARTTLS is opportunistically enabled by default; e.g. will be used if the server announces support for it, and will require a trusted certificate. If using a self-signed or untrusted certificate, you must disable STARTTLS by setting the following: smtp.starttls_enabled=false

This only controls whether STARTTLS will be used if the server supports it. To force its use, see: starttls_required

With UniFi Network version 6.1 and newer, STARTTLS is opportunistically enabled by default, but only required if using port 587. This behavior can be overridden by setting smtp.starttls_required=true to force the use of STARTTLS on ports other than 587, or to make STARTTLS optional on port 587, set it to false.

If smtp.starttls_enabled=false is set, the starttls_required value has no impact.

User Tips & Notes

  • 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 Network application, see this Community threadATTENTION: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 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.

    Source :