SDX 6.4.x Application Library Guide > Installing and Initially Configuring the VTA > Related Configuration Tasks

Related Configuration Tasks

The VTA configuration script configures the components that it finds and accesses on each host. However, depending on your configuration and the components you use, such as the type of database and J2EE application server, you may need to manually configure some of the components or the configuration. This section provides a complete list of the configuration procedures related to the VTA and explains which procedures the VTA configuration script completes. It includes:

1. Configuring a Database to Store Account and Session Data
2. Configuring the J2EE Application Server
3. Configuring VTA Services and Policies
4. Configuring Subscribers and Subscriptions to VTA Services
5. Accessing the J2EE Application Server's Client Libraries
6. Specifying How the VTA Loads Configurations from the Directory
7. Configuring the SAE to Send Tracking Events to the VTA
8. Specifying Tracking Plug-Ins for Enterprise Subscribers on JUNOS Routing Platforms
9. Using NICs with the VTA

Configuring a Database to Store Account and Session Data

The VTA requires a relational database to store accounts and session data. For information about databases that we have tested for use with the VTA, see the SDX Application Library Release Notes.

To configure a database:

1. For each VTA, create a database that uses the schema for the VTA.

To view the database schemas, see the following file, which is created when you install the Solaris package for the VTA.

• /opt/UMC/conf/vta/quota/vtadata.sql

2. Configure access to the database for an administrator by using the VTA to monitor and manage subscribers.

The access parameters that you configure must match the access parameters that you configure for the data sources created in the J2EE application server (see Configuring the J2EE Application Server).

Configuring the J2EE Application Server

Before configuring the J2EE application server, install the JDBC driver that allows your database to connect to the J2EE application server, and restart the J2EE application server. See the documentation for the database to determine the required JDBC driver. For example, for JBoss, copy the driver to /opt/UMC/jboss/server/default/lib.

NOTE: If you use JBoss, the VTA configuration script configures the J2EE application server, and you do not need to complete these tasks.

To configure the J2EE application server to support the VTA:

1. For each VTA, create a data source with a Java Naming and Directory Interface (JNDI) name that matches the name of the data source (see Table 33 for the default names).

The load script copies default data-source deployment descriptors. These descriptors are appropriate for an environment in which you use JBoss with the MySQL database and have both of these applications running on the same host. The descriptor files begin with mysql-. For more information about these files, see the documentation for the version of JBoss included with the SDX software.

To modify the names of the VTA deployment descriptors, see Creating Deployment Descriptors.

2. Set up a Java Message Service (JMS) connection factory, and link it to the resource environment reference jms/QueueConnectionFactory.

The way you link the JMS connection factory to the resource environment reference depends on the J2EE application server. See the documentation for the J2EE application.

3. For each VTA, create a JMS queue for the ConnectionFactory class with the appropriate name for the VTA (see Table 33).
4. Create a role called VTA-Admin, and configure the administrator profiles so that administrators can access the VTA administration portal with this role.
5. Specify an authentication mechanism, and access parameters (such as a username and password) by which administrators can access the data source through the portals.

The access parameters that you configure must match the access parameters that you configure for the database (see Configuring a Database to Store Account and Session Data).

 Table 33:  Names for Data Sources and JMS Queues 

 Type of VTA
 Default Name for Data Sources
 Name for JMS Queue

 Quota

 Quota/MySQLS

 queue/Quota/SAEEventQueue


 Threshold

 Threshold/MySQLS

 queue/Threshold/SAEEventQueue



 

Creating Deployment Descriptors

The enterprise archives (EAR files) for a VTA contain several modules that require deployment descriptors for the J2EE application server. In these EAR files are sample deployment descriptors for several J2EE application servers. See the Release Notes for information about the J2EE servers that we have tested with the VTA.

To determine the names of the files that contain the descriptors and how to edit them, see the documentation for your J2EE application server.

To deploy the VTA in a J2EE application server that we have not tested, you may need to develop your own deployment descriptors. In this case, you may be able to use the samples we provide as a guide.

To create a deployment descriptor:

1. Create a folder for the VTA on a host.

mkdir vta

2. Copy the EAR file for the VTA from the webapp folder on the application library CD to the folder that you created in Step 1. For example:

cp /cdrom/cdrom0/webapp/quotavta.ear vta

3. From the EAR file, extract the following files into the folder you created in
   Step 1:

• vtacore.jar
• datamgr.jar
• quotadp.jar

For example:

