Controlling Volume Usage with the VTA > How the VTA Works

How the VTA Works

The VTA manages subscriber accounts using a rule-driven event processing system that can prioritize the actions taken for certain conditions. The VTA is triggered by events, such as the logging in of subscribers, the use of network services, or the changing of account balances. These events can cause actions, such as updating account balances, starting or stopping network services, or running scripts to perform external actions.

A VTA processes external events based on its configuration. A VTA configuration is made up of:

• Event handlers
• Actions
• Processors

Events

Each VTA event corresponds to one subscriber and contains some attributes. The VTA supports the following types of events:

• Service and subscriber tracking events from the SAE; for example, start or stop tracking events.
• Account update events triggered by updating database accounts.
• Callback events triggered by a method call.

Event Attributes

Each event carries attributes. Table 2 describes the types of attributes that are available for each type of event.

 Table 2:  Event Attributes  

 Event Type 
 Available Attributes 

 Service and subscriber tracking events from the SAE 


  
 Plug-in attributes, such as PA_SERVICE_NAME or PA_LOGIN_NAME, associated with an SAE plug-in event. For a list of SAE plug-in events, see the SAE CORBA plug-In SPI online documentation on the Juniper Networks Web site at http://www.juniper.net/techpubs/software/management/sdx/api-index.html or in the SDX software distribution SDK/doc/idl/sae/html/index.html.
  
 The currentTime attribute, which is the time since January 1, 1970 UTC when the VTA receives the event. The value is the number of milliseconds in the range 0-9223372036854775807. 



 Account update events 


  
 Old status of the account. 
  
 New status of the account. 
  
 Last time the account was updated—both old time and new time. 
  
 Old balance of the account. 
  
 New balance of the account.
  
 Time since January 1, 1970 UTC, when the VTA receives the event. 



 Callback events 


  
 The callId attribute and all parameters provided with the callback. 
  
 The currentTime attribute is the time since January 1, 1970 UTC, when the VTA receives the event. The value is the number of milliseconds in the range 0-9223372036854775807. 




 

Event Handlers

An event handler defines how the VTA processes an event. VTA event handlers consist of:

• Type of event—Tracking, update, or callback event; for example, a subscriber start-tracking event or a service start-tracking event.
• Priority—Priority at which event handlers are evaluated and executed. Event handlers are evaluated and executed from high to low priority.
• Condition—Condition that the event handler evaluates to determine whether the event handler should handle the event.
• Actions—List of actions to be performed by the event handler.

You can set up multiple event handlers to process events. For example, the first event handler could retrieve the balance for a quota account, and the next event handler could refill the quota account, depending on whether the condition of the second event handler is met.

Figure 2 shows the event handler model. The VTA processes an event as follows:

1. The event handler with the highest priority receives the event, checks if the event's type is the same as the event type of the event handler, and checks if the event satisfies the condition of the event handler.
2. If the condition is met, the VTA performs the corresponding actions based on the event attributes. An action invokes a function and provides the parameters required by that function to the processor.
3. When an event handler finishes processing an event, the next applicable event handler according to the priority of the event handler processes the event.

Figure 2: VTA Event Handler Model

Actions

You can specify actions that the VTA takes in response on an event; for example, updating an account balance, starting a service, or stopping a service. The actions are performed if the event is of the specified type and matches the specified condition. An action is modeled as a call to a function.

An action can update event attributes or add new attributes to an event for subsequent processing of the same event by another event handler.

An action configuration includes:

• Function—Function that the action invokes
• Parameter—Parameters and corresponding values to be passed to the function

VTA Processors

Processors receive and process events. The VTA has four processors:

• Database engine processor—Acts as a proxy to a database.
• Mail processor—Sends e-mail notifications when certain events occur.
• SAE proxy processor—Acts as a proxy to the SAE.
• Script runner processor—Runs external scripts or JavaScript programs.

Database Engine Processor

The database engine processor is a proxy to a database. You can use the database engine processor to:

• Calculate the use of network resources for a service.
• Calculate the interim accounting interval for each service based on a subscriber's remaining resources and use of the service.
• Update VTA accounts with a JavaScript program.
• Terminate a VTA session. This feature is usually used at the end of a billing period so that you can finish collecting data for the current billing period and start a new VTA session for the new billing period.

Mail Processor

You use the mail processor to set up the VTA to send e-mail notifications to subscribers when certain events occur.

SAE Proxy Processor

You can use the SAE proxy processor to:

• Set an interim interval for a service.
• Set a service session timeout for a subscription.
• Set a session timeout for a subscriber.
• Start a subscription to a service. You can specify the parameter substitutions to use when the service is started.
• Stop a subscription to a service. You can include a reason for the subscription's being stopped. When the service is stopped, the reason is sent to the billing system so it can differentiate between service stops.

The SAE proxy processor is a proxy to the SAE external interface that resolves the subscriber interface based on the event types to which functions are applied.

