BQN Docs – Subscriber Quotas

Subscriber Quotas

Time and volume quotas can be associated to a subscriber IP address. Once a quota is exhausted, the subscriber IP address is restricted (by default, the traffic is blocked). Both a time and a volume quota can be associated to an IP address at the same time, in which case the restriction happens when any of the quotas is exhausted.

Quotas are assigned to IP addresses. If a subscriber changes the IP address to a new one, that new IP address will not have a quota associated until one is provisioned through the REST API.

A time quota grants access for a period. There are two ways to define a time quota:

As an absolute time. For example, 05/23/2023 (23^rdof May, 2023).
As an extension of current date (e.g. 15 days from now).

A volume quota grants access for a volume of traffic. There are two ways to define a time quota:

As an absolute amount. For example, 10 GB.
As an extension of amount (e.g. 5 GB on top of existing 10).

‍

Quota General Configuration

To configure general aspects of quota behavior, go to Status->Subscribers->Subscriber Quotas and extend Advanced Quota Parameters.

‍

Subscriber initial quota status defines what to do with IP addresses without an assigned quota:

When set to disabled (the default), traffic is allowed, without restrictions.
When set to blocked, traffic will be blocked until a valid quota is assigned.

The redirect URL fields specify the sites to redirect HTTP traffic when an IP address is blocked (captive portal) because of quota exhaustion. There is one field to redirect IPv4 traffic and another for IPv6 traffic. The two fields can have the same URL if the same captive portal is used for both IPv4 and IPv6.

If the field is empty, no redirection is attempted.
If a URL is specified, a redirection is attempted to that URL for the corresponding IP version of the HTTP traffic.

HTTPS redirections are not supported, because modern browsers are protected against redirection attempts for security reasons.

