Enabling Plan Enforcement (Shaping) or Changing Default Plan Speeds

How do I enable plan enforcement or change default plan speeds in Preseem?

This article describes how to enable plan enforcement in your Preseem device. The difficulty level for this task is intermediate. If you are not comfortable with Unix shell environments, feel free to contact Preseem for help and we will be happy to assist. You need to log in to the Preseem device via SSH or console to proceed. Changing the configuration file and restarting the service requires sudo / root access.

Overview

Preseem can optimize traffic at two levels: Subscriber and Access Point.

Subscriber (Plan Enforcement)

One of the most common causes of poor subscriber quality of experience (QoE) is the subscriber utilizing their full plan bandwidth. That is, the subscriber self congests their own "link". Examples of this include a large game or OS update which saturates the connection or video services such as Netflix negatively impacting the latency sensitive experience of gaming and VoIP applications. The reason that the customer experience degrades rapidly as the link approaches congestion is because most devices employ simple FIFO buffering schemes which add latency and eventually loss across all flows.

Preseem plan enforcement (shaping) is based on modern active queue management (AQM) techniques which keep latency and loss low even when the link is near its full capacity. This is accomplished by providing isolation between flows so one flow cannot negatively impact another flow and by more intelligently managing the packets that do need to be queued.

Access Point

Another very common source of poor QoE in fixed wireless networks is at the access point (AP). Just like other network devices, most APs employ simple buffering schemes which provide a bad subscriber experience when the link is near its capacity.

To maintain a good subscriber experience even when the AP is near its capacity, Preseem has AP shaping. This enables the operator to set a bandwidth limit just below the point when the AP becomes saturated and delivers a bad experience. This enables Preseem's AQM techniques to optimize the experience. This approach also has the benefit of more fairly sharing the AP's bandwidth between the subscribers on the AP.

For more information on Access Point shaping please see this article.

Principle of Operation

  • Subscriber level: Once Preseem is integrated with your billing system, it will periodically (by default every 5 minutes) retrieve all subscriber information to be aware of any change to plans and plan speeds.  The plan speeds are forwarded to the Preseem device to enforce that speed.  This allows the Preseem device to automatically adapt the plan enforcement / shaping to new values entered in your billing system.
  • Access Point (AP, or Sector) level: Typically, a service running in a Preseem device deployed in your network polls your APs dynamically (preseem-netmeta-agent and preseem-network-poller services).  This information is shared with the cloud and all other inline devices.  Preseem then aggregates all subscribers that are attached to a given AP, and applies upstream and downstream shaping rules to all of them as one. For instructions and guidelines on how to use AP shaping please see this article.

Check the System Status

Run this command at a shell terminal prompt:

preseemctl system show

The Running and Healthy columns should contain Yes for each service, except for the Bypass services that only initialize the system when it starts. It is normal for Telegraf to have N/A in the healthy column. Here is a typical good output:

[root@preseem ~]# preseemctl system show
SERVICE | START ON BOOT | RUNNING | HEALTHY | UPTIME
+--------------------+---------------+---------+---------+-----------------+
BypassBoot | Yes | N/A | N/A | N/A
BypassShutdown | Yes | N/A | N/A | N/A
HealthManager | Yes | Yes | Yes | 25d:14h:43m:31s
NetdevManager | Yes | Yes | Yes | 25d:14h:43m:25s
NodeManager | Yes | Yes | Yes | 25d:14h:43m:31s
Telegraf | Yes | Yes | N/A | 25d:14h:43m:31s
SystemStatsManager | Yes | Yes | Yes | 25d:14h:43m:31s

Set the Shaping Parameters

In the Preseem configuration text file (/etc/preseem/config.yaml), under each interface of interest, we have a qosTransmitPolicy ("policy") section defined. Inside that section, you can find these parameters:

  • name: when set to "count", no enforcement shaping is applied, and when set to "two-level-mq", enforcement shaping is applied.  Enforcement shaping is applied both for subscribers and Access Points.  Configure each access point in the online application; the default speed for the AP is that of the link itself.
  • defaultLevel2DownloadRate / defaultLevel2UploadRate: maximum Download/Upload rates, in kbps, for a subscriber with no speed defined.
  • rate: maximum rate for the link itself, expressed in kbps; this parameter remains, but is deprecated

In the example sections below, we will assume a 970 Mbps link speed and 100 Mbps (downstream) x 60 Mbps (upstream) bandwidth default subscriber configuration.  Here is the starting point:

links:
enp4s0:
ignore: true
enp5s0:
 ignore: true
enp6s0:
internetFacing: true
enp7s0:
internetFacing: false

IMPORTANT NOTE: As sudo / root user, change the parameters of interest, pay particular attention to the spacing, do not use tabs, and read about the YAML format if you are interested (https://en.wikipedia.org/wiki/YAML).  Then, save the file.  The instructions provided are subject to change, so please refer to this page often.

Example Configuration

Here is the configuration changes necessary to implement the values mentioned earlier.

links:
enp4s0:
ignore: true
enp5s0:
ignore: true
enp6s0:
internetFacing: true
qosTransmitPolicy:
name: two-level-mq
rate: 9700000
twoLevelConfig:
defaultLevel2DownloadRate: 100000
defaultLevel2UploadRate: 60000
enp7s0:
internetFacing: false
qosTransmitPolicy:
name: two-level-mq
rate: 9700000
twoLevelConfig:
defaultLevel2DownloadRate: 100000
defaultLevel2UploadRate: 60000

The qosTransmitPolicy line has 4 spaces at the beginning. The name, rate and subscriberConfig/twoLevelConfig lines have 6, and the default lines have 8. Veering from this requirement will prevent the configuration from being loaded.

Mini Quiz Questions:

  1. Is this configuration enforcing shaping or not?
  2. Which interface is configured to receive packets from the internet?

Apply the Changes

Once changes are made to accommodate your needs, restart the Network Device Manager service (requires sudo / root permission):

sudo systemctl restart preseem-netdev-manager

Check the System

To check that the reload was successful, run:

systemctl status preseem-netdev-manager
[root@preseem ~]# systemctl status preseem-netdev-manager
● preseem-netdev-manager.service - Preseem NetdevManager service
Loaded: loaded (/usr/lib/systemd/system/preseem-netdev-manager.service; enabled; vendor preset: disabled)
Active: active (running) since Mon 2019-05-27 02:38:17 UTC; 3 weeks 4 days ago
Docs: https://www.preseem.com
Main PID: 2035 (preseem-netdev-)
Tasks: 14 (limit: 4915)
Memory: 54.9M
CGroup: /system.slice/preseem-netdev-manager.service
└─2035 /usr/sbin/preseem-netdev-manager

May 27 02:38:18 preseem preseem-netdev-manager[2035]: 2019/05/27 02:38:18 Populating IP network <removed> for address space default
May 27 02:38:18 preseem preseem-netdev-manager[2035]: 2019/05/27 02:38:18 Received NM entity loaded
May 27 02:38:18 preseem preseem-netdev-manager[2035]: 2019/05/27 02:38:18 Received NM reference entity loaded
May 27 02:38:19 preseem preseem-netdev-manager[2035]: 2019/05/27 02:38:19 Publishing configuration

To make sure that all services are up, check the system status by running this command like earlier:

preseemctl system show

To list all active shaping sessions in your Preseem device, you can run this command:

preseemctl session show --format csv > /tmp/session.csv

This will create a file called /tmp/session.csv, and it will contain one comma-separated line per subscriber IP address, including multiple useful pieces of information, e.g. AP and its speed.