Chapter 2 Getting Started Using Diameter

The Diameter stack configuration is provided through the Diameter service element in the Sun GlassFish^TM Communications Server domain.xml file. The Admin Console and asadmin Diameter commands can be used to administer the various configuration parameters in the Diameter service.

This chapter describes how to configure and get started with Diameter. The following topics are addressed:

• About Diameter in the Communications Server Environment

• Configuring Diameter for Communications Server

• Using the Diameter Commands

About Diameter in the Communications Server Environment

The Diameter service consists of connection information for an individual Diameter peer. A peer configuration contains details of a listener, peers, and a set of one or more Diameter applications.

A Diameter listener is a local Diameter peer which defines details such as the following:

• Vendor ID

• Product name

• Firmware version

• Mode, such as, client, server, relay, or proxy

• Address/port/transport of the local peer (bindto)

• Flag indicating if unknown peer connections will be accepted or not (accept-unknown-peer)

• Time interval for retrying peer connections (tctimer)

• Realm name used by the local peer

A peer configuration can also include a list of known peers. Each peer points to the application, including the host/port/transport of the peer, and also to the realm. A peer configuration includes a list of Diameter applications to run.

Applications can be either authentication or accounting applications supported by a particular vendor.

Other configurables of the Diameter service are max-threads, which denotes the maximum number of threads in a Grizzly pool configuration, msg-buffer-size, which indicates the size of the byte buffers in the pool used to store and parse incoming messages, and enable-msg-persistence for enabling and disabling message persistence.

Diameter Tools

After installing Diameter Adapter 1.0, you must configure Diameter for Sun GlassFish Communications Server before you can use the Diameter tools.

The following topics are addressed here:

• Admin Console

• Command-line Interface

• Code Generation Tool

Admin Console

The Communications Server Admin Console is a browser-based utility that features a graphical interface for performing administrative tasks. The format for starting the Administration Console in a web browser is http://hostname:port. For example:

http://localhost:4848

After you create the Diameter service, the Diameter node appears in the Admin Console. You can then use the Admin Console pages to perform Diameter administrative tasks. Navigate to the Diameter pages as follows: Configurations->config-name->Diameter Service. You can display the help text for a page in the Admin Console by clicking the Help button on the page.

Command-line Interface

Alternatively, you can use the asadmin commands to configure and administer the Diameter service from the command line. You can run the asadmin commands either from a command prompt or from a script. The format for starting the asadmin utility on the command line is as-install/bin/asadmin command --option. A multimode example:

asadmin> monitor --type httplistener

For a list of all the asadmin commands for Diameter, see Appendix A, Diameter Commands for the asadmin Utility.

You can display help information for a command by typing help followed by the command. For example:

asadmin> help create-diameter-application

For a collection of the help pages for all Communications Server asadmin commands, see Sun GlassFish Communications Server 2.0 Reference Manual.

Code Generation Tool

The Diameter Adapter provides a tool for developers to add or edit attribute value pairs (AVPs) that are available in the current API. The tool can be used to generate Enums, grouped AVP interfaces, implementation classes, and factory methods to simplify application code development. For information and instructions on using this tool, see Chapter 3, Generating Diameter Code for Communications Server.

Configuring Diameter for Communications Server

After installation, you are ready to configure the Diameter service. This section provides instructions for configuring the Diameter service by using the Communications Server asadmin Diameter commands.

The following topics are addressed here:

• To Configure the Initial Diameter Service

• To Create a Diameter Resource

To Configure the Initial Diameter Service

To create the Diameter service, you must use the command line. If you do not specify the target operand, the default instance is used. If the task applies to a cluster, target must specify the cluster name.

After you create the Diameter service by using the create-diameter-service command, the Diameter node appears in the Communications Server Admin Console.

Before You Begin

The Diameter Adapter must be installed before Diameter can be configured.

1. Create the Diameter service by using the create-diameter-service(1) command.

   asadmin> create-diameter-service target-name

   Default target-name is server.

2. Repeat Step 1 for each additional configuration.

   This is a one-time task per configuration.

3. Create a Diameter application by using the create-diameter-application(1) command.

   For additional usage information, see To Create a Diameter Application.

4. Create a Diameter peer by using the create-diameter-peer(1) command.

   For additional usage information, see To Create a Diameter Peer.

5. Restart the server for changes to take effect.

   Use the stop-domain(1) and start-domain(1) commands.

