Mobicents Diameter Core User Guide
User Manual:
Open the PDF directly: View PDF 
.
Page Count: 60
| Download | |
| Open PDF In Browser | View PDF |
Diameter User Guide
by Bartosz Baranowski and Alexandre Mendonca
Preface ............................................................................................................................. v
1. Document Conventions .......................................................................................... v
1.1. Typographic Conventions ............................................................................ v
1.2. Pull-quote Conventions .............................................................................. vii
1.3. Notes and Warnings .................................................................................. vii
2. Provide feedback to the authors! .......................................................................... viii
1. Introduction to Mobicents Diameter ............................................................................ 1
1.1. Message Format ................................................................................................. 1
1.2. Contents ............................................................................................................ 4
2. Mobicents Diameter Stack ........................................................................................... 5
2.1. Diameter Stack Design ....................................................................................... 5
2.1.1. Diameter Stack Extensibility ...................................................................... 5
2.1.2. Diameter Stack Model .............................................................................. 6
2.1.3. Application Session Factories ................................................................... 7
2.1.4. Session Replication .................................................................................. 8
2.2. Mobicents Diameter Stack Setup ......................................................................... 9
2.2.1. Pre-Install Requirements and Prerequisites ................................................ 9
2.2.2. Source Code ........................................................................................... 9
2.3. Diameter Stack Configuration ............................................................................ 10
2.3.1. Cluster configuration ............................................................................... 19
2.4. Diameter Stack Source overview ....................................................................... 21
2.4.1. Session Factory ..................................................................................... 22
2.4.2. Sessions ................................................................................................ 25
2.4.3. Application Session Factories ................................................................. 27
2.5. Diameter Stack Validator ................................................................................... 29
2.5.1. Validator Configuration ........................................................................... 30
2.5.2. Validator Source Overview ...................................................................... 37
3. Multiplexer (MUX) ...................................................................................................... 39
3.1. Diameter Multiplexer (MUX) Design ................................................................... 39
3.2. Diameter Multiplexer (MUX) Setup ..................................................................... 40
3.2.1. Pre-Install Requirements and Prerequisites .............................................. 40
3.2.2. Source Code .......................................................................................... 41
3.3. Diameter Multiplexer (MUX) Configuration .......................................................... 42
3.4. Diameter MUX Source Overview ....................................................................... 42
3.5. Diameter Multiplexer (MUX) Dictionary ............................................................... 44
A. Revision History .......................................................................................................... 49
Index ............................................................................................................................... 51
iii
iv
Preface
1. Document Conventions
This manual uses several conventions to highlight certain words and phrases and draw attention
to specific pieces of information.
In PDF and paper editions, this manual uses typefaces drawn from the Liberation Fonts [https://
fedorahosted.org/liberation-fonts/] set. The Liberation Fonts set is also used in HTML editions if
the set is installed on your system. If not, alternative but equivalent typefaces are displayed. Note:
Red Hat Enterprise Linux 5 and later includes the Liberation Fonts set by default.
1.1. Typographic Conventions
Four typographic conventions are used to call attention to specific words and phrases. These
conventions, and the circumstances they apply to, are as follows.
Mono-spaced Bold
Used to highlight system input, including shell commands, file names and paths. Also used to
highlight key caps and key-combinations. For example:
To see the contents of the file my_next_bestselling_novel in your current
working directory, enter the cat my_next_bestselling_novel command at the
shell prompt and press Enter to execute the command.
The above includes a file name, a shell command and a key cap, all presented in Mono-spaced
Bold and all distinguishable thanks to context.
Key-combinations can be distinguished from key caps by the hyphen connecting each part of a
key-combination. For example:
Press Enter to execute the command.
Press Ctrl+Alt+F1 to switch to the first virtual terminal. Press Ctrl+Alt+F7 to
return to your X-Windows session.
The first sentence highlights the particular key cap to press. The second highlights two sets of
three key caps, each set pressed simultaneously.
If source code is discussed, class names, methods, functions, variable names and returned values
mentioned within a paragraph will be presented as above, in Mono-spaced Bold. For example:
File-related classes include filesystem for file systems, file for files, and dir
for directories. Each class has its own associated set of permissions.
Proportional Bold
This denotes words or phrases encountered on a system, including application names; dialogue
box text; labelled buttons; check-box and radio button labels; menu titles and sub-menu titles.
For example:
v
Preface
Choose System > Preferences > Mouse from the main menu bar to launch
Mouse Preferences. In the Buttons tab, click the Left-handed mouse check
box and click Close to switch the primary mouse button from the left to the right
(making the mouse suitable for use in the left hand).
To insert a special character into a gedit file, choose Applications >
Accessories > Character Map from the main menu bar. Next, choose Search
> Find from the Character Map menu bar, type the name of the character in the
Search field and click Next. The character you sought will be highlighted in the
Character Table. Double-click this highlighted character to place it in the Text
to copy field and then click the Copy button. Now switch back to your document
and choose Edit > Paste from the gedit menu bar.
The above text includes application names; system-wide menu names and items; applicationspecific menu names; and buttons and text found within a GUI interface, all presented in
Proportional Bold and all distinguishable by context.
Note the > shorthand used to indicate traversal through a menu and its sub-menus. This is to
avoid the difficult-to-follow 'Select Mouse from the Preferences sub-menu in the System menu
of the main menu bar' approach.
Mono-spaced Bold Italic or Proportional Bold Italic
Whether Mono-spaced Bold or Proportional Bold, the addition of Italics indicates replaceable or
variable text. Italics denotes text you do not input literally or displayed text that changes depending
on circumstance. For example:
To connect to a remote machine using ssh, type ssh username@domain.name
at a shell prompt. If the remote machine is example.com and your username on
that machine is john, type ssh john@example.com.
The mount -o remount file-system command remounts the named file
system. For example, to remount the /home file system, the command is mount
-o remount /home.
To see the version of a currently installed package, use the rpm -q package
command. It will return a result as follows: package-version-release.
Note the words in bold italics above username, domain.name, file-system, package, version and
release. Each word is a placeholder, either for text you enter when issuing a command or for text
displayed by the system.
Aside from standard usage for presenting the title of a work, italics denotes the first use of a new
and important term. For example:
When the Apache HTTP Server accepts requests, it dispatches child processes
or threads to handle them. This group of child processes or threads is known as
vi
Pull-quote Conventions
a server-pool. Under Apache HTTP Server 2.0, the responsibility for creating and
maintaining these server-pools has been abstracted to a group of modules called
Multi-Processing Modules (MPMs). Unlike other modules, only one module from
the MPM group can be loaded by the Apache HTTP Server.
1.2. Pull-quote Conventions
Two, commonly multi-line, data types are set off visually from the surrounding text.
Output sent to a terminal is set in Mono-spaced Roman and presented thus:
books
books_tests
Desktop
Desktop1
documentation
downloads
drafts
images
mss
notes
photos
scripts
stuff
svgs
svn
Source-code listings are also set in Mono-spaced Roman but are presented and highlighted as
follows:
package org.jboss.book.jca.ex1;
import javax.naming.InitialContext;
public class ExClient
{
public static void main(String args[])
throws Exception
{
InitialContext iniCtx = new InitialContext();
Object
ref = iniCtx.lookup("EchoBean");
EchoHome
home = (EchoHome) ref;
Echo
echo = home.create();
System.out.println("Created Echo");
System.out.println("Echo.echo('Hello') = " + echo.echo("Hello"));
}
}
1.3. Notes and Warnings
Finally, we use three visual styles to draw attention to information that might otherwise be
overlooked.
vii
Preface
Note
A note is a tip or shortcut or alternative approach to the task at hand. Ignoring a
note should have no negative consequences, but you might miss out on a trick that
makes your life easier.
Important
Important boxes detail things that are easily missed: configuration changes that
only apply to the current session, or services that need restarting before an update
will apply. Ignoring Important boxes won't cause data loss but may cause irritation
and frustration.
Warning
A Warning should not be ignored. Ignoring warnings will most likely cause data
loss.
2. Provide feedback to the authors!
If you find a typographical error in this manual, or if you have thought of a way to make this manual
better, we would love to hear from you! Please submit a report in the the Issue Tracker [http://
code.google.com/p/jdiameter/issues/list], against the product Diameter User Guide, or contact
the authors.
When submitting a bug report, be sure to mention the manual's identifier: User_Guide
If you have a suggestion for improving the documentation, try to be as specific as possible when
describing it. If you have found an error, please include the section number and some of the
surrounding text so we can find it easily.
viii
Chapter 1.
Introduction to Mobicents Diameter
Diameter is a computer networking protocol for Authentication, Authorization and Accounting
(AAA), as defined in RFC3588. It is a successor to RADIUS, and has been designed to overcome
certain RADIUS limitations:
• No transport reliability and flexibility (Diameter uses TCP/SCTP instead of UDP).
• No security within protocol (Diameter supports IPSec (mandatory) and TLS (optional)).
• Limited address space for AVPs (Diameter uses 32-bit address space instead of 8-bit).
• Only stateless mode is possible (Diameter supports both stateful and stateless modes).
• Static peers (Diameter offers dynamic discovery, using DNS, SRV and NAPTR).
• No peer alignment capabilities (Diameter introduces capabilities negotiation).
• No support for transport layer failover. Diameter follows RFC3539 [http://tools.ietf.org/html/
rfc3539], which introduces correct procedures.
• Limited support for roaming (Diameter introduces mechanisms for secure and scalable
roaming).
• No extension possible (Diameter allows extension - new commands and AVPs to be defined).
Diameter offers all of the capabilities of the RADIUS protocol, and is compatible with RADIUS. It
can also define extensions, or "Applications".
Each application may introduce new types of messages, AVP codes, and state machines. The
Message and AVP codes are assigned by the IANA. Each application has its own Application ID
and Vendor ID that is used to distinguish between applications. Application code is used to signal
to other peers which operations are supported by the connecting peer (Capabilities Exchange /
Negotiation).
1.1. Message Format
Diameter is a byte based protocol. Each message has a fixed structure, which consists of two
parts: header and payload.
The message header structure is common for every message. The content is fixed, as is the
length. Message header content includes the code, application and certain bit flags, which helps
identify the message in Diameter scope.
The message payload is built up of AVPs. Its content differs for each command and application,
though they all define the Session-ID AVP as mandatory.
1
Chapter 1. Introduction to Mo...
Figure 1.1. Diameter Message Structure
The header has the following fields:
Message Headers
Version
Indicates the Diameter protocol version. This value is always set to 1.
Message Length
Indicates the Diameter message length, including the header fields.
Flags
Composed by eight bits, to provide information regarding the message. The first four bits in
the flags octet have the following meaning:
• R = The message is a request (1) or an answer (0).
• P = The message is proxiable (1) and may be proxied, relayed or redirected, or it must be
processed locally (0).
• E = The message is an error message (1) or a regular message (0).
• T = The message is potentially being re-transmitted (1) or being sent for the first time (0).
The last four bits are reserved for future use, and should be set to 0.
2
Message Format
Command Code
Indicates the command associated with the message.
Application-ID
Identifies the application to which the message is applicable for. The application is an
authentication, accounting, or vendor specific application. The application-id in the header
must be the same as what is contained in any relevant AVPs in the message.
Hop-by-Hop ID
A unique ID that is used to match requests and answers. The header field of the answer
message must contain the same value present in the corresponding request. This is how
answers are routed back to the peer that sent the message.
End-to-End ID
A time-limited unique ID that is used to to detect duplicate messages. The ID must be unique
for at least four minutes. The answer message originator must ensure that this header contains
the same value present in the corresponding request.
The message payload is built up from AVPs. Each AVP has a similar structure: a header, and
encoded data. Data can be simple (eg, integer, long) or complex (another encoded AVP).
Figure 1.2. Payload Structure
Payload AVPs
AVP Code
Uniquely identifies the attribute, by combining the specified code with the value contained
within the Vendor-ID header field.
AVP numbers 1 to 255 are reserved for RADIUS backwards compatibility, and do not require
the Vendor-ID header field. AVP numbers 256 and above are used exclusively for the
Diameter protocol, and are allocated by IANA.
3
Chapter 1. Introduction to Mo...
Flags
Bit flags that specify how each attribute must be handled. Flags octets have the following
structure: V M P r r r r r.
A full description is available in Section 4.1 of RFC3588 [http://tools.ietf.org/html/
rfc3588#section-4.1].
The first three bits have the following meaning:
V
If set, indicates that optional octets (Vendor-ID) is present in AVP header.
M
If set, it indicates that receiveing peer must understand this AVP or send error answer.
P
If set, it indicates the need for encryption for end-to-end security.
The last 5 bits are reserved for future use, and should be set to 0.
AVP Length
Indicates the number of octets in the AVP, including the following information:
• AVP Code
• AVP Length
• AVP Flags
• Vendor-ID field (if present)
• AVP Data
Vendor-ID
An optional octet that identifies the AVP in application space. AVP code and AVP Vendor-ID
create a unique identifier for the AVP.
1.2. Contents
Mobicents Diameter core is built on top of three basic components:
Stack
Extensible Diameter Stack. It provides basic session support along with application specific
sessions.
Multiplexer (MUX)
Diameter Stack multiplexer. Allows different listeners to share the same stack instance.
Dictionary
Diameter Message and AVP Dictionary. Provides an API to access information about AVPs.
Dictionary is embeded in the MUX.
4
Chapter 2.
Mobicents Diameter Stack
The Diameter Stack is the core component of the presented Diameter solution. It performs all
necessary tasks to allow user interaction with the Diameter network. It manages the state of
diameter peers and allows to route messages between them. For more details, refer to RFC 3588
[http://tools.ietf.org/html/rfc3588].
The Diameter Stack currently supports the following application sessions:
• Base
• Credit Control Application (CCA)
• Sh
• Ro
• Rf
• Cx/Dx
• Gx
• Gq'
• Rx
2.1. Diameter Stack Design
2.1.1. Diameter Stack Extensibility
Diameter Stack has been designed to be extensible. In order to achieve that, two set of APIs
are defined by the stack - one that defines basic contracts between the user application and the
stack, and one that defines contracts allowing the instance to inject custom objects into the stack
to perform certain tasks (for example, SessionFactory). ISessionFactory declares additional
methods that allow the developer to declare custom behaviour (for example, custom application
sessions). Please refer to Section 2.4.1, “Session Factory” for more detailed information.
5
Chapter 2. Mobicents Diameter...
Figure 2.1. Diameter Stack Extensibility Visualization
The general pattern for interface declaration is:
• The interface ComponentInterface declares the minimal set of methods for a component to
perform its task.
• The interface IComponentInterface provides additional behavior methods. Please refer to the
java doc for a list of interfaces and descriptions of method contracts.
2.1.2. Diameter Stack Model
Diameter Stack performs the following tasks:
• Manages connections to remote peers.
• Manages session objects.
• Routes messages on behalf of sessions.
• Receives and delivers messages to assigned listeners (usually a session object).
Sessions use the stack and the services it provides to communicate with remote peers. The
application is the only place that holds references to sessions. It can be seen as follows:
6
Application Session Factories
Figure 2.2. Diameter Application and Stack Model
2.1.3. Application Session Factories
Application session factories perform two tasks:
• server stack as factory for sessions.
• server session objects as holders for session related resources, like state change listener, event
listeners and context.
The figure below shows the relationship between Application Session Factories and User
Applications:
Figure 2.3. Application Session Factory and User Application
7
Chapter 2. Mobicents Diameter...
Note
Session context is a callback interface defined by some sessions.
2.1.4. Session Replication
Diameter Stack supports replication of session data and state. Clustered stack instances can
perform operations on session regardless of physical location. Imagine the logically clustered
stack as follows:
Figure 2.4. Diameter Cluster
8
Mobicents Diameter Stack Setup
Stack only replicates non simple sessions. This is because simple sessions do not hold state and
can be simply recreated by the application. Simple sessions include:
• RawSessions
• Sessions
Diameter Cluster replicates the full state of sessions. However, it does not replicate resources
that are entirely local to the stack instance, like session listeners. Local resource references are
recreated once the session is being prepared to be used in the stack instance. Listeners (state and
events) are fetched from the respective session factory instance. See Section 2.1.3, “Application
Session Factories” for more details.
2.2. Mobicents Diameter Stack Setup
2.2.1. Pre-Install Requirements and Prerequisites
Ensure that the following requirements have been met before continuing with the install.
2.2.1.1. Hardware Requirements
Mobicents Diameter Stack does not have any hardware requirements.
2.2.1.2. Software Prerequisites
Mobicents Diameter Stack has the following software dependencies:
• Pico Container
• slf4j
Clustered setup also requires following:
• JDiameter HA
• JBoss Cache
2.2.2. Source Code
This section provides instructions on how to obtain and build the Mobicents Diameter Stack from
source code.
9
Chapter 2. Mobicents Diameter...
2.2.2.1. Release Source Code Building
1.
Downloading the source code
Important
Subversion is used to manage its source code. Instructions for using
Subversion, including install, can be found at http://svnbook.red-bean.com
Use SVN to checkout a specific release source, the base URL is ?, then add the specific
release version, lets consider 1.6.0.FINAL.
[usr]$ svn co ?/1.6.0.FINAL jdiameter-1.6.0.FINAL
2.
Building the source code
Important
Maven 2.0.9 (or higher) is used to build the release. Instructions for using
Maven2, including install, can be found at http://maven.apache.org
Use Maven to build the deployable unit binary.
[usr]$ cd jdiameter-1.6.0.FINAL
[usr]$ mvn install
Once the process finishes you should have the JAR files deployed in maven archive.
2.2.2.2. Development Trunk Source Building
Follow the process in Section 2.2.2.1, “Release Source Code Building”, replacing the SVN source
code URL with ?.
2.3. Diameter Stack Configuration
The stack is initially configured by parsing an XML file. The top level structure of the file is described
below. Further explanation of each child element, and the applicable attributes, is provided later
in this section.
10
Diameter Stack Configuration
The element contains parameters that affect the local Diameter peer. The available
elements and attributes are listed for reference.
11
Chapter 2. Mobicents Diameter...
Elements and Attributes
Specifies the URI for the local peer. The URI has the following format: "aaa://FQDN:port".
Contains one or more child element, which contain a single, valid IP address for
the local peer, stored in the value attribute of the IPAddress.
Specifies the realm of the local peer, using the value attribute.
Specifies a numeric identifier that corresponds to the vendor ID allocated by IANA.
Specifies the name of the local peer product.
Specifies the version of the firmware.
Optional parent element containing child elements that specify settings relating to the
Overload Monitor.
Supports child elements that specify the ID of the tracked application(s). It
also supports the following properties:
index
Defines the index of this overload monitor, so priorities/orders can be specified.
lowThreshold
The low threshold for activation of the overload monitor.
highThreshold
The high threshold for activation of the overload monitor.
Parent element containing child elements that specify information about the application. The
child elements create a unique application identifier. The child elements are:
Specifies the vendor ID for application definition. It supports a single property: "value".
The Authentication Application ID for application definition. It supports a single property:
"value".
12
Diameter Stack Configuration
The Account Application ID for application definition. It supports a single property: "value".
Contains a child element , which defines the list of default supported
applications. It is used for the server side, when the stack is configured to accept incoming
calls and there is an empty list of preconfigured peers (server is configured to accept any
connection).
13
Chapter 2. Mobicents Diameter...
The element contains elements that specify parameters for the Diameter stack.
The available elements and attributes are listed for reference. If not specified otherwise, each tag
supports a single property - "value", which indicates the value of the tag.
Elements and Attributes
Specifies whether the stack will accept connections from undefined peers. The default value
is false.
Specifies whether duplicate message protection is enabled. The default value is false.
Specifies the time each duplicate message is valid for (in extreme cases, it can live up to
2 * DuplicateTimer - 1 milliseconds). The default, minimum value is 240000 (4 minutes in
milliseconds).
Specifies the number of requests stored for duplicate protection. The default value is 5000.
Determines whether the URI should be used as FQDN. If it is set to true, the stack expects
the destination/origin host to be in the format of "aaa://isdn.domain.com:3868" rather than the
normal "isdn.domain.com". The default value is false.
Determines how many tasks the peer state machine can have before rejecting the next task.
This queue contains FSM events and messaging.
Determines the timeout for messages other than protocol FSM messages. The delay is in
milliseconds.
Determines how long the stack waits for all resources to stop. The delays are in milliseconds.
Determines how long it takes for CER/CEA exchanges to timeout if there is no response. The
delays are in milliseconds.
Determines how long the stack waits to retry the communication with a peer that has stopped
answering DWR messages. The delay is in milliseconds.
Determines how long it takes for a DWR/DWA exchange to timeout if there is no response.
The delay is in milliseconds.
14
Diameter Stack Configuration
Determines how long it takes for a DPR/DPA exchange to timeout if there is no response.
The delay is in milliseconds.
Determines how long it takes for the reconnection procedure to timeout. The delay is in
milliseconds.
Determines the number of threads for handling events in the Peer FSM.
The element contains elements that specify parameters for external peers. The
available elements and attributes are listed for reference.
Elements and Attributes
Parent element containing the child element , which specifies external peers and the
way they connect. specifies the name of external peers, whether they should be
treated as a server or client, and what rating the peer has externally.
supports the following properties:
name
Specifies the name of the peer in the form of a URI. The structure is "aaa://[fqdn|
ip]:port" (for example, "aaa://192.168.1.1:3868").
attempt_connect
Determines if the stack should try to connect to this peer. This property accepts boolean
values.
rating
Specifies the rating of this peer in order to achieve peer priorities/sorting.
Parent element containing the child element , which specifies all realms that connect
into the Diameter network. contains attributes and elements that describe different
16
Diameter Stack Configuration
realms configured for the Core. It supports child elements, which define the
applications supported.
supports the following parameters:
peers
Comma separated list of peers. Each peer is represented by an IP Address or FQDN.
local_action
Determines the action the Local Peer will play on the specified realm: Act as a LOCAL
peer.
dynamic
Specifies if this realm is dynamic. That is, peers that connect to peers with this realm
name will be added to the realm peer list if not present already.
exp_time
The time before a peer belonging to this realm is removed if no connection is available.
Below is an example configuration file for a server supporting the CCA, Sh and Ro Applications:
2.3.1. Cluster configuration
The following list defines the requirements for enabling stack cluster mode
• Add the following entries to the Parameters section of jdiameter-config.xml:
org.mobicents.diameter.impl.
SessionDatasource>
org.mobicents.diameter.impl.ha.
TimerFacility>
ha.data.ReplicatedData
19
Chapter 2. Mobicents Diameter...
2.4. Diameter Stack Source overview
Diameter stack is built with the following basic components:
Session Factory
The Session Factory governs the creation of sessions - raw and specific application sessions.
21
Chapter 2. Mobicents Diameter...
Raw and Application Sessions
Sessions govern stateful message routing between peers. Specific application sessions
consume different type of messages and act differently based on the data present.
Stack
The Stack governs all necessary components, which are used to establish connection and
communicate with remote peers.
Note
For more detailed information, please refer to the Javadoc or the simple examples
that can be found here: SVN Testsuite Trunk [http://mobicents.googlecode.com/
svn/trunk/servers/diameter/core/testsuite/load].
2.4.1. Session Factory
SessionFactory provides the stack user with access to session objects. It manages registered
application session factories in order to allow for the creation of specific application sessions.
A Session Factory instance can be obtained from the stack using the getSessionFactory()
method. The base SessionFactory interface is defined below:
package org.jdiameter.api;
import org.jdiameter.api.app.AppSession;
public interface SessionFactory {
RawSession getNewRawSession() throws InternalException;
Session getNewSession() throws InternalException;
Session getNewSession(String sessionId) throws InternalException;
T getNewAppSession(ApplicationId applicationId,
Class userSession) throws InternalException;
T getNewAppSession(String sessionId, ApplicationId
applicationId, Class userSession) throws InternalException;
}
However, since the stack is extensible, it is safe to cast the SessionFactory object to this
interface:
22
Session Factory
package org.jdiameter.client.api;
public interface ISessionFactory extends SessionFactory {
T getNewAppSession(String sessionId,
ApplicationId applicationId, java.lang.Class
aClass, Object... args) throws InternalException;
void registerAppFacory(Class sessionClass,
IAppSessionFactory factory);
void unRegisterAppFacory(Class sessionClass);
IConcurrentFactory getConcurrentFactory();
}
RawSession getNewRawSession() throws InternalException;
This method creates a RawSession. Raw sessions are meant as handles for code performing
part of the routing decision on the stack's, such as rely agents for instance.
Session getNewSession() throws InternalException;
This method creates a session that acts as the endpoint for peer communication (for a given
session ID). It declares the method that works with the Request and Answer objects. A session
created with this method has an autogenerated ID. It should be considered as a client session.
Session getNewSession(String sessionId) throws InternalException;
As above. However, the created session has an ID equal to that passsed as an argument.
This created session should be considered a server session.
T getNewAppSession(ApplicationId applicationId, Class userSession) throws InternalException;
This method creates a new specific application session, identified by the application ID and
class of the session passed. The session ID is generated by implementation. New application
sessions should be considered as client sessions. It is safe to type cast the return value to
class passed as an argument. This method delegates the call to a specific application session
factory.
applicationId,
Class
sessionId,
ApplicationId
userSession)
throws
InternalException;
As above. However, the session Id is equal to the argument passed. New sessions should
be considered server sessions.
23
Chapter 2. Mobicents Diameter...
T
getNewAppSession(String
sessionId,
ApplicationId
applicationId, java.lang.Class aClass, Object... args)
throws InternalException;
As above. However, it allows the stack to pass some additional arguments. Passed values
are implementation specifc.
void
registerAppFacory(Class
sessionClass,
IAppSessionFactory factory);
Registers the factory for a certain sessionClass. This factory will receive a delegated call
when ever the getNewAppSession method is called with an application class matching one
from the register method.
void unRegisterAppFacory(Class sessionClass);
Removes the application session factory registered for the sessionClass.
Example 2.1. SessionFactory use example
class Test implements EventListener
{
....
public void test(){
Stack stack = new StackImpl();
XMLConfiguration config = new XMLConfiguration(new FileInputStream(new File(configFile));
SessionFactory sessionFactory = stack.init(config);
stack.start();
//perferctly legal, both factories are the same.
sessionFactor = stack.getSessionFactory();
Session session = sessionFactory.getNewSession();
session.setRequestListener(this);
Request r = session.createRequest(308,ApplicationId.createByAuth(100L,10101L),
"mobicents.org","aaa://uas.fancyapp.mobicents.org");
//add avps specific for app
session.send(r,this);
}
}
Example 2.2. SessionFactory use example
class Test implements EventListener
{
24
Sessions
Stack stack = new StackImpl();
XMLConfiguration config = new XMLConfiguration(new FileInputStream(new File(configFile));
ISessionFactory sessionFactory = (ISessionFactory)stack.init(config);
stack.start();
//perferctly legal, both factories are the same.
sessionFactor = (ISessionFactory)stack.getSessionFactory();
sessionFactory.registerAppFacory(ClientShSession.class, new ShClientSessionFactory(this));
//our implementation of factory does not require any parameters
ClientShSession session = (ClientShSession) sessionFactory.getNewAppSession(null, null
, ClientShSession.class, null);
...
session.sendUserDataRequest(udr);
}
2.4.2. Sessions
RawSessions, Sessions and ApplicationSessions provide the means for dispatching and
receiving messages. Specific implementation of ApplicationSession may provide non standard
methods.
The RawSession and the Session life span is controlled entirely by the application. However, the
ApplicationSession life time depends on the implemented state machine.
RawSession is defined as follows:
public interface BaseSession extends Wrapper, Serializable {
long getCreationTime();
long getLastAccessedTime();
boolean isValid();
Future send(Message message) throws InternalException,
IllegalDiameterStateException, RouteException, OverloadException;
Future send(Message message, long timeOut, TimeUnit timeUnit)
throws InternalException, IllegalDiameterStateException, RouteException, OverloadException;
void release();
}
25
Chapter 2. Mobicents Diameter...
public interface RawSession extends BaseSession {
Message createMessage(int commandCode, ApplicationId applicationId, Avp... avp);
Message createMessage(int commandCode, ApplicationId applicationId,
long hopByHopIdentifier, long endToEndIdentifier, Avp... avp);
Message createMessage(Message message, boolean copyAvps);
void send(Message message, EventListener listener)
throws InternalException, IllegalDiameterStateException, RouteException, OverloadException;
void send(Message message, EventListener listener,
long timeOut, TimeUnit timeUnit) throws InternalException,
IllegalDiameterStateException, RouteException, OverloadException;
}
long getCreationTime();
Returns the time stamp of this session creation.
long getLastAccessedTime();
Returns the time stamp indicating the last sent or received operation.
boolean isValid();
Returns true when this session is still valid (ie, release() has not been called).
void release();
Application calls this method to inform the user that the session should free any associated
resource - it shall not be used anymore.
Future send(Message message)
Sends a message in async mode. The Future reference provides the means of accessing
the answer once it is received
void
send(Message
message,
EventListener
listener,
long
timeOut, TimeUnit timeUnit)
As above. Allows to specify the time out value for send operations.
Message createMessage(int commandCode, ApplicationId applicationId, Avp... avp);
Creates a Diameter message. It should be explicitly set either as a request or answer. Passed
parameters are used to build messages.
Message
createMessage(int
commandCode,
ApplicationId
applicationId,
long
hopByHopIdentifier, long endToEndIdentifier, Avp... avp);
As above. However, it also allows for the Hop-by-Hop and End-to-End Identifiers in the
message header to be set. This method should be used to create answers.
26
Application Session Factories
Message createMessage(Message message, boolean copyAvps);
Clones a message and returns the created object. The copyAvps parameter defines whether
basic AVPs (Session, Route and Proxy information) should be copied to the new object.
void send(Message message, EventListener listener)
Sends a message. The answer will be delivered by the specified listener
void
send(Message
message,
EventListener
listener,
long
timeOut, TimeUnit timeUnit)
As above. It also allows for the answer to be passed after timeout.
Session defines similar methods, with exactly the same purpose:
public interface Session extends BaseSession {
String getSessionId();
void setRequestListener(NetworkReqListener listener);
Request createRequest(int commandCode, ApplicationId appId, String destRealm);
Request createRequest(int commandCode, ApplicationId appId, String destRealm, String destHost);
Request createRequest(Request prevRequest);
void send(Message message, EventListener listener)
throws InternalException, IllegalDiameterStateException, RouteException, OverloadException;
void send(Message message, EventListener listener, long timeOut,
TimeUnit timeUnit) throws InternalException, IllegalDiameterStateException,
RouteException, OverloadException;
}
2.4.3. Application Session Factories
In the table below, you can find session factories provided by current implementation, along with
a short description:
Table 2.1. Application Factories
Factory class
Application type & id Application
org.jdiameter.common
.impl.app.acc. AccountingId[0:3]
AccSessionFactoryImpl
Acc
Reference
RFC3588
[http://
tools.ietf.org/html/
rfc3588]
27
Chapter 2. Mobicents Diameter...
Factory class
Application type & id Application
org.jdiameter.common
.impl.app.auth. Specific
AuthSessionFactoryImpl
Auth
Reference
RFC3588
[http://
tools.ietf.org/html/
rfc3588]
org.jdiameter.common
.impl.app.cca. AuthId[0:4]
CCASessionFactoryImpl
CCA
RFC4006
[http://
tools.ietf.org/html/
rfc4006]
org.jdiameter.common
.impl.app.sh. AuthId[10415:16777217]Sh
ShSessionFactoryImpl
TS.29328
[http://
www.3gpp.org/ftp/
Specs/htmlinfo/29328.htm],
TS.29329
[http://
www.3gpp.org/ftp/
Specs/htmlinfo/29329.htm]
org.jdiameter.common
.impl.app.cxdx. AuthId[13019:16777216]Cx
CxDxSessionFactoryImpl
TS.29228
[http://
www.3gpp.org/ftp/
Specs/htmlinfo/29228.htm],
TS.29229
[http://
www.3gpp.org/ftp/
Specs/htmlinfo/29229.htm]
org.jdiameter.common
.impl.app.cxdx. AuthId[10415:16777216]Dx
CxDxSessionFactoryImpl
TS.29228
[http://
www.3gpp.org/ftp/
Specs/htmlinfo/29228.htm],
TS.29229
[http://
www.3gpp.org/ftp/
Specs/htmlinfo/29229.htm]
org.jdiameter.common
.impl.app.acc. AccountingId[10415:3] Rf
AccSessionFactoryImpl
TS.32240
[http://
www.3gpp.org/ftp/
Specs/htmlinfo/32240.htm]
org.jdiameter.common
.impl.app.cca. AuthId[10415:4]
CCASessionFactoryImpl
Ro
TS.32240
[http://
www.3gpp.org/ftp/
Specs/htmlinfo/32240.htm]
28
Diameter Stack Validator
Note
There is no specific factory for Ro and Rf. Those applications reuse the respective
session and session factories.
Note
Application IDs contain two numbers - [VendorId:ApplicationId].
Important
Spaces have been introduced in the Factory class column values to correctly
render the table. Please remove them when using copy/paste.
2.5. Diameter Stack Validator
Validator is one of the Stack features. The primary purpose of the Validator is to detect malformed
messages, such as an Answer message containing a Destination-Host Attribute Value Pair (AVP).
The Validator is capable of validating multi-leveled, grouped AVPs, excluding the following content
types:
• URI, or Identifier types.
• Enumerated types against defined values.
The Validator is only capable of checking structural integrity, not the content of the message.
The Validator performs the following checks:
Index
Checks that the AVPs are in the correct place. For example, Session-Id must always be
encoded before any other AVP.
Multiplicity
Checks that the message AVPs occur the proper number of times. For example, the SessionID should only be present once.
The Validator is called by the stack implementation. It is invoked after the message is received,
but before it is dispatched to a remote peer.
29
Chapter 2. Mobicents Diameter...
Note
This means that if the peer does not exist in the local peer table, the validator is
not called, as the stack fails before calling it.
2.5.1. Validator Configuration
The Validator is configured with a single XML file. This file contains the structure definition for
both messages and AVPs.
Upon creation of the Diameter Stack, the validator is initialized. It performs the initialization by
looking up the dictionary.xml file in classpath.
Note
The configuration file contains more data that Validator uses to build its data
base. This is because the Dictionary uses the same file to configure itself. It
reuses the AVP definitions, with some extra information like AVP type and flags.
The configuration file has the following structure:
The root element that contains the child elements comprising the validator and dictionary
components. This element does not support any attributes.
Specifies whether message validation is activated for sent and received stack messages. The
element supports the following optional attributes:
enabled
Specifies whether the validator is activated or deactivated. If not specified, the validator
is deactivated.
sendLevel
Determines the validation level for messages sent by the stack instance. Values determine
if sent messages are not validated at all (OFF), only message level AVPs are checked
(MESSAGE) or all AVPs are checked (ALL).
receiveLevel
Determines the validation level for messages received by the stack instance. Values
determine if sent messages are not validated at all (OFF), only message level AVPs are
checked (MESSAGE) or all AVPs are checked (ALL).
Optional element that specifies the mapping between the vendor name, vendor ID, and vendor
code. The element supports the following required attributes:
name
Specifies the vendor name. For example, "Hewlett Packard".
vendor-id
Specifies the unique ID associated with the vendor. For example, "HP".
code
Specifies the alpha-numeric code allocated to the vendor by IANA. For example, "11".
The value must be unique for each declaration.
Example 2.3. XML Attributes
...
Defines the simple Attribute Value Pair (AVP) types. The element supports the following
required attributes:
type-name
Specifies a type name in accordance with the acceptable base types defined in RFC 3588.
For example; "Enumerated", "OctetString", "Integer32".
type-parent
Specifies the parent type name used to define the base characteristics of the type.
The values are restricted to defined elements. For example; "OctetString",
"UTF8String", "IPAddress".
Example 2.4. XML Attributes
Defines the specific applications used within the dictionary. Two child elements are supported
by : and .
32
Validator Configuration
The element supports the following attributes:
id
Specifies the unique ID allocated to the application. The attribute is used in all messages
and forms part of the message header.
name
Optional attribute that specifies the logical name of the application.
uri
Optional attribute that specifies a link to additional application information.
Example 2.5. XML Attributes
name="3GPP
Cx/Dx"
uri="http://www.ietf.org/rfc/rfc3588.txt?
Element containing information necessary to configure the Attribute Value Pairs. Table 2.2,
“ Attributes” contains the complete list of supported attributes, and their available values
(if applicable).
The element supports a number of child elements that are used to set finer parameters
for the individual AVP. The supported elements are , , and .
Note
Different sets of elements are supported by depending on its position
in the dictionary.xml file.
Example 2.6. Child Elements and Attributes
Child element of that is used to match the AVP with the AVP type as defined in the
element. The element supports the following mandatory attribute:
type-name
Specifies the type-name of the element. This is used to match the type-name value in
the element.
Note
is ignored if the element contains the element.
Child element of that specifies the enumeration value for the specified AVP.
is used only when the type-name attribute of is specified. The element supports the
following mandatory attributes:
name
Specifies the name of a constant value that applies to the AVP.
code
Specifies the integer value associated with the name of the constant. The value is passed
as a value of the AVP, and maps to the name attribute.
Note
is ignored if the element contains the element.
Child element of that specifies the AVP is a grouped type. A grouped AVP is one that
has no element present. The element does not support any attributes, however
the element is allowed as a child element.
The , which specifies a reference to a grouped AVP, supports one mandatory attribute:
name
Specifies the name of the grouped AVP member. The value must match the defined AVP
name.
34
Validator Configuration
Table 2.2. Attributes
Attribute Name (optional in Explicit Values (default in Description
brackets)
brackets)
name
Specifies the name of the
AVP. This is used to match the
AVP definition to any grouped
AVP references. For further
information about grouped
AVPs, refer to the element
description in this section.
code
(vendor-id)
Specifies the integer code of
the AVP.
(none)
Used to match the vendor ID
reference to the value defined
in the element.
(multiplicity)
Specifies the number
acceptable
AVPs
in
of
a
message using an explicit
value.
0
An AVP must not be present in
the message.
(0+)
Zero or more instances of the
AVP must be present in the
message.
0-1
Zero, or one instance of the
AVP may be present in the
message. An error occurs if
the message contains more
than one instance of the AVP.
1
One instance of the AVP must
be present in the message.
1+
At least one instance of the
AVP must be present in the
message.
may-encrypt
Yes | (No)
Specifies whether the AVP
can be encrypted.
protected
may | must | mustnot
Determines actual state of
AVP that is expected, if it
MUST be encrypted , may or
MUST NOT.
35
Chapter 2. Mobicents Diameter...
Attribute Name (optional in Explicit Values (default in Description
brackets)
brackets)
vendor-bit
must | mustnot
Specifies whether the Vendor
ID should be set.
mandatory
may | must | mustnot
Determines if support for this
AVP is mandatory in order to
consume/process message.
vendor
Specifies the defined vendor
code, which is used by the
child element.
Example 2.7. XML Attributes
Specifies the command for the application. The element supports the element, which
specifies the structure of the command. The element supports the following attributes:
name
Optional parameter that specifies the message name for descriptive purposes.
code
Mandatory parameter that specifies the integer code of the message.
request
Mandatory parameter that specifies whether the declared command is a request or
answer. The available values are "true" (request) or "false" (answer).
36
Validator Source Overview
Note
If the element is specified in , it does not support any child
elements. The element only refers to defined AVPs when used in this
context.
Example 2.8. Elements and Attributes
2.5.2. Validator Source Overview
The Validator API defines methods to access its database of AVPs and check if the AVP and
message have the proper structure.
The Validator is currently message oriented. This means that it declares methods
that center on message consistency checks. The class containing all validation logic
is org.jdiameter.common.impl.validation.DiameterMessageValidator. It exposes the
following methods:
public boolean isOn();
Simple method to determine if the Validator is enabled.
public ValidatorLevel getSendLevel();
Returns the validation level of outgoing messages. It can have one of the following values:
OFF, MESSAGE, ALL.
public ValidatorLevel getReceiveLevel()
Returns the validation level of incoming messages. It can have one of the following values:
OFF, MESSAGE, ALL.
public void validate(Message msg, boolean incoming) throws JAvpNotAllowedException
Performs validation on a message. Based on the incoming flag, the correct validation level
is applied. If validation fails, an exception with details is thrown.
public
void
validate(Message
msg,
ValidatorLevel
validatorLevel)
throws
JAvpNotAllowedException
Performs validation on messages with a specified level. It is a programatical way
to allow different levels of validation from those configured. If validation fails, a
JAvpNotAllowedException with details is thrown.
37
Chapter 2. Mobicents Diameter...
Note
The current implementation provides more methods, however those are out of
scope for this documentation.
A simple example of a Validator use case is shown below:
Example 2.9. Validator Message Check Example
The example below is pseudo-code.
...
boolean isRequest = true;
boolean isIncoming = false;
DiameterMessageValidator messageValidator = DiameterMessageValidator.getInstance();
Message message = createMessage(UserDataRequest.MESSAGE_CODE, isRequest,
applicationId);
//add AVPs
...
//perform check
try{
messageValidator.validate(message, isIncoming);
}
catch(JAvpNotAllowedException e) {
System.err.println("Failed to validate ..., avp code: " + e.getAvpCode() + " avp
vendor:" + e.getVendorId() + ", message:" + e.getMessage());
}
38
Chapter 3.
Multiplexer (MUX)
The Multiplexer (MUX) is designed as a stack wrapper. It serves two purposes:
Expose Stack
It exposes the stack and allows it to be shared between multiple listeners. The stack follows
the life cycle of the MUX. It is created and destroyed with MUX.
Expose Management Operations
Exposes the management operations for JMX clients, one of them being the RHQ Console.
For specific information please refer to the Mobicents Diameter Management Console User
Guide.
3.1. Diameter Multiplexer (MUX) Design
MUX is a simple service provided on behalf of the Stack. Entities interested in receiving messages
for certain diameter applications register in MUX. Upon registration, the entity passes a set of
application IDs. Based on the message content and registered listeners, MUX either drops the
message or passes it to the proper listener. MUX checks application IDs present in the message
to match the target listener.
39
Chapter 3. Multiplexer (MUX)
Figure 3.1. Diameter Multiplexer (MUX) Design Overview
3.2. Diameter Multiplexer (MUX) Setup
3.2.1. Pre-Install Requirements and Prerequisites
Ensure that the following requirements have been met before continuing with the installation
process.
3.2.1.1. Hardware Requirements
MUX does not have any hardware requirements.
3.2.1.2. Software Prerequisites
MUX must be deployed either in JBoss Application Server v4.x or v5.x. However it is possible to
adapt configuration files and run in any JMX container.
40
Source Code
3.2.2. Source Code
This section provides instructions on how to obtain and build the Mobicents Diameter MUX from
source code.
3.2.2.1. Release Source Code Building
1.
Downloading the source code
Important
Subversion is used to manage its source code. Instructions for using
Subversion, including installation, can be found at http://svnbook.redbean.com.
Use SVN to checkout a specific release source. The base URL is ?. Then add the specific
release version, for example 1.6.0.FINAL.
[usr]$ svn co ?/1.6.0.FINAL mux-1.6.0.FINAL
2.
Building the source code
Important
Maven 2.0.9 (or higher) is used to build the release. Instructions for using
Maven2, including installation, can be found at http://maven.apache.org.
Use Maven to build the deployable unit binary.
[usr]$ cd mux-1.6.0.FINAL
[usr]$ mvn install
Once the process finishes you should have the SAR built. If the JBOSS_HOME environment
variable is set, the SAR will be deployed in the container after execution.
41
Chapter 3. Multiplexer (MUX)
Note
By default Mobicents Diameter MUX; deploys in the JBoss Application Server v5.x
SAR. To change it, run maven with the profile switch command: -Pjboss4.
3.2.2.2. Development Trunk Source Building
Follow the Section 3.2.2.1, “Release Source Code Building” procedure, replacing the SVN source
code URL with ?.
3.3. Diameter Multiplexer (MUX) Configuration
MUX requires three configuration files:
jboss-service.xml
This file is specific to SAR. Please refer to the JBoss Application Server manual for
explanation. The file binds Diameter MUX under the following JMX object name by default:
diameter.mobicents:service=DiameterStackMultiplexer.
jdiameter-config.xml
This file configures the stack exposed by MUX. Please refer to Section 2.3, “Diameter Stack
Configuration” for details. It is located in mobicents-diameter-mux-1.6.0.FINAL.sar/
config.
dictionary.xml
This file configures the dictionary. Its structure and content is identical to the file described in
Section 2.5.1, “Validator Configuration”.
3.4. Diameter MUX Source Overview
The
Diameter
MUX
capabilities
are
defined
by
the
MBean
interface
org.mobicents.diameter.stack.DiameterStackMultiplexerMBean. This interface defines
two types of methods:
Management
Used by RHQ console. These methods are outside the scope of this documentation.
Stack Accessors
Methods that allow the user to retrieve and use a wrapped stack.
The methods below are of interest to a Diameter MUX user:
public Stack getStack();
Returns a stack wrapped by the multiplexer. It is present as a convenience method, and the
stack should only be changed directly by expert users.
42
Diameter MUX Source Overview
public void registerListener(DiameterListener listener, ApplicationId[] appIds)
throws IllegalStateException;
Registers a listener to be triggered when a message for a certain application ID is received.
public void unregisterListener(DiameterListener listener);
Removes the message listener.
public DiameterStackMultiplexerMBean getMultiplexerMBean();
Returns the actual instance of MUX.
The listener interface is defined below:
package org.mobicents.diameter.stack;
import java.io.Serializable;
import org.jdiameter.api.Answer;
import org.jdiameter.api.EventListener;
import org.jdiameter.api.NetworkReqListener;
import org.jdiameter.api.Request;
public interface DiameterListener extends NetworkReqListener, Serializable,
EventListener
{
}
MUX can be used as follows:
public class DiameterActor implements DiameterListener
{
private ObjectName diameterMultiplexerObjectName = null;
private DiameterStackMultiplexerMBean diameterMux = null;
private synchronized void initStack() throws Exception {
this.diameterMultiplexerObjectName =
new ObjectName("diameter.mobicents:service=DiameterStackMultiplexer");
Object[] params = new Object[]{};
String[] signature = new String[]{};
String operation = "getMultiplexerMBean";
43
Chapter 3. Multiplexer (MUX)
this.diameterMux=mbeanServer.invoke(this.diameterMultiplexerObjectName, operation,
params, signature);
long acctAppIds = new long[]{19312L};
long acctVendorIds = new long[]{193L};
long authAppIds = new long[]{4L};
long authVendorIds = new long[]{0L};
List appIds = new ArrayList();
for(int index = 0;index
Source Exif Data:
File Type : PDF
File Type Extension : pdf
MIME Type : application/pdf
PDF Version : 1.4
Linearized : Yes
XMP Toolkit : Adobe XMP Core 5.6-c015 84.159810, 2016/09/10-02:41:30
Modify Date : 2017:04:24 09:49:42-06:00
Metadata Date : 2017:04:24 09:49:42-06:00
Document ID : uuid:e59fefca-cff8-4f95-bee3-a27abcd861f3
Instance ID : uuid:994a6843-42b3-40d6-be4c-93f795a06333
Format : application/pdf
Page Mode : UseOutlines
Page Count : 60
Profile CMM Type : Linotronic
Profile Version : 2.1.0
Profile Class : Display Device Profile
Color Space Data : RGB
Profile Connection Space : XYZ
Profile Date Time : 1998:02:09 06:49:00
Profile File Signature : acsp
Primary Platform : Microsoft Corporation
CMM Flags : Not Embedded, Independent
Device Manufacturer : Hewlett-Packard
Device Model : sRGB
Device Attributes : Reflective, Glossy, Positive, Color
Rendering Intent : Perceptual
Connection Space Illuminant : 0.9642 1 0.82491
Profile Creator : Hewlett-Packard
Profile ID : 0
Profile Copyright : Copyright (c) 1998 Hewlett-Packard Company
Profile Description : sRGB IEC61966-2.1
Media White Point : 0.95045 1 1.08905
Media Black Point : 0 0 0
Red Matrix Column : 0.43607 0.22249 0.01392
Green Matrix Column : 0.38515 0.71687 0.09708
Blue Matrix Column : 0.14307 0.06061 0.7141
Device Mfg Desc : IEC http://www.iec.ch
Device Model Desc : IEC 61966-2.1 Default RGB colour space - sRGB
Viewing Cond Desc : Reference Viewing Condition in IEC61966-2.1
Viewing Cond Illuminant : 19.6445 20.3718 16.8089
Viewing Cond Surround : 3.92889 4.07439 3.36179
Viewing Cond Illuminant Type : D50
Luminance : 76.03647 80 87.12462
Measurement Observer : CIE 1931
Measurement Backing : 0 0 0
Measurement Geometry : Unknown
Measurement Flare : 0.999%
Measurement Illuminant : D65
Technology : Cathode Ray Tube Display
Red Tone Reproduction Curve : (Binary data 2060 bytes, use -b option to extract)
Green Tone Reproduction Curve : (Binary data 2060 bytes, use -b option to extract)
Blue Tone Reproduction Curve : (Binary data 2060 bytes, use -b option to extract)
Create Date : 2014:10:31 05:07:17Z
Creator : jDocBook Plugin for Maven
Producer : jDocBook Plugin for Maven
EXIF Metadata provided by EXIF.tools