• If a function is applied to SAE subscriber-tracking or service-tracking events, the processor finds the SAE reference in the event message.
• If a function is applied to other events, the processor uses subscriber's ID in the event as the key for the NIC to find the SAE reference.

Script Runner Processor

The Script runner processor can invoke external executable scripts or JavaScripts. We recommend using JavaScript, where possible, for better performance.

• External scripts are executable programs, such as shell scripts, that are available on the VTA's host. Each external script can perform a task and return a value. If the script returns a value, the value can be added to the current event as an event attribute.
• JavaScript programs are used to process attributes of a VTA event. For example, it can convert a VTA event attribute in a timestamp to a date string and add it to the event as a new attribute. The attribute can then be used for subsequent actions, such as sending an e-mail notification to the subscriber. The JavaScript program can refer to any attributes of the event being processed, and it must return a value.

VTA Operation

Figure 3 illustrates the VTA operation process.

Figure 3: Operation of the VTA

The VTA operates as follows:

1. When an event that activates a value-added service occurs (for example, a subscriber logs in), the SAE sends a session start event to the VTA through the SAE external plug-in interface.
2. Optionally, the VTA queries a database for the subscriber's current set of sessions and accounts.
3. Depending on the configuration of the VTA, it may activate or deactivate services based on the subscriber's use of resources.
4. The VTA tracks the subscriber's use of resources for a period of time.
5. The VTA updates sessions and account balances in the database.
6. The VTA sends to the SAE changes in the interim accounting interval and takes action to limit excessive bandwidth use or to allow increased bandwidth use.
7. When an event that deactivates a value-added service occurs (for example, the subscriber logs out), the VTA updates the VTA session, closes the VTA session, and may update the account balances.

Events received through the remote interface can also cause the VTA to activate services, deactivate services, or change the accounting interval.

Example: Limiting Subscriber Access Based on Account Balances

The sample data provides an example called Quota that limits a subscriber's access rate based on the balances of accounts that record the subscriber's use of network resources. Subscribers receive a quota of transfer (upload and download) volume in two ways:

• Periodic quota—Volume that is periodically added to a subscriber's account. For example, a subscriber may receive a 25-MB periodic quota each month. The periodic quota is tracked in the periodic account.
• Bought quota—Additional volume that a subscriber can purchase and use at any time. For example, a subscriber may purchase 25 MB of bought quota in January, and use the bought quota between January and March. Bought quota is tracked in a bought account.

As a subscriber consumes volume, the VTA debits the accounts, using first the periodic quota and, if no periodic quota is available, the bought quota.

Subscribers managed by a VTA require a subscription to quota services—value-added services for which a VTA monitors and manages usage. You must configure these subscriptions to be activated when the subscriber logs in. When a subscriber logs in to the SAE, the SAE tries to activate the quota services. However, if neither the periodic account nor the bought account has a positive balance, the VTA deactivates the quota services, and the SAE applies to the subscriber either the default policy or another policy that implements a service with a lower bandwidth.

The units of the accounts depend on the formula that you define to determine the use of network resources. With this formula, the VTA calculates the change to the accounts and the interim accounting interval.

The Quota configuration example provides a VTA that operates as follows:

1. When a service session for the quota service starts, the SAE sends a start event to the VTA.
2. The VTA starts a VTA session that has the same identifier as the service session and a qualifier of zero.
3. When the VTA receives the first interim update from the SAE in a VTA session, it records a balance change that details the use of resources and the event time for the VTA session. When the VTA receives interim updates in the VTA session, it updates the use of resources and the event time in the balance change recorded previously.

• If the periodic account contains sufficient resources to cover the balance change, the VTA changes only the balance of that account.
• If the periodic account does not contain sufficient resources for the change, the VTA records one balance change for the resources available in that account and records another balance change for the difference in the bought account. In this case, the VTA records subsequent balance changes to the bought account.
• If neither account has sufficient resources, the VTA deactivates the quota service.

4. If the SAE session ends, the VTA session ends. When a new service session starts, Steps 1 to 3 recur. However, a service session may last for several VTA sessions. In this case, the SAE and VTA continue the process described in Step 3.
5. When an administrator replenishes the periodic quota, the VTA ends the VTA session, finalizes all balance changes for the session, and records a credit to the periodic account.
6. When the subscriber buys additional volume, the VTA ends the VTA session, finalizes all balance changes for the session, and records a credit to the bought account.
7. When the VTA next receives an interim update event from the SAE, it starts a new VTA session. The VTA obtains the start time for the VTA session from the SAE event, and records debits to the accounts as described in Step 3.

The VTA always ends the VTA session when an administrator replenishes periodic quota or the subscriber buys volume. However, a service session may last for several billing periods. In this case, when the VTA starts a new VTA session, it continues to assign the SAE session identifier to the VTA session and increments the qualifier by one. Keeping the VTA session within a billing period allows the VTA to finalize balance changes.