cd vta

jar xvf quotavta.ear datamgr.jar

4. For each JAR file you extracted, extract the file that defines the deployment descriptors for the J2EE application server. For example, for JBoss:

jar xvf datamgr.jar META-INF/jboss.xml

5. Edit the file that defines the deployment descriptors for the J2EE application server.
6. Replace in the JAR file the file that defines the deployment descriptors for the J2EE application server. For example:

jar uvf datamgr.jar META-INF/jboss.xml

7. Replace the JAR file in the EAR file. For example:

jar uvf quotavta.ear datamgr.jar

Troubleshooting Database Deadlocks

The JBoss application server logs the following error when the database reports a deadlock—a condition in which the database operation cannot continue because two processes are both waiting for the other process to be completed before they proceed.

java.sql.SQLException: General error, message from server: "Deadlock found when 
trying to get lock; Try restarting transaction

Deadlocks can occur for a variety of reasons in normal database operation. The VTA resolves deadlocks in the database, and you should ignore this message.

Configuring VTA Services and Policies

You do not need to complete the tasks in this section if you used the VTA configuration script to load the sample data. The sample data includes services for the VTA and policies for the services, and it configures the services to generate tracking events.

Only the VTA should activate and deactivate services that the VTA controls, and you must ensure that these services are not visible on a portal for subscribers to control manually. You can use other services with a VTA if you design the policies and priorities for those services to work together.

For example, if you manage subscribers with a VTA, you can allow subscribers to manually activate a service that overrides the quota service, and consequently prevents charges in the periodic and bought accounts. You would account for use of this service through RADIUS rather than a VTA, and subscribers would incur an extra cost for using the service. In this case, you configure the overriding service with a higher precedence than the quota service.

To configure services for the VTA:

1. Create value-added services for which a VTA monitors and manages usage.
2. Configure policies that specify ingress and egress accounting rules consistent with the usage formula.

For information about configuring accounting rules for a policy, see SDX Services and Policies Guide, Chapter 3, Policy Management Overview.

Configuring Subscribers and Subscriptions to VTA Services

You need to add retailers and subscribers to the directory. If you are using the VTA for testing or demonstration purposes, you can use the retailers and subscribers that are provided in the sample data. (For information about loading sample data, see Installing the VTA and Running the VTA Configuration Script.) If you do not load the sample data, you need to create at least one shared subscriber.

1. Add a retailer and at least one shared subscriber.

See SDX Subscribers and Subscriptions Guide, Chapter 8, Configuring Subscribers and Subscriptions.

2. For all subscribers managed by the VTA, create an individual or a group subscription to value-added services for which a VTA monitors and manages usage.

See SDX Subscribers and Subscriptions Guide, Chapter 8, Configuring Subscribers and Subscriptions.

3. For the value-added service, configure the subscriptions to automatically activate the service when the subscribers log in.

Accessing the J2EE Application Server's Client Libraries

If you use JBoss on the host, the script /opt/UMC/conf/vta/load copies the JBoss client libraries to the SAE installation directory, and you do not need to complete these tasks.

Each SAE that interacts with the VTA requires access to the J2EE application server's client libraries. To provide this access:

1. Refer to the documentation for the J2EE application server to determine the locations and names of the files for the client libraries.

When you install the VTA, the files for the JBoss client libraries are placed in the folder /opt/UMC/conf/vta/jboss-client.

2. Copy the files for the libraries to the folder opt/UMC/sae/lib on each host that supports an SAE. For example:

