BQN Documentation
BQN Documentation

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 theIP address to a new one, that new IP address will not have a quota associateduntil one is provisioned through the REST API.

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

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

A volume quota grants access for a volume of traffic. Thereare 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 ofexisting 10).

 Quota General Configuration

To configure general aspects of quota behavior, go to Configuration->Quotas.

Subscriber initial quota status defines what to dowith 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 whatreflects the previous screenshot, where the URL used is

If HTTP redirections are used, a policy is needed toallow the traffic to the redirection sites (and associated DNS queries). See thesection 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

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):

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, with 0 usage at the moment, and two time quotas (note that month is given before day, so 6/29/2023 is 29th of June 2023).

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:

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 policy not affected by quota exhaustion has the quota switchset to off:

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: forexample, 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 -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 -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 -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 -H "Content-Type: application/json" --data '{"quota": {"volume": 1000000}}'

To extend the quota adding 500 MB:

curl -k -u myuser:mypassword -X PUT -H "Content-Type: application/json" --data '{"quota": {"volumeIncrement": 500000}}'

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

curl -k -u myuser:mypassword -X PUT -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 -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 -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 -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

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