Month: January 2022

This article describes how to perform advanced configurations on the UniFi Security Gateway (USG and USG-PRO-4) using the config.gateway.json file. This article is not applicable to the UniFi Dream Machine models. The UDM line does not support configurations done outside of the UniFi Network application.NOTES & REQUIREMENTS:

• Ubiquiti Support cannot assist in the creation of the config.gateway.json file nor will assistance be provided for command line configuration. If assistance is required, feel free to visit our Community to create a topic and ask for help with your desired configuration.
• This article covers advanced configuration, and should only be used by advanced users.

Table of Contents

1. Introduction
2. Creating the config.gateway.json File
3. Editing the config.gateway.json File
4. Testing & Verification
5. Related Articles

Introduction

The config.gateway.json is a file that sits in the UniFi Network application filesystem and allows custom changes to the USG that aren’t available in the web GUI. Some possible customizations will be: configuring site-to-site VPNs with hostnames, policy routing certain traffic out WAN2, or even adding multiple IP addresses on an interface. These features don’t exist in the UniFi Network application yet, so the config.gateway.json file will supplement those features until they’re available in the GUI.

When making customizations via the config.gateway.json file, it is best to enter only the customizations that can’t be performed via the Network application. If the formatting is incorrect, a provisioning loop will be triggered on the USG, and a reboot will take place once the USG comes out of the provisioning loop. At this point the config.gateway.json file could be corrected or removed to correct this.WARNING:Some users may find they can get away with using the full config, but this is not recommended as it will most likely cause issues down the road. A provisioning loop might take place when a setting is changed in the Network application that conflicts with a setting in the config.gateway.json file.

Creating the config.gateway.json File

By default, the config.gateway.json file doesn’t exist, it has to be created in order to use it. 

1. Create a new file using a text editor such as TextEdit or Notepad++.

2. The structure of a json file is just as important as the words themselves. Incorrect placement of brackets, indentations, line breaks or any other structural element will make the json file invalid. It is recommended to run the text through a json validator in order to verify it has the correct syntax. The JSON Formatter website is one example of the many options of json validators you’ll find online.

3. Once the contents of the file has been validated, save it by naming it config.gateway.json and placing it under the <unifi_base>/data/sites/site_ID directory stored on the Network application. User Tip:Depending on your operating system, placing the file under this directory might be as simple as drag and drop, or using a FTP server might be necessary. The config.gateway.json file must have unifi:unifi as the owner and group permissions. You can check to verify with ls -l <unifi_base>/data/sites/site_ID. To change it, once you’re in the site directory, use the command: chown unifi:unifi config.gateway.json

The location <unifi_base> will vary from one operating system to another. See this article for more information. The site_ID can be seen in the URL of your browser when on the Network application. The original site is named “default”, and every site that is created will be assigned a random string. For example, this is what would be seen in the URL bar when inside the dashboard page of a site:

In the above case, the random string ceb1m27d is the folder name that shall be used under <unifi_base>/data/sites/. Therefore, the config.gateway.json should be placed inside <unifi_base>/data/sites/ceb1m27d/.User Tips:

• On Cloud Key install the path for the .json file is: /srv/unifi/data/sites/[site name/default]/
• On an Ubuntu install the path for the .json file is: /usr/lib/unifi/data/sites/[site name/default]/

Editing the config.gateway.json File

Before customizing firewall or NAT rules, take note of the rule numbers used in the UniFi Network application under Settings > Routing & Firewall > Firewall. Default firewall rules start at either 3001 or 6001, and NAT rules will also start at 6001 (which don’t overlap with firewall rules). The custom rules created in the config.gateway.json cannot have duplicate rule numbers with the existing rules in the USG, or there will be a provisioning loop. It is recommended to put custom rules before the existing ruleset, as the lower number will win between two matching rules.NOTE: When editing thiscustom json file, it is not necessary to include everything. You must only include the complete “path” to the items you have edited, anything outside of the path can be omitted. Think of each node in the json file as a folder that is nested within other folders (except for the level 1 folder which is our main section). The folder path that takes you from level 1 all the way down to the item you will be configuring must be present in the json file. See this example where we want to edit “close”, which has the following path: system > conntrack > timeout > tcp > close.  

