UniFi - Explaining the config.properties File


Overview


This article gives a brief explanation of the config.properties file, where it should be created and some sample configuration nodes. By editing the config.properties file, users can add configurations that are not available in the UniFi Controller at the moment. 

ATTENTION: The nodes described in this document are advanced configurations and should only be attempted by advanced users. Our Support team will not be able to give assistance to these configurations, so please remove them from your environment prior to contacting support. 

Table of Contents


  1. Creating the config.properties File
  2. Configuration Nodes
  3. Related Articles

Creating the config.properties File


Back to Top

By default, the config.properties file does not exist. A user must create it in order to use it. Since the config.properties file is used to define site-wide parameters for the UniFi Controller, it must be placed under each <unifi_base>/data/sites/the_site directory. Use a text editor to create this file and name it "config.properties".

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

The UniFi Controller designates a random string to each site name. The easiest way to find this string is to open the Controller in a browser, and navigate to the corresponding site. In the browser address bar, you will see something similar to this when you are within the dashboard section:

https://127.0.0.1:8443/manage/s/ceb1m27d/dashboard

In the URL above, the random string ceb1m27d will be the folder name used under <unifi_base>/data/sites/. Therefore, for this example we would navigate to the folder named ceb1m27d within the sites parent folder and place the config.properties file within it. Finish off by triggering a provision to the UniFi device taking the configuration.


Configuration Nodes


Back to Top

Below you'll find a list of configuration nodes that are still relevant with their corresponding purpose:

User Tip: In any of the configuration nodes shown below, if you must use a UniFi Access Point (UAP) or UniFi Switch (USW) MAC ID, enter the number without any punctuation marks and make sure letters are all in lower case. For example, a MAC ID would look like this: 24a43c02d824

  Node

Purpose

config.selfrun_guest_mode=pass

or

config.selfrun_guest_mode=off

Configure whether to automatically authorize all guests when the controller is down. All guest isolation / policy is still enforced. 

config.captive_portal_subnets=0.0.0.0/1 128.0.0.0/1 

This configuration sets the subnets that should be allowed to access for portal pages. For example, to set Paypal express checkout. As paypal.com no longer uses static IP subnets, the current workaround is to enable all HTTPS traffic.

config.system_cfg.1=

or

config.system_cfg.UAP_USW_MAC.1= 

To customize UAP provisioning (see this article for detailed explanation). Choose between device-specific or site-wide customization with these two options.

e.g. config.system_cfg.1=ebtables.1.cmd=-t nat -A PREROUTING --in-interface eth2 -d BGA -j DROP

config.system_cfg.1=radio.1.txbf=3

 

(UAP-AC only) TxBF (transmit beamforming) is OFF by default. If enabling this feature is desired, we would suggest you update all clients drivers to the latest version first, and then add below config into config.properties file.

A value of 0 = tx off and rx off. 
A value of 1 = tx off and rx on. 
A value of 2 = tx on and rx off. 
A value of 3 = tx on and rx on.

radio.1 is for 5G interface named "eth2" in UAP-AC. Thus the radio.1.devname=eth2. radio.2 is for 2G interface named "eth1" in UAP-AC.

ATTENTION:
It is recommended to perform all configurations in the UniFi Controller GUI. The config.properties nodes listed in the expandable section below are now included in the Controller and should be configured from there. 
Click here to see Deprecated Configuration Nodes.
  • To change the default NTP server being used,
    config.ntp_server=0.ubnt.pool.ntp.org
  • To enable/disable uapsd (some clients may or may not work with uapsd enabled),
    config.uapsd_enabled=false 
  • To enable/disable IGMP snooping (for multicast enhancement, default is enabled)
    config.igmpsnoop_enabled.[ssid]=false
  • This is to facilitate portal redirect process, most users would never need to change this (note: this is deprecated since 3.2.10)
    config.redirect_via_host=www.ubnt.com
  • To set minimum RSSI feature related parameters (see this article for detailed explanation),
    config.minrssi.UAP_MAC.[ng|na]=[Minimum RSSI value].
    e.g. config.minrssi.24a43c02d824.ng=20
  • (v3.2.9+)  To change guest portal redirect behavior for HTTPS page
    config.redirect_https=true - guests will receive invalid cert error while doing https browsing
    config.redirect_https=false - This is the default behavior (3.2.10+ or 4.6.3+). Guests get timed out while trying https browsing

  • (v4.6.3+)  To change guest portal behavior
    config.redirect_to_https=true - Guests will be redirected to HTTPS guest portal (8843)
    config.redirect_to_https=false - This is the default behavior. Guests will be redirected to HTTP guest portal (8880)
  • For UAP-ACs before v3.1.10, TxBF is ON by default. To turned it off, ssh into the target AP and issue below commands. Note that, this change is NOT persistent and won't survive pass AP reboot.

     wl -i ethX down
     wl -i ethX txbf 0
     wl -i ethX txbf_bfr_cap 0
     wl -i ethX txbf_bfe_cap 0
     wl -i ethX up

     You can check if values are set into the AP by typing these,
     wl -i eth2 txbf
     wl -i eth2 txbf_bfr_cap
     wl -i eth2 txbf_bfe_cap

     Note: The default value is 1 (means enable) for all three.

  • To bind SSHD only on the management interface (v3.1.7+),

     On controller, to push this config to all APs within a site, add these into config.properties,
     config.system_cfg.1=sshd.1.status=enabled
     config.system_cfg.2=sshd.1.ifname=br0
     config.system_cfg.3=sshd.1.port=22

     The above will cause issues with USW SSH access, so if limiting AP SSHD to br0 add this for USW:
     config.system_cfg.USW_MAC.1=sshd.1.ifname=eth0

  • Configurable Management Frame Rate (v4.6.3+)

    # set mgmt rate for wlan with <ssid>
    config.mgmt_rate.wlan.MySsid=54
    or
    # set mgmt rate for device with <mac> and radio <na|ng>
    config.mgmt_rate.UAP_MAC.na=36
  • Configurable Broadcast and Multicast Rate (v4.6.3+)
    # set bcast/mcast rate for wlan with <ssid>
    config.mcast_rate.wlan.MySsid=54
    or
    # set bcast/mcast rate for device with <mac> and radio <na|ng>
    config.mcast_rate.24a43c02d824.na=36
  • (UAP-AC only) To disable broadcast and multicast filters. config.mcast_filter_enabled=false
NOTE: DHCP and ARP will be passed through (NOT filtered) by default. The filter only kicks in if there are too many broadcast/multicast traffic in the network (which affects performance). However, a more accurate solution to this kind problem is to refine subnet size.

 

USG Specific Nodes

  • (USG only) To disable response to ping on WAN:
    config.firewall.internet.local.icmp=false  (Note: This has been deprecated in 5.5.4 and newer controller versions. Ping on WAN is disabled by default, and can be permitted via WAN LOCAL firewall rules configured in the controller UI if desired.)
  • (USG only) To enable UPnP support: 
    config.igd.enabled=true
  • (USG only, 4.6.3+) To enable mDNS reflector:
    config.ugw.mdns.enabled=true
  • (USG only) To disable SIP ALG support: 
    config.ugw.voip.sip_alg_disable=true

Related Articles


Back to Top

UniFi - Where is <unifi_base>?

UniFi - How to Trigger a Provision

UniFi - How to Make Persistent Changes to UAP system.cfg