To Create a Diameter Resource

After configuring the initial Diameter service, you are ready to create a Diameter resource. This section provides instructions for creating a resource for Diameter by using the Communications Server Admin Console.

If you want to work from the command line, you can use the create-admin-object(1) command. Be sure to set the required properties as described in this procedure. For an example command, see Example 2–1.

Before You Begin

The Diameter service, a Diameter application, and a Diameter peer must be created before a Diameter resource can be created.

1. Open the Admin Console.

2. Navigate to Resources->Connectors->Admin Object Resource.

3. Click New.

4. Select the sundiameter resource adapter.

5. Select one of the following connection definitions:

   • For Sh Application

     com.sun.diameter.application.sh.api.UserProfileServer

   • For Online Charging Application

     com.sun.diameter.application.credit.ro.api.RoChargingFactory

   • For Offline Charging Application

     com.sun.diameter.application.credit.rf.api.RfChargingFactory

6. Enter a JNDI name of your choice and click Next.

   The Additional Properties section displays the following Diameter peer properties:

   • PeerId — The ID of the peer

   • Host — Host name or IP address of the peer

   • Port — Port number of the peer

   • Realm — Peer realm

   • SecondaryPeerId — ID of peer to be used when the primary peer is not available

7. Set PeerId or Host-Port-Realm (others are optional).

   The Host-Port-Realm combination is used to identify unknown peers that are accepted by the Diameter stack.

8. Configure the PeerId property.

   Specify the peer ID used when creating the peer, such as PeerId: peer_1

9. Click Finish.

Example 2–1 Creating a Diameter Resource on the Command Line

This example creates a Diameter administered object with JNDI name rf_so.

asadmin> create-admin-object --raname sundiameter --target server 
--property PeerId=charging-peer --restype com.sun.diameter.application.credit.
rf.api.RfChargingFactory diameter/rf_ao 
Command create-admin-object executed successfully.

Using the Diameter Commands

This section provides instructions for using the Diameter asadmin commands. The following topics are addressed:

• Administering the Diameter Service

• Administering Diameter Applications

• Administering Diameter Peers

These tasks can also be accomplished by using the Admin Console, with the exception of creating or deleting the Diameter service which can only be done on the command line. Instructions for using the Admin Console are provided in the online help.

Administering the Diameter Service

The Diameter service itself can only be administered on the command line. You cannot create or delete the Diameter service by using the Admin Console. However, all the other Diameter tasks can be performed either on the command line or in the Admin Console.

The following topics are addressed here:

• To Create the Diameter Service

• To Delete the Diameter Service

To Create the Diameter Service

Use the create-diameter-service command in remote mode to create the Diameter service on an instance or cluster. The default Diameter stack configuration is applied. If you do not specify the target operand, the default instance is used. If the task applies to a cluster, target must specify the cluster name.

The Diameter service can only be created from the command line. After you create the Diameter service by using the create-diameter-service command, the Diameter node appears in the Communications Server Admin Console. Then you can use the Admin Console for other Diameter tasks if you prefer.

Before You Begin

The Diameter Adapter must be installed before the Diameter service can be created.

1. Ensure that the server is running.

   Remote commands require a running server.

2. Create the Diameter service by using the create-diameter-service(1) command.

Example 2–2 Creating the Diameter Service on a Server Instance

This example creates the Diameter service on the default instance.

asadmin> create-diameter-service
Command create-diameter-service executed successfully.

See Also

You can also view the full syntax and options of the command by typing asadmin help create-diameter-service at the command line.

To Delete the Diameter Service

Use the delete-diameter-service command in remote mode to delete the Diameter service configuration on a cluster or server instance. The Diameter service can only be deleted from the command line. This command disables the Diameter service and removes the Diameter node in the Admin Console until you recreate the Diameter service. As child elements of the Diameter service, all Diameter configuration elements will be deleted.

If you do not specify the --target option, the default instance is used. If the task applies to a cluster, the --target option must specify the cluster name.

1. Ensure that the server is running.

   Remote commands require a running server.

2. Delete the Diameter service by using the delete-diameter-service(1) command.

Example 2–3 Deleting the Diameter Service

This example disables the Diameter service on the default instance.

asadmin> delete-diameter-service
Command delete-diameter-service executed successfully.

See Also

