This is an old revision of the document!


mod_feature_capping.pm

Implements traffic or session time based capping defined using certain attributes that can be set at a group or user level.

Config File

The following section is supported in the smradiusd.conf configuration file.

Enable Mikrotik specific attributes to allow better control of capping and traffic control by setting session limits.

enable_mikrotik=yes

Supported v1.0.x

Enable the captrafzero caveat. This will swap the meaning of 0 and undef on traffic capping limits. There was a logic error prior to v1.0.x.

caveat_captrafzero=yes

Attributes

Limits, also known as capping.

Defines a maximum traffic usage allowed. This value is in Mbyte.

If unset, this value is unlimited.

If this value is set to 0, topups must be added.

SMRadius-Capping-Traffic-Limit  :=  500

Defines a maximum session time allowed. This value is in minutes.

If unset, this value is unlimited.

If this value is set to 0, topups must be added.

SMRadius-Capping-Uptime-Limit  :=  500

Usage manipulation can be used to multiple the current usage to determine limits on other clients.

For instance a user with a 1G traffic limit, may have a multiplication factor of 2 on a LTE network which would result in him only being able to use 500M of traffic.

This attribute is a modifier for traffic limit. The limit for traffic will be multiplied by this value so that the effective traffic limit can be set to a portion of the total limit. Note - this attribute is commonly added to the clients as a client attribute. The advantage is being able to select a portion of users in a larger pool of users who are allowed additional traffic usage, or less traffic usage as needed.

SMRadius-Config-Capping-Traffic-Multiplier  :=  0.5

This attribute is a modifier for uptime limit. The limit for uptime will be multiplied by this value so that the effective uptime limit can be set to a portion of the total limit. Note - this attribute is commonly added to the clients as a client attribute. The advantage is being able to select a portion of users in a larger pool of users who are allowed additional uptime, or less uptime as needed.

SMRadius-Config-Capping-Uptime-Multiplier  :=  0.5

Supported v1.0.x

The same attributes are used for Traffic and Uptime, just replace $TYPE below.

Auto-topups are stored in the topups table…

               ID: 2078471
           UserID: 11391
        Timestamp: 2016-09-18 13:59:42
             Type: 5   <= The 'Type' is OR'd with the value 4
        ValidFrom: 2016-09-18 00:00:00
          ValidTo: 2016-10-01 00:00:00
            Value: 500
         Depleted: 0
SMAdminDepletedOn: NULL

Type 1 is a Traffic topup.

Type 2 is a Uptime topup.

Type 4 is a Auto-topup.

This attribute enables the $TYPE auto-topup facility. The operator used is := and the value needs to be a positive boolean either 1, true, yes.

SMRadius-AutoTopup-Traffic-Enabled  :=  yes

This is the amount per auto-topup of $TYPE. The operator used is := and the value is in minutes or Mbyte.

SMRadius-AutoTopup-Traffic-Amount  :=  500

This is the limit on the total amount of auto-topups that can be added within the current period. The operator used is := and the value is in minutes or Mbyte.

SMRadius-AutoTopup-Traffic-Amount  :=  2000

This attribute enables the notification mechanism and sets the notification means. The operator used is := and the value is the notification means, for instance an email address. This attributes' value can be comma or semicolon separated.

SMRadius-AutoTopup-Traffic-Notify  :=  joe@example.com

The template parsing is done using Template::Toolkit.

Supported macro's include:

  • user.ID
  • user.username
  • usage.total
  • usage.limit
  • autotopup.amount
  • autotopup.limit
  • autotopup.added
  • autotopup.toAdd (if this is 0, it means additional auto-topups cannot be added)
  • autotopup.toAddAmount

Example below…

To: [% notify.target %]
From: Test ISP <isp\@example.com>
Subject: [Test ISP] Your account [% user.username %]

[% IF autotopup.toAdd %]
Please note that you have [% usage.limit - usage.total %]Mbyte available on username [% user.username %]. We added another [% autotopup.toAdd %] automatic topup(s) totalling [% autotopup.toAddAmount %]Mbyte to your username. Your automatic topup usage is [% autotopup.added + autotopup.toAddAmount %]Mbyte of [% autotopup.limit ? autotopup.limit : '-no-limit-' %]Mbyte.
[% ELSE %]
We cannot add another [% autotopup.amount %]Mbyte to your username as you have reached your automatic topup limit of [% autotopup.limit %]Mbyte. Your total usage is [% usage.total %]Mbyte.
[% END %]

Regards
Your Test ISP
Support: +1 555 555 555

The threshold can be set to 0, which means only when the total limit has been exceeded will an auto-topup be added.

If the value is left undefined it will default to (Amount / 2).

Configuration Attributes

The below configuration attributes are set by SMRadius.

The amount of additional traffic in Mbyte which the user can consume outside of the normal traffic limit before being disconnected and denied login. This attribute is set by the server using mod_config_sql_topups.pm.

The amount of additional uptime in minutes which the user can remain online for before being disconnected and denied login. This attribute is set by the server using mod_config_sql_topups.pm.

Supported v1.0.x

The amount of traffic added by means of auto-topup in Mbyte. This attribute is set by the server using mod_config_sql_topups.pm.

Supported v1.0.x

The amount of time added by means of auto-topup in minutes. This attribute is set by the server using mod_config_sql_topups.pm.

Hooks

post_auth_hook

Runs the checks based on attribute configuration to determine whether or not traffic or uptime limits have been reached. Runs at the post authentication stage.

post_acct_hook

Runs the checks based on attribute configuration to determine whether or not traffic or uptime limit have been reached. Runs at the post authentication stage.