Skip to content

Commit

Permalink
Rebuild documentation
Browse files Browse the repository at this point in the history
  • Loading branch information
@opensips-github
opensips-github committed Mar 2, 2024
1 parent d5a7f5d commit 48e0a4c
Show file tree
Hide file tree
Showing 20 changed files with 422 additions and 445 deletions.
198 changes: 162 additions & 36 deletions modules/aaa_diameter/README
View file
Original file line number Diff line number Diff line change
Expand Up @@ -6,29 +6,37 @@ AAA_DIAMETER MODULE
1. Admin Guide

1.1. Overview
1.2. Dependencies
1.2. Diameter Client
1.3. Diameter Server
1.4. Dependencies

1.2.1. OpenSIPS Modules
1.2.2. External Libraries or Applications
1.4.1. OpenSIPS Modules
1.4.2. External Libraries or Applications

1.3. Exported Parameters
1.5. Exported Parameters

1.3.1. fd_log_level (integer)
1.3.2. realm (string)
1.3.3. peer_identity (string)
1.3.4. aaa_url (string)
1.3.5. answer_timeout (integer)
1.5.1. fd_log_level (integer)
1.5.2. realm (string)
1.5.3. peer_identity (string)
1.5.4. aaa_url (string)
1.5.5. answer_timeout (integer)

1.4. Exported Functions
1.6. Exported Functions