You can also view the full syntax and options of the command by typing asadmin help delete-diameter-service at the command line.

Administering Diameter Applications

The following topics are addressed here:

• To Create a Diameter Application

• To Delete a Diameter Application

• To Delete a Diameter Application Set

• To Delete Diameter Accounting Application

• To Delete a Diameter Authentication Application

• To List Vendors for a Diameter Application Set

• To List Diameter Applications

To Create a Diameter Application

Use the create-diameter-application command in remote mode to create a vendor-specific Diameter application. If you do not specify the --target option, the default instance is used. If the task applies to a cluster, the --target option must specify the cluster name.

Before You Begin

The Diameter service must be created before a Diameter application can be created.

1. Ensure that the server is running.

   Remote commands require a running server.

2. Create a Diameter application by using the create-diameter-application(1) command.

   Information about the options and properties of the command is included in this help page.

Example 2–4 Creating a Diameter Application

This example creates a vendor-specific Diameter accounting application that is added to the application set referenced by the ID apps_1. The vendor ID of this application is 10415.

asadmin> create-diameter-application --applicationsid apps_1 --acctappid 300 10415
Command create-diameter-application executed successfully.

See Also

You can also view the full syntax and options of the command by typing asadmin help create-diameter-application at the command line.

To Delete a Diameter Application

Use the delete-diameter-application command in remote mode to remove a Diameter application for a specific vendor. If you do not specify the --target option, the default instance is used. If the task applies to a cluster, the --target option must specify the cluster name.

1. Ensure that the server is running.

   Remote commands require a running server.

2. List the Diameter applications in a by using the list-diameter-applications(1) command.

3. Delete a Diameter application by using the delete-diameter-application(1) command.

Example 2–5 Deleting a Diameter Application

asadmin> delete-diameter-application --applicationsid apps_2 2000
Command delete-diameter-application executed successfully.

See Also

You can also view the full syntax and options of the command by typing asadmin help delete-diameter-application at the command line.

To Delete a Diameter Application Set

An application set is a place holder that is used to group a set of applications that have different vendor IDs. This helps peers to refer to applications easily. Use the delete-diameter-applications command in remote mode to remove a Diameter application set. If you do not specify the --target option, the default instance is used. If the task applies to a cluster, the --target option must specify the cluster name.

1. Ensure that the server is running.

   Remote commands require a running server.

2. Delete a Diameter application set by using the delete-diameter-applications(1) command.

Example 2–6 Deleting a Diameter Application Set

This examples deletes the application set named apps_2.

asadmin> delete-diameter-applications apps_2
Command delete-diameter-applications executed successfully.

See Also

You can also view the full syntax and options of the command by typing asadmin help delete-diameter-applications at the command line.

To Delete Diameter Accounting Application

Use the delete-diameter-acctapp command in remote mode to delete a Diameter accounting application. If you do not specify the --target option, the default instance is used. If the task applies to a cluster, the --target option must specify the cluster name.

1. Ensure that the server is running.

   Remote commands require a running server.

2. Delete a Diameter accounting application by using the delete-diameter-acctapp(1) command.

3. Restart the server for changes to take effect.

   Use the stop-domain(1) and start-domain(1) commands.

Example 2–7 Deleting a Diameter Accounting Application

This example deletes the accounting application 300.

asadmin> delete-diameter-acctapp --applicationsid apps_1 --vendorid 10415 300
Command delete-diameter-acctapp executed successfully

See Also

You can also view the full syntax and options of the command by typing asadmin help delete-diameter-acctapp at the command line.

To Delete a Diameter Authentication Application

Use the delete-diameter-authapp command in remote mode to delete a Diameter authentication application. If you do not specify the --target option, the default instance is used. If the task applies to a cluster, the --target option must specify the cluster name.

1. Ensure that the server is running.

   Remote commands require a running server.

2. Delete a Diameter authentication application by using the delete-diameter-authapp(1) command.

3. Restart the server for changes to take effect.

   Use the stop-domain(1) and start-domain(1) commands.

Example 2–8 Deleting an Authentication Application

This example deletes authentication application 200.

asadmin> delete-diameter-authapp --applicationsid apps_1 --vendorid 10415 200
Command delete-diameter-authapp executed successfully.

See Also

You can also view the full syntax and options of the command by typing asadmin help delete-diameter-authapp at the command line.

To List Vendors for a Diameter Application Set

