Quarkus JDiameter
The Diameter protocol is a computer networking protocol for Authentication, Authorisation and Accounting, as defined in RFC6733. It is extensively used in the 3GPP telecommunication industry.
JDiameter is an existing Java Diameter stack that supports the protocol. The original RestComm implementation (https://github.com/RestComm/jdiameter) is quite old, and its active support has stopped.
The Quarkus Diameter extension has updated the JDiameter implementation for both a Quarkus JVM and a Native application.
Installation
If you want to use this extension, you need to add the io.quarkiverse.jdiameter:quarkus-diameter extension first to your build file.
For instance, with Maven, add the following dependency to your POM file:
<properties>
<quarkus.jdiameter.version>2.0.x</quarkus.jdiameter.version> <!-- Set to the latest version of Quarkus JDiamter -->
</properties>
<dependency>
<groupId>io.quarkiverse.jdiameter</groupId>
<artifactId>quarkus-jdiameter</artifactId>
<version>${quarkus.jdiameter.version}</version>
</dependency>Implementing a Diameter Service
To implement a Diameter service, a class must be defined and annotated with @DiameterService and optionally @DiameterServiceOptions.
The @DiameterServiceOption annotation is used, among other things, to specify the Diameter configuration profile to use for the service.
If it is not specified, the service will use the default configuration profile.
The type of Diameter service is determined by the Diameter Application Session Listener interfaces implemented by the service.
The DiameterService interceptor will initialise all the configured services and start the Diameter stack (if it hasn’t already started).
Example
@DiameterService (1)
@DiameterServiceOption("client1") (2)
public class MyDiameterService implements ClientCCASessionListener (3)
{
@Override public void doCreditControlAnswer(ClientCCASession session, JCreditControlRequest request, JCreditControlAnswer answer) throws InternalException
{
//...
}
}| 1 | Marking the class as a diameter service |
| 2 | The optional configuration option to apply to the diameter service. If not defined, the <default> configuration will be used. |
| 3 | Implements the SessionListener associated with the Session Type.
(See List below) |
Application Session Types
The session listener determines the Diameter service session type it implements. The list below contains all the session types currently supported by the Diameter Service implementation.
| Session Type | Server Session Interface | Client Session Interface | Application | Reference |
|---|---|---|---|---|
Acc |
ServerAccSessionListener |
ClientAccSessionListener |
AccountingId[0:3] |
|
Auth |
ServerAuthSessionListener |
ClientAuthSessionListener |
Internal |
|
CCA |
ServerCCASessionListener |
ClientCCASessionListener |
AuthId[0:4] |
|
Gx |
ServerGxSessionListener |
ClientGxSessionListener |
- |
- |
Rx |
ClientRxSessionListener |
ClientRxSessionListener |
- |
- |
S6a |
ServerS6aSessionListener |
ClientS6aSessionListener |
- |
- |
Gq |
ServerGqSessionListener |
ClientGqSessionListener |
- |
- |
Sh |
ServerShSessionListener |
ClientShSessionListener |
- |
- |
CxDx |
ServerCxDxSessionListener |
ClientCxDxSessionListener |
AuthId[13019:16777216] AuthId[10415:16777216] |
TS.29228 |
S13 |
ServerS13SessionListener |
ClientS13SessionListener |
- |
- |
Ro |
ServerRoSessionListener |
ClientRoSessionListener |
AuthId[10415:4] |
TS.32240 |
Rf |
ServerRfSessionListener |
ClientRfSessionListener |
AccountingId[10415:3] |
TS.32240 |
Only one implementation of a session listener per diameter stack is allowed per application.
If the build phase detected that the same session listener is implemented more than once for the same diameter stack a DiameterConfigException exception will be generated.
|
| A Diameter service may implement more than one session listener. |
Diameter Server mode
If a Diameter service implements any of the ServerXXXSessionListeners, the Diameter Service interceptor automatically creates a network listener for that Diameter service.
The interceptor will skip creating a listener if it detects that the Diameter Service has implemented the NetworkListener interface.
|
In most cases you do not need to implement your own NetworkListener and you can let the interceptor create one for you!
|
Injecting the Diameter stack
An application can inject the diameter stack and configuration for a given configuration profile.
| Only one stack is created per enabled configuration profile. |
| The stack will only be active if there is a defined DiameterService for the stack. |
@ApplicationScoped
public class Demo {
@DiameterConfig (1)
Stack stack;
@DiameterConfig("test2") (2)
Configuration test2Config;
//...
}| 1 | Injecting the Diameter stack associated with the "<default>" configuration. |
| 2 | Injecting the Diameter configuration for the "test2" configuration. |
Using Quarkus JDiameter in an high availability environment
The Quarkus JDiameter keeps track of each active session by storing the session information for each session. Quarkus JDiameter also sets various timers linked to these sessions. In a standalone mode, the session state is stored locally, and the timers are defined in the local JVM. To use the diameter stack in a high availability (HA) mode, where two or more nodes are used in a load balance or failover mode, the sessions cannot be stored in local RAM.
To use Quarkus JDiameter in an HA environment the HA extensions must be loaded.
The HA extensions store the session state in an Infinispan Cache and use Infinispan timers to implement the diameter timers.
The HA extensions store the session information in a remote cache called diameter.
The cache used can be changed by setting the quarkus.diameter.parameter.caching-name property
|
The Quarkus extension automatically include the HA extensions. To use the HA components, the following configuration needs to be added:
quarkus.diameter.parameter.caching-name=drasessions (1)
meter.extensions.session-datasource=org.jdiameter.impl.ha.data.CachedSessionDatasourceImpl
quarkus.diameter.extensions.timer-facility=org.jdiameter.impl.ha.timer.ReplicatedTimerFacilityImpl| 1 | This option changes the caching name from the default diameter to 'drasessions'. |
| The HA implementation depends on the Quarkus Infinispan client. You also need to provide the Infinispan configuration to make this all work. |
Example Configuration
The example configuration defines two sets of client diameter config. One is the default config, and the other is named config and is called 'test1'.
quarkus.diameter.local-peer.uri=aaa://ocsclient:1812
quarkus.diameter.local-peer.ip-addresses=0.0.0.0, 127.0.0.1
quarkus.diameter.local-peer.realm=server.test.com
quarkus.diameter.local-peer.product-name=Diameter Test Client
quarkus.diameter.local-peer.firmware-revision=1
quarkus.diameter.local-peer.applications.0.auth-appl-id=4
quarkus.diameter.local-peer.applications.1.auth-appl-id=4
quarkus.diameter.local-peer.applications.1.vendor-id=10415
quarkus.diameter.parameter.use-virtual-threads=true
quarkus.diameter.network.peers.peer-uri=aaa://ocs.test.org:3868
quarkus.diameter.network.peers.ip=127.0.0.1
quarkus.diameter.network.peers.attempt-connect=true
quarkus.diameter.network.peers.rating=0
quarkus.diameter.network.realms."server.test.com".peers=192.168.241.1,localhost
quarkus.diameter.network.realms."server.test.com".local-action=local
quarkus.diameter.network.realms."server.test.com".dynamic=false
quarkus.diameter.network.realms."server.test.com".exp-time=1
quarkus.diameter.network.realms."server.test.com".application-id.auth-appl-id=4
quarkus.diameter.test1.local-peer.uri=aaa://ocsclient:1813
quarkus.diameter.test1.local-peer.ip-addresses[0]=0.0.0.0, 127.0.0.1
quarkus.diameter.test1.local-peer.realm=server.test.com
quarkus.diameter.test1.local-peer.product-name=Diameter Test Client
quarkus.diameter.test1.local-peer.firmware-revision=1
quarkus.diameter.test1.local-peer.applications.0.auth-appl-id=4
quarkus.diameter.test1.parameter.use-virtual-threads=true
quarkus.diameter.test1.network.peers.peer-uri=aaa://ocs.test.org:3868
quarkus.diameter.test1.network.peers.ip=127.0.0.1
quarkus.diameter.test1.network.peers.attempt-connect=true
quarkus.diameter.test1.network.peers.rating=0
quarkus.diameter.test1.network.realms."server.test.com".peers=192.168.241.1,localhost
quarkus.diameter.test1.network.realms."server.test.com".local-action=local
quarkus.diameter.test1.network.realms."server.test.com".dynamic=false
quarkus.diameter.test1.network.realms."server.test.com".exp-time=1
quarkus.diameter.test1.network.realms."server.test.com".application-id.auth-appl-id=4| For more information about the extension configuration, please refer to the Configuration Reference. |
Configuration property fixed at build time - All other configuration properties are overridable at runtime
Configuration property |
Type |
Default |
|---|---|---|
The localPeer element contains parameters that affect the local Diameter peer |
Type |
Default |
Specifies the URI for the local peer. The URI has the following format: "aaa://FQDN:port". Environment variable: |
string |
|
The name of the TLS configuration to use. If not set and the default TLS configuration is configured ( If no TLS configuration is set, and Environment variable: |
string |
|
Contains one or more valid IP address for the local peer.` Environment variable: |
list of string |
|
Specifies the realm of the local peer. Environment variable: |
string |
|
Specifies the name of the local peer product Environment variable: |
string |
|
Specifies the version of the firmware. Environment variable: |
long |
|
Specifies a numeric identifier that corresponds to the vendor ID allocated by IANA. Environment variable: |
long |
|
Type |
Default |
|
Specifies the vendor ID for application definition. Environment variable: |
long |
|
The Authentication Application ID for application definition. Environment variable: |
long |
|
The Account Application ID for application definition. Environment variable: |
long |
|
Optional parent element containing child elements that specify settings |
Type |
Default |
Defines the index of this overload monitor, so priorities/orders can be specified. Environment variable: |
int |
|
The low threshold for activation of the overload monitor. Environment variable: |
double |
|
The high threshold for activation of the overload monitor. Environment variable: |
double |
|
Specifies the vendor ID for application definition. Environment variable: |
long |
|
The Authentication Application ID for application definition. Environment variable: |
long |
|
The Account Application ID for application definition. Environment variable: |
long |
|
The Parameters element contains elements that specify parameters for the Diameter stack |
Type |
Default |
Specifies whether the stack will accept connections from undefined peers. The default value is Environment variable: |
boolean |
|
Specifies whether duplicate message protection is enabled. The default value is Environment variable: |
boolean |
|
Determines whether the URI should be used as FQDN. If it is set to Environment variable: |
boolean |
|
Specifies whether the stack should use virtual threads The default value is Environment variable: |
boolean |
|
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 Environment variable: |
long |
|
Specifies the number of requests stored for duplicate protection. The default value is Environment variable: |
int |
|
Determines how many tasks the peer state machine can have before rejecting the next task. This queue contains FSM events and messaging Environment variable: |
int |
|
Determines the timeout for messages other than protocol FSM messages. The delay is in milliseconds. Environment variable: |
long |
|
Determines how long the stack waits for all resources to stop. The delays are in milliseconds. Environment variable: |
long |
|
Determines how long it takes for CER/CEA exchanges to timeout if there is no response. The delays are in milliseconds. Environment variable: |
long |
|
Determines how long the stack waits to retry the communication with a peer that has stopped answering DWR messages. The delay is in milliseconds. Environment variable: |
long |
|
Determines how long it takes for a DWR/DWA exchange to timeout if there is no response. The delay is in milliseconds. Environment variable: |
long |
|
Determines how long it takes for a DPR/DPA exchange to timeout if there is no response. The delay is in milliseconds. Environment variable: |
long |
|
Determines how long it takes for the reconnection procedure to timeout. The delay is in milliseconds. Environment variable: |
long |
|
Determines how long it takes for the session to timeout The delay is in milliseconds. Environment variable: |
long |
|
Determines the number of threads for handling events in the Peer FSM. Environment variable: |
int |
|
Determines a delay before binding. The delay is in milliseconds. Environment variable: |
long |
|
Determines the maximum thread count in other entities. Environment variable: |
int |
|
Determines the thread count for message processing tasks. Environment variable: |
int |
|
Specifies the thread pool for identifying duplicate messages. Environment variable: |
int |
|
Specifies the thread pool for redirecting messages that do not need any further processing. Environment variable: |
int |
|
Determines the thread pool for managing the overload monitor. Environment variable: |
int |
|
Determines the thread pool for managing tasks regarding peer connection FSM. Environment variable: |
int |
|
Determines the thread pool for statistic gathering tasks. Environment variable: |
int |
|
Determines the thread pool for managing the invocation of application session FSMs, which will invoke listeners. Environment variable: |
int |
|
The caching name to be used if HA datasource is used Environment variable: |
string |
|
The Network< element contains elements that specify parameters for external peers |
Type |
Default |
Type |
Default |
|
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"). Environment variable: |
string |
|
Specifies the rating of this peer in order to achieve peer priorities/sorting. Environment variable: |
int |
|
Specifies the actual ip for the peer-uri, for example 192.168.1.1 Environment variable: |
string |
|
Specifies a port range to accept connection override the port number in peer-uri Environment variable: |
string |
|
Determines if the stack should try to connect to this peer. Environment variable: |
boolean |
|
The name of the TLS configuration to use. If not set and the default TLS configuration is configured ( If no TLS configuration is set, and Environment variable: |
string |
|
Type |
Default |
|
Comma separated list of peers. Each peer is represented by an IP Address or FQDN. Environment variable: |
string |
|
Determines the action the Local Peer will play on the specified realm: Act as a LOCAL peer. Environment variable: |
|
|
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. Environment variable: |
boolean |
|
The time before a peer belonging to this realm is removed if no connection is available. The time is in seconds. Environment variable: |
long |
|
Specifies the vendor ID for application definition. Environment variable: |
long |
|
The Authentication Application ID for application definition. Environment variable: |
long |
|
The Account Application ID for application definition. Environment variable: |
long |
|
Retrieves the properties of the agent configuration. Environment variable: |
Map<String,String> |
|
The extensions elements contains elements that override existing components in the Diameter stack |
Type |
Default |
The MetaData extension Environment variable: |
string |
|
The MetaData extension Environment variable: |
string |
|
The MetaData extension Environment variable: |
string |
|
The MetaData extension Environment variable: |
string |
|
The MetaData extension Environment variable: |
string |
|
The Realm Controller extension Environment variable: |
string |
|
The Session Factory extension Environment variable: |
string |
|
The Transport Factory extension Environment variable: |
string |
|
The Connection extension Environment variable: |
string |
|
The Network Guard extension Environment variable: |
string |
|
The Peer Fsm Factory extension Environment variable: |
string |
|
The Statistic Factory extension Environment variable: |
string |
|
The Concurrent Factory extension Environment variable: |
string |
|
The Concurrent Entity Factory extension Environment variable: |
string |
|
The Statistic Processor extension Environment variable: |
string |
|
The Network extension Environment variable: |
string |
|
The Session Datasource extension Environment variable: |
string |
|
The Timer Facility extension Environment variable: |
string |
|
The Agent Redirect extension Environment variable: |
string |
|
The Agent Configuration extension Environment variable: |
string |
|
The Agent Proxy extension Environment variable: |
string |
|
The Overload Manager extension Environment variable: |
string |