UISP - Suspension, Traffic Shaping and Aggregation


Readers will learn more about the UISP Suspension and Traffic Shaping features. These advanced networking features strongly focus on allowing ISPs to manage and influence the traffic of clients located in the network. 

NOTES & REQUIREMENTS:Applicable to the latest UISP release version. Traffic Shaping for ONU devices is supported starting from the v1.1.0 version. See the Global Features for Networks article for more information on the UISP advanced network features.


Adding a UISP-branded gateway device (ex. UISP Console, UISP Router) or EdgeRouter device as a UISP Gateway router allows you to easily configure advanced networking features such as Traffic Shaping, NetFlow, and Suspension.

  • Traffic Shaping Limits the upload and download speed of client devices to a specific value.
  • NetFlow Collects IP network traffic statistics. See the NetFlow article for more information.
  • Suspension Allows an administrator to (temporarily) suspend the network services of a client or customer.  See the Suspension article for more information.

NOTE: It is recommended to perform both Suspension and Traffic Shaping through the UISP Gateway router. Alternatively, it is possible to shape the traffic on Ubiquiti CPE devices as well.

The integrated CRM module is used to manage Suspension and Traffic Shaping according to ISP business plans and tariffs. The management is performed through a service created in CRM and paired with a client site. 

In order to manage traffic shaping, UISP gathers all IP addresses of all devices attached to a Client Site. Then it discards those IP addresses which are not in the defined internal network range (which can be configured in the  Settings > Network > Addresses section). All management IP addresses are discarded as well at this point. For all remaining IP addresses, a rule is created on the gateway with a specified data transfer speed limit. In the case of Gateway + CPE traffic shaping, those rules are pushed to a specific CPE device, which connects a Client Site to its parent Site.

NOTE: Shaping or Suspension rules are in effect regardless of what type/brand of device is downstream (on the side of your client). UISP monitors any IP changes on shaped or suspended devices and alters the rules on the gateway or CPE accordingly. Please note it can take several minutes to distribute the changed rules through the system. 

Configuring Traffic Shaping

There are many ways to perform Traffic Shaping on a network. UISP focuses on two of them:

Gateway Only All traffic shaping rules are configured on the main gateway. It is important to make sure all internet connections are going through that device in order to make the traffic shaping work correctly. UISP supports multiple gateways with the expectation that there won't be dozens of them. We recommend using a UISP-branded gateway device (ex. UISP Console, UISP Router) or EdgeRouter running the latest firmware as the UISP Gateway router.

Gateway + CPE It is not possible to configure the Traffic Shaping feature only on CPE devices, when a gateway is present in UISP, as that may lead to conflicts with gateway settings. The gateway has to be aware that traffic shaping is enabled. It is important to mention that each traffic shaping method has its own pros and cons. Traffic shaping in UISP is done on WAN (egress) and LAN (egress). Supported CPE devices for this version are airMAX AC, airMAX M, and airFiber in both router and bridge modes. 

Follow the steps below to enable the Traffic Shaping feature from UISP:

GUI: Access the UISP application (web).

1. Navigate to the Settings > Network section.

2. Edit the existing UISP Gateway router or add a new gateway.

3. Enable the Traffic Shaping feature by changing the Allow Traffic Shaping slider to ON.

4.  Define the max upload/download gateway WAN capacity. If this is not specified, the maximal physical capacity of the WAN interface is assumed.

5. The specific limits are configured per the Service Plan in the CRM module. Navigate to the CRM > System > Service plans & Products section to add or modify a service plan.

6. Navigate to the CRM > Clients > Select client > Select service plan to associate a client with a service plan.

7. It is possible to set up limits for both download and upload, as well as aggregation. See the section below for more information on the CRM Service Plan Aggregation option.

CRM: Service Plan Aggregation

NOTE: Aggregation is set automatically starting from the release of 1.2.0. UISP will attempt to find the correct aggregation for the optimal line utilization as well as the gateway performance. It is still possible to manually configure the aggregation value if needed.