Note that though only HTTP redirections are supported, the site to redirect the traffic can be HTTPS, and very often it is (this is what reflects the previous screenshot, where the URL used is https://my-captive-portal.com).

If HTTP redirections are used, a policy is needed to allow the traffic to the redirection sites (and associated DNS queries). See the section on Captive portal policies for details.

‍

Associating Quotas to Subscriber IPs

To associate a quota to a subscriber IP address, go to Status->Subscribers->Subscriber Quotas. Click on Add Quota to new Subscriber… It can also be accessed from Configuration->Subscriber Quotas->Subscriber Quotas.

The following example define a time quota as an absolute time:

‍

It is also possible to define the time quota relative to current date and time (+1 month in the example):

To define a volume quota, first define an absolute value (20GB in the example):

Once created, a volume quota can be extended editing the quota and using the option Increment limit by this amount (5 GB in the following example):

‍

Note that the field Current Volume Used informs about the quota already gone. A pie chart on the lower right shows it graphically.

Time and volume quotas can coexist, and in this case the subscriber traffic will be restricted when either of the two become exhausted.

It is also possible to edit the quota and remove its time or volume component pressing the button Remove Time Limit or Remove Volume Limit respectively.

Checking quota state

‍

Status->Subscribers->Subscriber Quotas shows the quotas and, in the case of volume quotas, how much has been consumed already.

In the previous example, there are three volume quotas, and two time quotas (note that month is given before day, so 9/29/2023 is 29^thof September 2023). For volume quotas, the volume already consumed is also shown (for example, 10.0.0.3 has a quota of 15 GB and it has consumed 20 MB).

‍

Slow down when Quota exhausted

‍

By default, the traffic will be completely blocked when the quota is exhausted, but it is possible to limit the traffic to a slow speed while the quota is not topped up again.

The following example changes the flow-default policy, so it slows down traffic when the quota is exhausted:

‍

Traffic not subject to quota

It is possible to define some traffic to be excluded fromthe quota (it will not increase quota usage and will not be blocked when quotais exhausted). In this example, some video streaming identified by DPI is associated to a policy not subject to quota.

When RADIUS is used to report quota usage, this traffic free of quota is deducted of the reported volume.

The policy not affected by quota exhaustion has the quota switchset to off:

‍

Captive portal Policy

In the section about quota general configuration, we saw how to define a redirection to a captive portal when the quota is exhausted. The captive portal implementation requires that traffic to it is not subject to the quota.This is implemented using flow policies.

In the following example, two traffic categories need to be out of the quota control (policy flow-no-quota):

Traffic going to the captive portal.
Traffic to some specific DNS servers (use to resolve the captive portal URL).

The DNS and captive portal traffic is associated to a policy not subject to quota (see an example in previous section).

‍

Quotas managed using REST API

In addition to the GUI, the BQN REST API can be used to manage time and volume quotas.

See REST API reference for more details.

‍

Time Quota

There are two ways to define a time quota:

As an absolute time: as POSIX time, defined as the number of seconds elapsed since midnight Coordinated Universal Time (UTC) of January 1, 1970. For example, 1672531200 is UTC Sunday, 1 January 20230:00:00. Absolute time is UTC, so convert your local time to UTC when setting the quota.
As seconds relative to current time: for example, a 3600 second quota will be exhausted an hour from now.

‍

To enable a time quota of one hour:


curl -k -u myuser:mypassword -X POST https://192.168.0.121:3443/api/v1/subscribers/10.0.0.35 -H "Content-Type: application/json" --data '{"quota": {"timeRemaining": 3600}}'

‍

To extend the quota to two hours from now:


curl -k -u myuser:mypassword -X PUT https://192.168.0.121:3443/api/v1/subscribers/10.0.0.35 -H "Content-Type: application/json" --data '{"quota": {"timeRemaining": 7200}}'

‍

To remove the quota, so the subscriber is no longer subject to a time quota:


curl -k -u myuser:mypassword -X PUT https://192.168.0.121:3443/api/v1/subscribers/10.0.0.35 -H "Content-Type: application/json" --data '{"quota": {"time": null}}'

‍

Volume Quota

A volume quota grants access for a number of Kbytes of traffic. The BQN convention is that 1 Kbyte is 1000 bytes.

‍

To enable a 1GB volume quota:


curl -k -u myuser:mypassword -X POST https://192.168.0.121:3443/api/v1/subscribers/10.0.0.35 -H "Content-Type: application/json" --data '{"quota": {"volume": 1000000}}'

‍

To extend the quota adding 500 MB:


curl -k -u myuser:mypassword -X PUT https://192.168.0.121:3443/api/v1/subscribers/10.0.0.35 -H "Content-Type: application/json" --data '{"quota": {"volumeIncrement": 500000}}'

‍

To remove the quota, so the subscriber is no longer subject to a volume quota:


curl -k -u myuser:mypassword -X PUT https://192.168.0.121:3443/api/v1/subscribers/10.0.0.35 -H "Content-Type: application/json" --data '{"quota": {"volume": null}}'

‍

Volume and Time Quotas at the same time

‍

To enable a 1GB volume quota and 1 month (whatever happens first):


curl -k -u myuser:mypassword -X POST https://192.168.0.121:3443/api/v1/subscribers/10.0.0.35 -H "Content-Type: application/json" --data '{"quota": {"volume": 1000000, "timeRemaining": 2678400}}'

‍

To extend the volume quota in 500 MB, keeping the time quota unchanged:


curl -k -u myuser:mypassword -X PUT https://192.168.0.121:3443/api/v1/subscribers/10.0.0.35 -H "Content-Type: application/json" --data '{"quota": {"volumeIncrement": 500000}}'

‍

To remove both quotas, so the subscriber is no longer subject to them:


curl -k -u myuser:mypassword -X PUT https://192.168.0.121:3443/api/v1/subscribers/10.0.0.35 -H "Content-Type: application/json" --data '{"quota": {"volume": null, "time": null}}'

‍

Checking quota state

You can also check the quota state through the REST API:


curl -k -u myuser:mypassword -X GET https://192.168.0.121:3443/api/v1/subscribers/10.0.0.35

{
  "subscriberIp": "10.0.0.35",
  "quota" : {
    "volume" : 1000000000,
    "volumeConsumed" : 647474875
    "time" : 1676628377,
    "timeRemaining" : 5364849
  },
  "policyRate" : ""
}

Quotas managed from RADIUS

BQN in RADIUS proxy deployment can handle volume and time quotas. Go to RADIUS chapter for more details.

Docs styling tags

[.p-highlight] Lorem ipsum... [.p-highlight]

Lorem ipsum dolor sit amet, consectetur adipiscing elit. Suspendisse varius enim in eros elementum tristique. Duis cursus, mi quis viverra ornare, eros dolor interdum nulla, ut commodo diam libero vitae erat. Aenean faucibus nibh et justo cursus id rutrum lorem imperdiet. Nunc ut sem vitae risus tristique posuere.

[.p-highlight-blue] Lorem ipsum... [.p-highlight-blue]

[.p-highlight-red] Lorem ipsum... [.p-highlight-red]

Preview for the single [.c-highlight]word mono-spaced[.c-highlight] styling.

Preview for the single word mono-spaced styling.