cp /opt/UMC/conf/vta/jboss-client/*.jar /opt/UMC/sae/lib

3. Restart the SAE on each host to which you copied the client libraries.

Specifying How the VTA Loads Configurations from the Directory

Bootstrap properties specify how the VTA loads configurations from the directory. If you install the directory on a different host than the J2EE application server, you must modify the bootstrap properties to specify the directory host.

NOTE: The examples in these steps are for the Quota VTA. The procedure for the Threshold VTA is identical; however, the EAR filename is thresholdvta.ear.

To configure the bootstrap properties for each VTA:

1. Create a folder for the VTA on a host.

mkdir vta

2. Copy the EAR file for the VTA from the webapp folder on the application library CD to the folder that you created in Step 1.

cp /cdrom/cdrom0/webapp/quotavta.ear vta

3. From the EAR file, extract the file vtacore.jar into the folder you created in
   Step 1.

cd vta

jar xvf quotavta.ear vtacore.jar

4. From the file vtacore.jar, extract the file META-INF/ejb-jar.xml.

jar xvf vtacore.jar META-INF/ejb-jar.xml

5. In the folder that you created in Step 1, edit the META-INF/ejb-jar.xml file.

See Properties in ejb-jar.xml file for information about the properties in this file.

6. Replace the file META-INF/ejb-jar.xml in the file vtacore.jar.

jar uvf vtacore.jar META-INF/ejb-jar.xml

7. Replace the file vtacore.jar in the EAR file.

jar uvf quotavta.ear vtacore.jar

Properties in ejb-jar.xml file

This section describes the properties in the ejb-jar.xml file.

Config.java.naming.provider.url, Config.java.naming.security.principal, Config.java.naming.security.credentials, Config.java.naming.security.protocol

• Standard JNDI properties.
• Value—See SDX Getting Started Guide, Chapter 14, Distributing Directory Changes to SDX Components.

Config.net.juniper.smgt.lib.config.staticConfigDN

• Root of the static configuration properties for the VTA.
• Value—DN
• Default—I=VTA, ou=staticConfiguration, ou=Configuration, o=Management, o=umc

Config.net.juniper.smgt.lib.config.dynamicConfigDN

• Root of the dynamic configuration properties for the VTA.
• Value—DN
• Default—ou=dynamicConfiguration, ou=Configuration, o=Management, o=umc

Config.net.juniper.smgt.des.<propertySuffix>

• Defines how the VTA monitors values that it reads from the directory.
• Value—See SDX Getting Started Guide, Chapter 14, Distributing Directory Changes to SDX Components.

vta.namespace

• Root namespace of the VTA.
• Value—Path, relative to the root of the static configuration properties, that defines where the VTA's configuration is stored
• Example—/Applications/Quota

Configuring the SAE to Send Tracking Events to the VTA

The VTA communicates with the SAE through the EJB adapter plug-in. This plug-in is an SAE plug-in and performs the following functions:

• Filters SAE plug-in events for the VTA.
• Adapts internal SAE events to EJB-compatible methods.
• Sends SAE tracking plug-in events to the VTA.

To use SDX Configuration Editor to configure the EJB adapter plug-in:

1. In the navigation pane, open the SAE configuration file (the default file is POP-ID.xml).
2. Click the Plug-Ins tab.
3. Scroll to the EJB Adapter configuration.
4. Edit or accept the default values for the fields.

See EJB Adapter Plug-In Fields.

5. Select File > Save, and then select SDX System Configuration > Export to LDAP Directory.

EJB Adapter Plug-In Fields

In SDX Configuration Editor, you can edit the following fields in the EJB Adapter section of the Plug-Ins pane in an SAE configuration file.

JNDI Service Provider

• Class name of the J2EE application server's JNDI service provider.
• Value—Depends on the type of J2EE application server; consult documentation for the J2EE application server
• Default—org.jnp.interfaces.NamingContextFactory (class name for JBoss application servers)
• Property name—Plugin.quotavta.java.naming.factory.initial

Application Server URL

• URL of J2EE application server that is running JNDI service.
• Value—Depends on the type of J2EE application server; consult documentation for the J2EE application server
• Default—jnp://10.227.6.242:1099 (URL for JBoss application servers)
• Property name—Plugin.<plugInName>.java.naming.provider.url

JNDI Name of SAE Event Listener

• JNDI name of the SAEEventListener EJB of the peer VTA.
• Value—JNDI name
• Default—No value
• Example—Quota/SAEEventListenerBean
• Property name—Plugin.<plugInName>.ejbJNDIName

Event Admitter

• LDAP filter that determines the subscriber and service events that the EJB adapter plug-in sends to the VTA.
• Value—Filter string that contains an LDAP query. Table 34 lists the values that you can use for LDAP filter strings.

 Table 34:  Settings for Filter Strings

 Filter String
 Action

 ()

 Matches no objects


 (*)

 Matches all objects


 List of <attribute>= <value> pairs
 <attribute>—Name of a property or attribute <ldapAttributeName>
 <value>—One of the following:

  
 * (asterisk)
  
 Explicit string
  
 String that contains an *

 Note: To define a special character (* & , ! | \ ) in a string, precede it with the backslash symbol (\).


  
 If <value> is *, checks for any value.
  
 If <value> is an explicit string, checks whether any value of the property matches the string, regardless of case.
  
 If <value> is a string that contains a *, checks whether any value of the property contains the string, regardless of case.



 (&<filter><filter>...)

 True if all filters match 


 (|<filter><filter>...)

 True if at least one filter matches


 (!<filter>)

 True if the filter does not match 



 

The variables in the filter include the names of plug-in attributes and a PluginEventType variable. The value of this variable is the name of the type of event, such as PE_START_SERVICE. For names of plug-in attributes and plug-in event types, see the SAE CORBA plug-in documentation in the SDX software distribution at SDK/doc/idl/sae/html/index.html on the Juniper Networks Web site at

http://www.juniper.net/techpubs/software/management/sdx/api-index.html

• Guidelines—If you specify plug-in attributes in this field, you must include the same attributes in the Plugin Attributes field.
• Default—No value
• Example—(|(&(PluginEventType=PE_*_SERVICE)(PA_SERVICE_NAME=QuotaInternet))(&(PluginEventType=PE_*_SERVICE)(PA_SERVICE_NAME=QuotaLocal)))
• Property name—Plugin.<plugInName>.admitter

Plugin Attributes

• Plug-in attributes that the EJB adapter plug-in sends to the VTA listener.
• Value—Comma-separated list of plug-in attributes
• Guidelines—Specify at least the plug-in attributes in the example below. You may need to add attributes if you use them for the event admitter. If you do not define a list of attributes, the EJB adapter plug-in sends all plug-in attributes to the VTA. Sending unnecessary plug-in attributes can adversely affect the performance of SDX components.
• Default—No value
• Example—PA_ROUTER_NAME, PA_SESSION_ID, PA_LOGIN_NAME, PA_USER_IP_ADDRESS, PA_SSP_HOST, PA_DOMAIN, PA_SERVICE_NAME, PA_EVENT_TIME, PA_SESSION_TIME, PA_IN_OCTETS, PA_OUT_OCTETS, PA_IN_PACKETS, PA_OUT_PACKETS, PA_SESSION_TIMEOUT, PA_DOWNSTREAM_BANDWIDTH, PA_UPSTREAM_BANDWIDTH, PA_SERVICE_SESSION_NAME, PA_SUBSCRIPTION_NAME
• Property name—Plugin.<plugInName>.attr

Use EJB Cluster

• Specifies whether or not the J2EE application server uses load balancing to determine the location that manages requests to the VTA.
• Value

• Yes (True)—Use load balancing.
• No (False)—Do not use load balancing.

• Default—No
• Property name—Plugin.<plugInName>.enableClustering

EJB Clustering Strategy

• Load-balancing scheme of the J2EE application server that hosts the VTA. See the documentation for the J2EE application server to determine which load-balancing scheme it supports.
• Value—One of the following:

• load balancing via object stubs
• load balancing via home interface
• load balancing via JNDI

• Guidelines—JBoss uses load balancing via object stubs
• Default—load balancing via object stubs
• Property name—Plugin.<plugInName>.clusterStrategy

Specifying Tracking Plug-Ins for Enterprise Subscribers on JUNOS Routing Platforms

When user-tracking plug-ins are attached to the retailer on JUNOS routing platforms, login names are needed to trigger the user-tracking plug-in and generate user-tracking events. Because enterprise subscribers do not have a login name, the VTA cannot get the required user-tracking events.

To allow enterprise subscribers on JUNOS routing platforms to use retailer-attached user-tracking plug-ins, configure the EJB adapter plug-in to filter SAE plug-in events for the VTA and send SAE tracking events to the VTA.

To use the EJB adapter plug-in to send events for a specific retailer:

1. Configure the Event Admitter property of the EJB adapter plug-in (see Configuring the SAE to Send Tracking Events to the VTA).

Specify the PA_USER_DN event attribute with the retailer's relative distinguished name (RDN). For example, the following event admitter matches events from subscribers in the SP-Quota retailer:

PA_USER_DN=*SP-Quota*

2. Configure the EJB adapter plug-in as the global user-tracking plug-in for the SAE. To do so:

1. In the SDX Configuration Editor navigation pane, open the file for the SAE configuration (the default file is POP-ID.xml).
2. Click the Plug-Ins tab.
3. In the Plug-In Event Publishers section, enter the name of the EJB adapter plug-in created in Step 1 in the Global User Tracking Plug-ins field.

Using NICs with the VTA

You can use NIC proxies if the VTA software needs to locate the SAE that manages a particular subscriber. For example, if the VTA receives an account update event and determines that it needs to reconfigure the corresponding SAE session, the VTA must find the SAE that is managing the session. The VTA can do this through the NIC.

You can also use the NIC with the VTA to allow the following:

• Automatically log in subscribers to the VTA Web portals—The NIC maps the subscriber's IP address to the subscriber's login name, DN, or name of the interface and VR to which the subscriber connects. This scenario is for subscribers who connect to the SDX network through a JUNOSe router.
• Immediately activate subscriptions to quota services—The VTA immediately activates a subscriber's quota service when a deposit is made to the subscriber's account. In this case, the NIC maps the subscriber's identifier to the SAE reference. This scenario is for subscribers who connect to the network through JUNOSe routers or JUNOS routing platforms.

If you do not set up a NIC for this purpose or you use an identifier that the NIC cannot map to an SAE reference, subscribers must log out and log in again before the VTA can activate their quota services when deposits are made to their accounts.

• Allow subscribers to log in with their IP addresses. The NIC maps the subscriber's IP address to the identifier that you use for subscribers in the VTA database. To use the sample VTA portals, you must implement this type of NIC. If you do not implement this NIC, you can provide another way for subscribers to log in, such as a central Web page on which subscribers can enter their usernames and passwords. This scenario is for subscribers who connect to the SDX network through a JUNOSe router.

Configuring a NIC

For demonstrations and installations with few subscribers, you can configure the VTA to use a NIC proxy stub, which explicitly defines a set of data mappings. However, for standard installation with a significant number of subscribers and multiple SAEs, you must set up a full NIC configuration.

To configure a NIC for the VTA management portals:

1. Install NIC Configuration Sample from the sample data from the SDX software distribution.

This action creates OnePopLogin under the NIC entry in the LDAP schema.

2. Plan and configure your NIC hosts (see SDX Network Guide: SAE, Juniper Networks Routers, and NIC, Chapter 5, Locating Subscriber Information).
3. On each workstation that supports a NIC host for this NIC configuration, configure the object request broker (ORB) to recognize the Common Object Services (COS) name server. For JacORB, include the following line in the file jacorb.properties.

ORBInitRef.NameService=corbaloc::<host>:<port>/NameService

• <host> is the name or IP address of the COS name server
• <port> is the TCP port

4. Add the NIC SAE agents to each SAE configuration as external plug-ins, as follows:

Plugin.nic.objectref=corbaname::<host>:<port>/NameService#nicsae/saePort 

Plugin.nic.attr=PA_ROUTER_NAME,PA_SESSION_ID,PA_USER_TYPE,\ 

PA_LOGIN_NAME,PA_USER_IP_ADDRESS

• <host> is the name or IP address of the COS name server
• <port> is the TCP port

For information about configuring SAE plug-ins, see SDX Subscribers and Subscriptions Guide, Chapter 6, How to Configure SAE Plug-Ins.

• (Optional) Configure a NIC proxy stub. See SDX Network Guide: SAE, Juniper Networks Routers, and NIC, Chapter 7, Configuring Applications to Communicate with an SAE for information about configuring the NIC proxy stub.

5. Configure a NIC proxy for the VTA. See Configuring NIC Proxies for the VTA.

Configuring NIC Proxies for the VTA

To configure NIC proxies:

1. In the SDX Configuration Editor navigation pane, expand the NIC proxy folder in the VTA folder.
2. Select the NIC proxy that you want to configure.

• If subscribers connect to the network through a JUNOSe router, you can configure a NIC proxy that passes the subscriber's IP address and receives the identifier that you configured for the subscriber (see Using NICs with the VTA). This NIC allows customers to log in through the Web portals (see Chapter 19, Managing Subscriber Accounts with VTA Portals).

You must also specify the namespace of the NIC proxy in the CONSTANTS.incl file of the Web applications for the VTA portals (see Properties for VTA Portals).

• You can configure a NIC proxy that passes the subscriber's identifier to a NIC resolver and receives the corresponding SAE reference. This NIC allows the VTA to immediately activate a subscriber's quota service when a deposit is made to the subscriber's account (see Immediate Activation of Subscriptions to Quota Service on page 13). This feature is available for subscribers who connect to the network through JUNOSe routers or JUNOS routing platforms.

3. Hold down the right mouse button, and select Open With > SDX Configuration Editor.

For information about the parameters that you can configure for NIC proxies, see SDX Network Guide: SAE, Juniper Networks Routers, and NIC, Chapter 7, Configuring Applications to Communicate with an SAE.