Notice that in level 3 “modules” is also present along with “timeout”, but we will not include it in the json file because it is not part of the path to “close”. Same with the other items in level 5 under “tcp”. They do not need to appear in the config.gateway.json file because they are not part of the path. A successful change then, in the configuration of “close” from 10 to 20 would look like this:

The following is an example of how a DNAT rule is created for DNS configured using EdgeOS formatting:

1. Connect to the USG via SSH, and issue the following commands:

configure
set service nat rule 1 type destination
set service nat rule 1 inbound-interface eth0
set service nat rule 1 protocol tcp_udp
set service nat rule 1 destination port 53
set service nat rule 1 inside-address address 10.0.0.1
set service nat rule 1 inside-address port 53
commit;save;exit

2. Next is displaying the config. The following command displays the entire config in a JSON format:

mca-ctrl -t dump-cfg

 The config can also be exported if preferred. The following example exports the output to the config.txt:

mca-ctrl -t dump-cfg > config.txt

3. Find the appropriate section with the custom changes in the config output, for our example above it would be the following:

                "nat": {
                        "rule": {
                                "1": {
                                        "destination": {
                                                "port": "53"
                                        },
                                        "inbound-interface": "eth0",
                                        "inside-address": {
                                                "address": "10.0.0.1",
                                                "port": "53"
                                        },
                                        "protocol": "tcp_udp",
                                        "type": "destination"
                                },

4. Above is the custom rule, but it’s missing all the closing brackets (}) at the end to make it correct. If you look at the config output from the start, there is a certain format that is required for the file to be read correctly. Each node in a section must be separated by a comma (,), and it section must begin with an opening bracket ({) and finish with a closing one (}). Follow the existing format carefully. If the above rule is the only change in the config.gateway.json, you would edit it to look like so:

{
       "service": {
                "nat": {
                        "rule": {
                               "1": {
                                       "destination": {
                                               "port": "53"
                                       },
                                       "inbound-interface": "eth0",
                                       "inside-address": {
                                               "address": "10.0.0.1",
                                               "port": "53"
                                       },
                                       "protocol": "tcp_udp",
                                       "type": "destination"
                               }
                       }
               }
       }
}

5. If there are multiple sections to add, say Firewall, Service, VPN, the closing bracket for that section would be followed by a comma (},), before starting the next section. You can see these formatting details in the example below.

The DNAT rule # ranges are from 1-4999, and the Source/Masquerade rule numbers are from 5000-9999. If you wanted to add a port forward (DNAT) in the config.gateway.json for WAN2 in a multiWAN (load-balance) setup, this is what the config.gateway.json would look like with only this particular NAT rule:

{
	"service": {
		"nat": {
			"rule": {
				"4500": {
					"description": "port_forward_WAN2",
					"destination": {
						"address": "100.64.100.100",
						"port": "22"
					},
					"inbound-interface": "eth3",
					"inside-address": {
						"address": "192.168.1.100"
					},
					"protocol": "tcp",
					"type": "destination"
				}
			}
		}
	}
}

And if we were to add a VPN with hostnames to the file, the config.gateway.json would look like the one below. Notice the opening and closing brackets, as well as the bracket with comma before starting with the "vpn" section:

{
	"service": {
		"nat": {
			"rule": {
				"4500": {
					"description": "port_forward_WAN2",
					"destination": {
						"address": "100.64.100.100",
						"port": "22"
					},
					"inbound-interface": "eth3",
					"inside-address": {
						"address": "192.168.1.100"
					},
					"protocol": "tcp",
					"type": "destination"
				}
			}
		}
	},
	"vpn": {
		"ipsec": {
			"site-to-site": {
				"peer": {
					"yyyy.ignorelist.com": {
						"authentication": {
							"id": "xxxx.ignorelist.com"
						},
						"local-address": "xxxx.ignorelist.com"
					}
				}
			}
		}
	}
}