Aggregation defines the minimal guaranteed throughput for each client at any given moment. For example, if there is a tariff with a 125 Mbps limit and the aggregation is set to 5, then each client will have 25 Mbps (125 / 5) of guaranteed throughput. For aggregation to work correctly, the sum of all guaranteed speeds for all users has to be lower than the total available throughput on the UISP Gateway router.

The example below uses two tariffs:

  • Standard 100/10 Mbps Download/Upload with the aggregation of 80.
  • Premium 100/10 Mbps Download/Upload with the aggregation of 7.

In this example, there are 200 clients that use the Standard tariff and 5 clients that use Premium. The total throughput this ISP bought and which is available for sharing through the WAN interface is 800Mbps.

As a first step, it is necessary to check if the intended setup is correct by calculating the values:

  • Standard offers 1.25Mbps guaranteed speed (100/80) and there are 200 clients. This equals to 200 * 1.25 = 250Mbps for all clients.
  • Premium offers 14.28Mbps guaranteed speed (100/7) and there are 5 clients. This equals to 5 * 14.28 = 71.4Mbps for all clients.
  • Combined there is 321.4Mbps used on a WAN interface that supports up to 800Mbps, so this setup is valid.
  • If the amount of Premium users was the same as Standard, the total required throughput would be (200 * 1.25) + (200 * 14.28) = 250 + 2856 = 3106Mbps = 3.1Gpbs. This setup is not valid and the gateway will display the overloaded warning.

For the customers, the aggregation settings mean that:

  • Each customer with the Standard service will have at least 1.25Mbps download and 125Kbps upload guaranteed even if everybody is fully utilizing their links. If the overall utilization is low, it is possible to download as much as 100Mbps with this tariff.
  • Each customer with the Premium service will have at least 14.28Mbps download and 1.42Mbps upload guaranteed even if everybody is fully utilizing their links. If the overall utilization is low, it is possible to download as much as 100Mbps with this tariff.

It would be rather difficult to recalculate the aggregation each time the user count changes. Therefore the aggregation is calculated automatically on the v1.2.0+ version. UISP will automatically calculate the optimal aggregation values that provide maximal throughput for clients while not overloading the router. When the number of clients changes or when other aggregations are manually reconfigured, UISP immediately recalculates the optimal aggregation values and pushes it to the UISP Gateway router.

Follow the steps below to configure aggregation manually for a Service plan:

GUI: Access the UISP application (web).

1. Navigate to the CRM > System > Service plans & Products section to add or modify a service plan.

2. Expand the Set traffic shaping details option and specify the aggregation value.

NOTE: A blank value set in the service plan Aggregation field means that the aggregation is automatically calculated.

Configuring Suspension

The UISP Suspension feature allows an administrator to (temporarily) suspend the network services of a client or customer. This feature identifies clients by their IP address and prevents them from accessing the internet or other networks, with the exception of some previously defined network services.

The feature relies on the UISP Gateway role that is assigned to an EdgeRouter device. It is recommended to use the latest UISP version and the EdgeRouter v2.0.x EdgeOS firmware when using Suspension. Another requirement for Suspension is that customer internet connectivity flows through that specific gateway. Since there can be more than one gateway defined in UISP it is vital to make sure this is correctly set up.

NOTE: The suspended Client Site and devices attached to it will not disconnect from UISP and it will be possible to manage them remotely despite the suspension.

Admins may set up other IP addresses, which customers are allowed to visit despite being in the suspended state. This is useful to redirect customers to a specific website that offers payment services or a portal that they can use to communicate with the ISP. When a suspended customer tries to visit any page outside of the mentioned whitelist, the traffic is redirected to a suspension page with information about the suspension and an option to temporarily cancel it in order to allow payment. A suspended client can also still reach UISP since this default exception is created automatically.

Follow the steps from the dedicated Suspension article for more information on configuring the UISP Suspension feature on a UISP-branded Gateway device (ex. UISP Console, UISP Router) or EdgeRouter that is assigned the UISP Gateway role.

NOTE: When suspended users visit an HTTP page they are redirected to the suspension page. In some cases, this doesn't work for HTTPS pages due to the security settings.

Related Articles

UISP - Global Features for Networks

UISP - NetFlow

EdgeRouter - Suspension

Was this article helpful?
115 out of 151 found this helpful