1.4.1. dm_send_request(app_id, cmd_code, avps_json,
1.6.1. dm_send_request(app_id, cmd_code, avps_json,
[rpl_avps_pv])

1.5. Exported Asyncronous Functions
1.6.2. dm_send_answer(avps_json, [is_error])

1.5.1. dm_send_request(app_id, cmd_code, avps_json,
1.7. Exported Asyncronous Functions

1.7.1. dm_send_request(app_id, cmd_code, avps_json,
[rpl_avps_pv])

1.8. Exported Events

1.8.1. E_DM_REQUEST

2. Contributors

2.1. By Commit Statistics
Expand All @@ -55,27 +63,63 @@ AAA_DIAMETER MODULE
1.6. Setting the answer_timeout parameter
1.7. dictionary.opensips extended syntax
1.8. dm_send_request usage
1.9. dm_send_request asynchronous usage
1.9. dm_send_answer() usage
1.10. dm_send_request asynchronous usage

Chapter 1. Admin Guide

1.1. Overview

This module provides a Diameter implementation for the core AAA
API interface.
This module provides an RFC 6733 Diameter peer implementation,
being able to act as either Diameter client or server, or both.

Any module that wishes to use it has to do the following:
* include aaa.h
* make a bind call with a proper Diameter-specific URL, e.g.
"diameter:freeDiameter-client.conf"

1.2. Dependencies
1.2. Diameter Client

The module implements the core AAA OpenSIPS interface, thus
offering an alternative client implementation to the aaa_radius
module which can be useful, for example, when performing
billing and accounting for the live SIP calls.

In addition to the RADIUS client's auth and accounting
features, the Diameter client includes support for sending
arbitrary Diameter requests, further opening up the scope of
applications which can be achieved through OpenSIPS scripting.
Such Diameter requests can be sent using the dm_send_request()
function.

1.3. Diameter Server

Starting with OpenSIPS 3.5, the Diameter module includes
server-side support as well.

First, the event_route module must be loaded in order to be
able to process E_DM_REQUEST events in the OpenSIPS
configuration file. These events will contain all necessary
information on the incoming Diameter request.

Finally, once the request information is processed and the
answer AVPs are prepared, script writers should use the
dm_send_answer() function in order to reply with a Diameter
answer message.

Recommendation: When possible, always load the dict_sip.fdx
freeDiameter extension module inside your freeDiameter.conf
configuration file, as it contains hundreds of well-known AVP
definitions which may be good to have when inter-operating with
other Diameter peer implementations.

1.2.1. OpenSIPS Modules
1.4. Dependencies

1.4.1. OpenSIPS Modules

None.

1.2.2. External Libraries or Applications
1.4.2. External Libraries or Applications

All Diameter message building and parsing, as well as the peer
state machine and Diameter-related network communication are
Expand All @@ -87,9 +131,9 @@ Chapter 1. Admin Guide
* libfdcore v1.2.1 or higher
* libfdproto v1.2.1 or higher

1.3. Exported Parameters
1.5. Exported Parameters

1.3.1. fd_log_level (integer)
1.5.1. fd_log_level (integer)

This parameter measures the quietness of the logging done by
the freeDiameter library. Possible values:
Expand All @@ -108,7 +152,7 @@ Chapter 1. Admin Guide
modparam("aaa_diameter", "fd_log_level", 0)


1.3.2. realm (string)
1.5.2. realm (string)

The unique realm to be used by all participating Diameter
peers.
Expand All @@ -120,7 +164,7 @@ modparam("aaa_diameter", "fd_log_level", 0)
modparam("aaa_diameter", "realm", "opensips.org")


1.3.3. peer_identity (string)
1.5.3. peer_identity (string)

The identity (realm subdomain) of the Diameter server peer, to
which the OpenSIPS Diameter client peer will connect.
Expand All @@ -132,7 +176,7 @@ modparam("aaa_diameter", "realm", "opensips.org")
modparam("aaa_diameter", "peer_identity", "server")


1.3.4. aaa_url (string)
1.5.4. aaa_url (string)

URL of the diameter client: the configuration file, with an
optional extra-avps-file, where the Diameter client is
Expand All @@ -152,19 +196,21 @@ modparam("aaa_diameter", "aaa_url", "diameter:freeDiameter-client.conf;e
xtra-avps-file:dictionary.opensips")


1.3.5. answer_timeout (integer)
1.5.5. answer_timeout (integer)

Time, in milliseconds, after which a dm_send_request() function
call with no received reply will time out and return a -2 code.

Default value is 2000 ms.

Example 1.6. Setting the answer_timeout parameter

modparam("aaa_diameter", "answer_timeout", 5000)


1.4. Exported Functions
1.6. Exported Functions

1.4.1. dm_send_request(app_id, cmd_code, avps_json, [rpl_avps_pv])
1.6.1. dm_send_request(app_id, cmd_code, avps_json, [rpl_avps_pv])

Perform a blocking Diameter request over to the interconnected
peer and return the Result-Code AVP value from the reply.
Expand All @@ -178,7 +224,7 @@ modparam("aaa_diameter", "answer_timeout", 5000)
dictionary.opensips Diameter configuration file beforehand.
body of the HTTP response.
* avps_json (string) - A JSON Array containing the AVPs to
include in the message payload.
include in the message.
* rpl_avps_pv (var, optional) - output variable which will
hold all AVP names from the Diameter Answer along with
their values, packed as a JSON Array string. The "json"
Expand Down Expand Up @@ -286,16 +332,68 @@ xlog("rc: $var(rc), AVPs: $var(rpl_avps)\n");
$json(avps) := $var(rpl_avps);


1.5. Exported Asyncronous Functions
1.6.2. dm_send_answer(avps_json, [is_error])

Send back a Diameter answer message to the interconnected peer
in a non-blocking fashion, in response to its request.

1.5.1. dm_send_request(app_id, cmd_code, avps_json, [rpl_avps_pv])
The following fields will be automatically copied over from the
Diameter request when building the answer message:
* Application ID
* Command Code
* Session-Id AVP, if any
* Transaction-Id AVP, if any (only applies when Session-Id is
not present)

Parameters
* avps_json (string) - A JSON Array containing the AVPs to
include in the answer message (example below).
* is_error (boolean, default: false) - Set to true in order
to set the 'E' (error) bit in the answer message.

Return Codes
* 1 - Success
* -1 - Internal Error

This function can only be used from an EVENT_ROUTE.

Example 1.9. dm_send_answer() usage

event_route [E_DM_REQUEST] {
xlog("Req: $param(sess_id) / $param(app_id) / $param(cmd_code)\n");
xlog("AVPs: $param(avps_json)\n");

$json(avps) := $param(avps_json);

/* ... process the data (AVPs) ... */

/* ... and reply back with more AVPs! */
$var(ans_avps) = "[
{ \"Vendor-Specific-Application-Id\": [{
\"Vendor-Id\": 0
}] },

{ \"Result-Code\": 2001 },
{ \"Auth-Session-State\": 0 },
{ \"Origin-Host\": \"opensips.diameter.test\" },
{ \"Origin-Realm\": \"diameter.test\" }
]";

if (!dm_send_answer($var(ans_avps)))
xlog("ERROR - failed to send Diameter answer\n");
}


1.7. Exported Asyncronous Functions

1.7.1. dm_send_request(app_id, cmd_code, avps_json, [rpl_avps_pv])

Similar to dm_send_request() but performs an asynchronous
Diameter request.

Uses the same parameters and return codes as dm_send_request().

Example 1.9. dm_send_request asynchronous usage
Example 1.10. dm_send_request asynchronous usage

# Building an sending an My-Custom-Request (92001) for the
# My Diameter Application (42)
Expand Down Expand Up @@ -327,14 +425,42 @@ route[dm_reply] {
}


1.8. Exported Events

1.8.1. E_DM_REQUEST

This event is raised whenever the aaa_diameter module is loaded
and OpenSIPS receives a Diameter request on the configured
Diameter listening interface.

Parameters:
* app_id (integer) - the Diameter Application Identifier
* cmd_code (integer) - the Diameter Command Code
* sess_id (string) - the value of either the Session-Id AVP,
Transaction-Id AVP or a NULL value if neither of these
transaction-identifying AVPs is present in the Diameter
request.
* avps_json (string) - a JSON Array containing the AVPs of
the request. Use the json module's $json variable to easily
parse and work with it.

Note that this event is currently designed to be mainly
consumed by an event_route, since that is the only way to gain
access to the dm_send_answer() function in order to build
custom answer messages. On the other hand, if the application
does not mind the answer being always a 3001
(DIAMETER_COMMAND_UNSUPPORTED) error, this event can be
successfully consumed through any other EVI-compatible delivery
channel ☺️

Chapter 2. Contributors

2.1. By Commit Statistics

Table 2.1. Top contributors by DevScore^(1), authored
commits^(2) and lines added/removed^(3)
Name DevScore Commits Lines ++ Lines --
1. Liviu Chircu (@liviuchircu) 90 25 5921 958
1. Liviu Chircu (@liviuchircu) 109 35 6827 1089
2. Razvan Crainea (@razvancrainea) 21 11 910 109
3. Maksym Sobolyev (@sobomax) 3 1 5 5

Expand All @@ -358,8 +484,8 @@ Chapter 2. Contributors

Table 2.2. Most recently active contributors^(1) to this module
Name Commit Activity
1. Razvan Crainea (@razvancrainea) May 2023 - Dec 2023
2. Liviu Chircu (@liviuchircu) May 2021 - Dec 2023
1. Liviu Chircu (@liviuchircu) May 2021 - Feb 2024
2. Razvan Crainea (@razvancrainea) May 2023 - Dec 2023
3. Maksym Sobolyev (@sobomax) Feb 2023 - Feb 2023

(1) including any documentation-related commits, excluding
Expand All @@ -369,8 +495,8 @@ Chapter 3. Documentation

3.1. Contributors

Last edited by: Razvan Crainea (@razvancrainea), Liviu Chircu
(@liviuchircu).
Last edited by: Liviu Chircu (@liviuchircu), Razvan Crainea
(@razvancrainea).

Documentation Copyrights:

Expand Down
18 changes: 9 additions & 9 deletions modules/aaa_diameter/doc/contributors.xml
View file
Original file line number Diff line number Diff line change
Expand Up @@ -21,10 +21,10 @@
<row>
<entry>1. </entry>
<entry>Liviu Chircu (<ulink url="https://github.com/liviuchircu">@liviuchircu</ulink>)</entry>
<entry align="center">90</entry>
<entry align="center">25</entry>
<entry align="center">5921</entry>
<entry align="center">958</entry>
<entry align="center">109</entry>
<entry align="center">35</entry>
<entry align="center">6827</entry>
<entry align="center">1089</entry>
</row>
<row>
<entry>2. </entry>
Expand Down Expand Up @@ -72,13 +72,13 @@
<tbody>
<row>
<entry>1. </entry>
<entry>Razvan Crainea (<ulink url="https://github.com/razvancrainea">@razvancrainea</ulink>)</entry>
<entry align="center">May 2023 - Dec 2023</entry>
<entry>Liviu Chircu (<ulink url="https://github.com/liviuchircu">@liviuchircu</ulink>)</entry>
<entry align="center">May 2021 - Feb 2024</entry>
</row>
<row>
<entry>2. </entry>
<entry>Liviu Chircu (<ulink url="https://github.com/liviuchircu">@liviuchircu</ulink>)</entry>
<entry align="center">May 2021 - Dec 2023</entry>
<entry>Razvan Crainea (<ulink url="https://github.com/razvancrainea">@razvancrainea</ulink>)</entry>
<entry align="center">May 2023 - Dec 2023</entry>
</row>
<row>
<entry>3. </entry>
Expand All @@ -99,7 +99,7 @@
<title>Documentation</title>
<section id="documentation_contributors" xreflabel="documentation_contributors">
<title>Contributors</title>
<para><emphasis role='bold'>Last edited by:</emphasis> Razvan Crainea (<ulink url="https://github.com/razvancrainea">@razvancrainea</ulink>), Liviu Chircu (<ulink url="https://github.com/liviuchircu">@liviuchircu</ulink>).</para>
<para><emphasis role='bold'>Last edited by:</emphasis> Liviu Chircu (<ulink url="https://github.com/liviuchircu">@liviuchircu</ulink>), Razvan Crainea (<ulink url="https://github.com/razvancrainea">@razvancrainea</ulink>).</para>
</section>

</chapter>
Loading

0 comments on commit 48e0a4c

Please sign in to comment.