Use the list-diameter-application command in remote mode to list the vendor IDs for a specific Diameter application set. If you do not specify the --target option, the default instance is used. If the task applies to a cluster, the --target option must specify the cluster name.

1. Ensure that the server is running.

   Remote commands require a running server.

2. List vendor IDs for a Diameter application set by using the list-diameter-application(1) command.

Example 2–9 Listing Vendor IDs for a Diameter Application Set

This example lists the vendor IDs for application set apps_1.

asadmin> list-diameter-application apps_1
10415
Command create-diameter-service executed successfully.

See Also

You can also view the full syntax and options of the command by typing asadmin help list-diameter-application at the command line.

To List Diameter Applications

Use the list-diameter-applications command in remote mode to list the Diameter applications in a specific cluster or server instance. If you do not specify the --target option, the default instance is used. If the task applies to a cluster, the --target option must specify the cluster name.

1. Ensure that the server is running.

   Remote commands require a running server.

2. List the Diameter applications in a particular server or cluster by using the list-diameter-applications(1) command.

Example 2–10 Listing Diameter Applications

This example list the Diameter applications on the default instance.

asadmin> list-diameter-applications
apps_1
Command list-diameter-applications executed successfully.

See Also

You can also view the full syntax and options of the command by typing asadmin help list-diameter-applications at the command line.

Administering Diameter Peers

The following topics are addressed here:

• To Create a Diameter Peer

• To Update a Diameter Peer

• To Delete a Diameter Peer

• To List Diameter Peers

To Create a Diameter Peer

Use the create-diameter-peer command in remote mode to add peer host information to the known peer list in the specified cluster or server instance. If you do not specify the --target option, the default instance is used. If the task applies to a cluster, the --target option must specify the cluster name.

Before You Begin

A Diameter application must be created before a Diameter peer can be created.

1. Ensure that the server is running.

   Remote commands require a running server.

2. Add peer host information to the Diameter peer list by using the create-diameter-peer(1) command.

   Information about the options and properties of the command is included in this help page.

Example 2–11 Adding Peer Information to a Diameter Application Set

This example creates a peer named peer_1 on the default instance.

asadmin> create-diameter-peer --applicationsref apps_1 --realm Sun.com --peerhost nyx
--peerport 3878 --transport tls peer_1
Command create-diameter-peer executed successfully.

See Also

You can also view the full syntax and options of the command by typing asadmin help create-diameter-peer at the command line.

To Update a Diameter Peer

Use the set command to update an existing Diameter peer.

1. List Diameter peers by using the list-diameter-peers(1) command.

2. Update a Diameter peer by using the set(1) command.

   This example changes the listening port of the peer with ID p1.

   asadmin> set server-config.diameter-service.peer-configuration.peers.peer.p1.port=3737 server-config.diameter-service.peer-configuration.peers.peer.p1.port = 3737

   where p1 is the peer ID which can be changed.

3. Restart the server for changes to take effect.

   Use the stop-domain(1) and start-domain(1) commands.

To Delete a Diameter Peer

Use the delete-diameter-peer command in remote mode to remove a peer in the Diameter service from the specified cluster or server instance. If you do not specify the --target option, the default instance is used. If the task applies to a cluster, the --target option must specify the cluster name.

1. Ensure that the server is running.

   Remote commands require a running server.

2. List Diameter peers by using the list-diameter-peers(1) command.

3. Delete a Diameter peer by using the delete-diameter-peer(1) command.

Example 2–12 Deleting a Diameter Peer

This example deletes peer_1 from the default instance.

asadmin> delete-diameter-peer peer_1
Command delete-diameter-service executed successfully.

See Also

You can also view the full syntax and options of the command by typing asadmin help delete-diameter-peer at the command line.

To List Diameter Peers

Use the list-diameter-peers command in remote mode to list all peers on the specified cluster or server instance. If you do not specify the --target option, the default instance is used. If the task applies to a cluster, the --target option must specify the cluster name.

1. Ensure that the server is running.

   Remote commands require a running server.

2. List Diameter peers by using the list-diameter-peers(1) command.

Example 2–13 Listing Diameter Peers

This example lists the Diameter peers on the default instance.

asadmin> list-diameter-peers
peer_1
Command list-diameter-peers executed successfully.

See Also

You can also view the full syntax and options of the command by typing asadmin help list-diameter-peers at the command line.