Section 3.81. <AuthBy HOTSPOT>

3.81. <AuthBy HOTSPOT>

<AuthBy HOTSPOT> provides advanced support for hotspot functionality, including differentiated services and prepaid/postpaid quotas. It combines <ServiceDatabase>, <SessionDatabase>, an authenticating <AuthBy xxxxxx> to a working solution which can be used with captive portals (for example MikroTik) and network access controllers supporting RADIUS. Besides hotspot use-case, <AuthBy HOTSPOT> can also be used to implement quota control for fixed-line access or cellular APN. It can also utilise <AuthBy DYNAUTH> (RADIUS Dynamic Authorization) for sending CoA/DM, for example, after a successful authentication or when a quota has been depleted.

See goodies/hotspot.cfg and goodies/README.hotspot for a sample configuration file. For a derived AuthBy, see Section 3.83. <AuthBy HOTSPOTFIDELIO>.

<AuthBy HOTSPOT> understands also the same parameters as <AuthBy xxxxxx>. For more information, see Section 3.32. <AuthBy xxxxxx>.

3.81.1. ServiceId

This optional string parameter specifies how to derive the Identifier of the Service to provision a subscription. Special variable %0 contains identifier of this AuthBy. There is no default value.

3.81.2. SubscriptionId

This optional string parameter specifies how to derive the Identifier of the Subscription to handle a request. Special variable %0 contains identifier of this AuthBy, %1 the username and %2 hotspot id . Default value is %1.

# Lookup a subscription based on username (%1) and Calling-Station-Id MAC address
SubscriptionId %1-%{Calling-Station-Id}

3.81.3. SessionId

This optional string parameter specifies how to derive the Identifier of the Session to handle a request. Special variable %0 contains identifier of this AuthBy, %1 the username , %2 hotspot id and %3 Class attribute value . There is no default value.

# Lookup a session based on username, Class and Calling-Station-Id MAC address
SessionId %1-%3-%{Calling-Station-Id}

3.81.4. ServiceAttribute

This optional string parameter specifies name of RADIUS attribute that is used to detect different services. There is no default value.

# Our hotspot is configured this send this attribute in RADIUS requests
ServiceAttribute OSC-AVPAIR

3.81.5. ServiceAttributePrefix

This optional string parameter specifies the prefix in ServiceAttribute value. You need to specify this if there is possibility to have multiple RADIUS attributes that are defined to be ServiceAttribute. There is no default value.

# Access-Request from our captive portal has multiple instances
# of ServiceAttribute, use the ones with this prefix 
ServiceAttributePrefix Mikrotik-Service=

3.81.6. SubscriptionAttribute

This optional string parameter specifies name of RADIUS attribute that is used to detect different subscriptions. There is no default value.

3.81.7. ServiceAttributePrefix

This optional string parameter specifies the prefix in SubscritionAttribute value. You need to specify this if there is possibility to have multiple RADIUS attributes that are defined to be SubscriptionAttribute. There is no default value.

3.81.8. SessionAttribute

This optional string parameter specifies name of RADIUS attribute that is used to detect different sessions. If this is set to an empty value, SessionId parameter is used to detect sessions. Defaults to Acct-Session-Id.

# Set this to an empty value
SessionAttribute

3.81.9. SessionAttributePrefix

This optional string parameter specifies the prefix in SessionAttribute value. You need to specify this if there is possibility to have multiple RADIUS attributes that are defined to be SessionAttribute. There is no default value.

3.81.10. DefaultService

This optional string parameter specifies a name of default service when the request does not contain ServiceAttribute. Defaults to default.

# Name of default service defined in our ServiceDatabase 
DefaultService free

3.81.11. DefaultServiceDefinition

This optional string parameter defines the default service to use when no service definition was found from our ServiceDatabase. Defaults to name:default price:0.

# Make this empty for no default configured service 
DefaultServiceDefinition

3.81.12. ConfirmSubscription

This optional flag parameter specifies if RADIUS Access-Reject message with Reply-Message attribute is used to ask for a confirmation of the upgrade or renewal charge. Disabled by default.

# Use Access-Reject with Reply-Message for confirmation 
ConfirmSubscription

3.81.13. ConfirmationMessage

This optional string parameter specifies the message that will ask the guest to confirm the upgrade or renewal charges when ConfirmSubscription flag parameter is set. Defaults to:

You are going to upgrade or renew your plan, please login
                     again to confirm the charge.

# Change the default to more specific 
ConfirmationMessage Please log in again to approve Wi-Fi charge at checkout.

3.81.14. PreProvisionSubscription

Set this optional flag parameter to create a subscription externally before the authentication. Defaults to not set.

3.81.15. PreProvisionSession

Set this optional flag parameter to create a session when the authentication is accepted. Defaults to not set.

# If RADIUS accounting will be used for quota monitoring,
# create a new session upon a successful authentication
PreProvisionSession

3.81.16. AuthBy

This string parameter specifies which AuthBy will be used to authenticate users. Special formatting characters are permitted. Defaults to not set but must be configured with a value.

# Authenticate Hotspot users with AuthBy that has this identifier
AuthBy AuthBy-FILE

3.81.17. ServiceDatabase

This string parameter specifies which ServiceDatabase will be used to query service and subscription information. Special formatting characters are permitted. Defaults to not set but should be configured with a value.

# Use ServiceDatabase with this identifier for services and subscriptions
ServiceDatabase ServiceDatabase-INTERNAL

3.81.18. SessionDatabase