Testing & Verification

It’s recommended to validate the code once finished creating the config.gateway.json. There are a number of free options out there, jsonlint.com is used by the Ubiquiti support team quite often.

After adding the config.gateway.json to the UniFi Network site of your choosing, you can test it by running a “force provision” to the USG in UniFi Devices > select the USG > Config > Manage Device > Force provision. This will take a while to provision (30 seconds to 3 minutes), and if it stays in provisioning longer than that, there may be a formatting error in the config.gateway.json, and you are experiencing the provisioning loop that was mentioned earlier. You can check server.log in the application and search for commit error. You can usually find what went wrong with the provisioning of the newly customized configuration in the log files. Find information about that here.User Tip:An easy way to test the validity of the json file is: python -m json.tool config.gateway.json

Deleting Changes or Reverting to Previous State

To remove a certain advanced configuration, just delete the section pertinent to that configuration in the config.gateway.json file. To completely remove all advanced configurations created in the config.gateway.json file, delete the file or rename it. This will void all manual changes. The USG will be provisioned with the current config contained within the UniFi Network application.

A best practice when editing an already working config.gateway.json file is to create a backup. If you need to add additional changes to the config.gateway.json file, rename the current file to config.gateway.json.old, essentially creating a backup, and copy all the existing and new changes into a new file named config.gateway.json. This way, if there happens to be any mistakes resulting in a “commit” error or provisioning loop, you can delete config.gateway.json, and try again starting from config.gateway.json.old.

Source :
https://help.ui.com/hc/en-us/articles/215458888-UniFi-USG-Advanced-Configuration-Using-config-gateway-json

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

Introduction

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 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 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 :
  https://help.ui.com/hc/en-us/articles/205202580-UniFi-Explaining-the-system-properties-File

This article shows what UDP and TCP ports are used by the UniFi Network application by default. The information applies to both Network applications hosted on UniFi OS Consoles, such as UniFi Cloud Key (UCK-G2, UCK-G2-PLUS, and UC-CK) or UniFi Dream Machine (UDM or UDM-Pro), as well as self-hosted Network applications. 

Note: Make sure to always update your Network application to the latest version.

• Local Ingress Ports
• Ingress Ports required for L3 management over the internet
• Egress Ports required for UniFi Remote Access
• Changing Default Ports

Local Ingress Ports

Note: Although TCP 22 is not one of the ports UniFi Network operates on by default, it is worth mentioning in this article since it is the port used when UniFi devices or the Network application is accessed via SSH.

Ingress Ports required for L3 management over the internet

Note: These ports need to be open at the gateway/firewall as well as on the UniFi Network application host. This would be achieved by creating port forwards on the gateway/firewall where the application is hosted.

Egress Ports required for UniFi Remote Access

Note: In most cases, these ports will be open and unrestricted by default.

Changing Default Ports

Changing default port assignments can only be done on self-hosted Network applications (Windows/macOS/Linux). This can be accomplished as follows:

1. Close any instances of the UniFi Network application.

2. Modify the system.properties file, which can be found in the directory <unifi_base>/data/system.properties.

• For example, if port 8081 was in use and port 8089 was open, you could change it by modifying unifi.shutdown.port=8081 to unifi.shutdown.port=8089

3. Restart the UniFi Network application.

Note: Make sure there are no leading or trailing spaces, comments, or other characters like hash tags (#) on any custom lines. Otherwise, UniFi Network will ignore the customizations.

Source :
https://help.ui.com/hc/en-us/articles/218506997-UniFi-Ports-Used

This article describes the different statuses a UniFi Access Point might be ascribed by the UniFi Network application within the UniFi Devices section.

Source :
https://help.ui.com/hc/en-us/articles/205231710-UniFi-UAP-Status-Meaning-Definitions