This string parameter specifies which SessionDatabase will be used to query session information. Special formatting characters are permitted. Defaults to not set but should be configured with a value.

# Use SessionDatabase with this identifier for sessions
SessionDatabase SessionDatabase-INTERNAL

3.81.19. PoolIPv4Attribute

This optional string parameter specifies name of RADIUS attribute to return when Service/Subscription has IPv4 pool. Defaults to PoolHint.

# Use non-default IPv4 pool attribute name to return service pool name
PoolIPv4Attribute Framed-Pool

3.81.20. PoolIPv6Attribute

This optional string parameter specifies name of RADIUS attribute to return when Service/Subscription has IPv6 pool. Defaults to PoolHint6.

# Use non-default IPv6 pool attribute name to return service pool name
PoolIPv6Attribute Framed-IPv6-Pool

3.81.21. UsageMonitoring

When this optional flag parameter is set, deplete Subscription quotas only based on RADIUS accounting. Disabled by default.

# Use accounting and return to NAS remaining time quota with Session-Timeout
# and data quota with Mikrotik attributes.
UsageMonitoring
ReplyWithDataQuota
DataLimitAttribute Mikrotik-Total-Limit
DataLimitGigawordsAttribute Mikrotik-Total-Limit-Gigawords

3.81.22. ReplyWithBandwidthControl

When this optional flag parameter is set, add Service/Subscription bandwidth limit RADIUS attributes to the reply. Enabled by default.

# Enable BW control for pre-paid, post-paid and throttled (quota exceeded) cases
ReplyWithBandwidthControl
UploadRateAttribute WISPr-Bandwidth-Max-Up
DownloadRateAttribute WISPr-Bandwidth-Max-Down

3.81.23. UploadRateAttribute

This optional string parameter specifies name of RADIUS attribute that is used to return Service/Subscription Upload bandwidth limit. Default value is OSC-Upload-Rate. See Section 3.81.22. ReplyWithBandwidthControl for an example.

3.81.24. DownloadRateAttribute

This optional string parameter specifies name of RADIUS attribute that is used to return Service/Subscription Download bandwidth limit. Default value is OSC-Download-Rate. See Section 3.81.22. ReplyWithBandwidthControl for an example.

3.81.25. ReplyWithDataQuota

When this optional flag parameter is set, Add Service/Subscription data limit RADIUS attributes to the reply. Disabled by default. See Section 3.81.21. UsageMonitoring for an example.

3.81.26. DataLimitAttribute

This optional string parameter specifies name of RADIUS attribute that is used to return Service/Subscription data limit. Default value is OSC-Data-Limit. See Section 3.81.21. UsageMonitoring for an example.

3.81.27. DataLimitGigawordsAttribute

This optional string parameter specifies name of RADIUS attribute that is used to return Service/Subscription data limit gigawords. Default value is OSC-Data-Limit-Gigawords. See Section 3.81.21. UsageMonitoring for an example.

3.81.28. ChargeHook

This optional parameter allows you to define a Perl function to modify a subscription charge.

ChargeHook must return new username, a charging reference and new price. Charging reference can be undefined. If username is undefined, charging is not done and request is rejected.

ChargeHook has the following arguments:

The current request
Username
Id, such as room number, plane seat number or loyalty card number or other value typically sent as password with a hotspot service
Price
Subscription

Here is an example of ChargeHook:

# Charge mikem with double rate
ChargeHook sub {my $name = $_[1]; my $price = $_[3]; \
                return ($name, undef, $price*2);}

3.81.29. ReplyAdjustHook

This optional parameter allows you to define a Perl function to adjust RADIUS Access-Accept reply.

ReplyAdjustHook return value is ignored. However, it is passed references to current request and reply for modification.

ReplyAdjustHook has the following arguments:

The current request
The current reply
Time left
Octets left
Gigawords left
Reference to the Service object
Reference to the Subscription object
Reference to the Session object
Reference to the current AuthBy

Here is an example of ReplyAdjustHook:

# Reply debugging for radpwtst testing
ReplyAdjustHook sub {my $rp = $_[1]; my $time_left = $_[2]; \
                     $rp->add_attr('OSC-AVPAIR', "time-debug=$time_left"); }

3.81.30. SessionQuotaSupplyFraction

This optional integer parameter specifies percentage (1-100) of remaining Subscription quota to allocate for a session. Defaults to 20.

# Allocate only 10%
SessionQuotaSupplyFraction 10

3.81.31. SessionQuotaResupplyThreshold

This optional integer parameter specifies percentage threshold (1-100) for session quota usage to resupply session quotas from a subscription. Defaults to 80.

# Experiment with 90% threshold
SessionQuotaResupplyThreshold 90

3.81.32. SessionQuotaResupplyTimeMin

This optional string parameter specifies the minimum amount of time quota to allocate from a subscription for a session. Value is seconds or a string with one letter suffix of y,d,h,m for year, day, hour or minute, respectively. Defaults to 10 minutes.

# Change resupply time to 20 minutes. 1200 would work also as the value. 
SessionQuotaResupplyTimeMin 20m

3.81.33. SessionQuotaResupplyDataMin

This optional string parameter specifies the minimum amount of data quota to allocate from a subscription for a session. Value is octets or a string with one letter suffix of G,M,K for 10^9, 10^6 or 10^3 octets, respectively. Defaults to 1M octets.

# Change resupply data to 20 000 000 octets. Can use 20M or 20000000 as the value. 
SessionQuotaResupplyDataMin 20M