kamailio/modules/cdp

The CDP Module

Dragos Vingarzan

Fraunhofer

Edited by

Jason Penton

Edited by

Richard Good

Copyright � 2006 FhG Fokus

Copyright � 2012 Smile Communications
__________________________________________________________________

Table of Contents

1. Admin Guide

1. Overview
2. How it works
3. Dependencies

3.1. Kamailio Modules
3.2. External Libraries or Applications

4. Parameters

4.1. config_file (string)
4.2. latency_threshold (int)

5. RPC Commands

5.1. cdp.disable_peer
5.2. cdp.enable_peer

6. Configuration Examples

6.1. DiameterPeer.xml example
6.2.

2. Developer Guide

1. Available Functions

1.1. load_cdp(struct cdp_binds *cdpb)
1.2. AAACreateRequest(AAAApplicationId app_id,
AAACommandCode command_code, AAAMsgFlag flags,
AAASession *session)

1.3. AAACreateResponse(AAAMessage *request)
1.4. AAAReturnCode AAAFreeMessage(AAAMessage **msg)
1.5. AAAReturnCode AAASendMessage(AAAMessage *message,
AAATransactionCallback_f *callback_f, void
*callback_param)

1.6. AAAReturnCode AAASendMessageToPeer(AAAMessage *message,
str *peer_id, AAATransactionCallback_f *callback_f,
void *callback_param)

1.7. AAAMessage* AAASendRecvMessage(AAAMessage *message)
1.8. AAAMessage* AAASendRecvMessageToPeer(AAAMessage
*message, str *peer_id)

1.9. AAASession* AAACreateSession(void *generic_data)
1.10. AAASession* AAAMakeSession(int app_id,int type,str
session_id)

1.11. AAASession* AAAGetSession(str id)
1.12. AAADropSession(AAASession *s)
1.13. AAASessionLock(unsigned int hash)
1.14. AAASessionUnLock(unsigned int hash)
1.15. AAASession* AAACreateClientAuthSession(int
is_statefull,AAASessionCallback_f *cb,void
*generic_data)

1.16. AAASession* AAACreateServerAuthSession(AAMessage
*msg,int is_statefull,AAASessionCallback_f *cb,void
*generic_data)

1.17. AAASession* AAAGetAuthSession(str id)
1.18. AAADropAuthSession(AAASession *s)
1.19. AAATerminateAuthSession(AAASession *s)
1.20. AAATransaction* AAACreateTransaction(AAAApplicationId
app_id,AAACommandCode cmd_code)

1.21. int AAADropTransaction(AAATransaction *trans)
1.22. AAA_AVP* AAACreateAVP(AAA_AVPCode code, AAA_AVPFlag
flags, AAAVendorId vendorId, char *data, size_t
length, AVPDataStatus data_status)

1.23. AAAReturnCode AAAAddAVPToMessage(AAAMessage *msg,
AAA_AVP *avp, AAA_AVP *position)

1.24. AAA_AVP* AAAFindMatchingAVP(AAAMessage *msg, AAA_AVP
*startAvp, AAA_AVPCode avpCode, AAAVendorId
vendorId, AAASearchType searchType)

1.25. AAA_AVP * AAAGetNextAVP(AAA_AVP *avp)
1.26. AAAReturnCode AAAFreeAVP(AAA_AVP **avp)
1.27. str AAAGroupAVPS(AAA_AVP_LIST avps)
1.28. AAA_AVP_LIST AAAUnGroupAVPS(str buf)
1.29. AAA_AVP* AAAFindMatchingAVPList(AAA_AVP_LIST avpList,
AAA_AVP *startAvp, AAA_AVPCode avpCode, AAAVendorId
vendorId, AAASearchType searchType)

1.30. AAAFreeAVPList(AAA_AVP_LIST *avpList)
1.31. int AAAAddRequestHandler(AAARequestHandler_f *f,void
*param)

1.32. int AAAAddResponseHandler(AAAResponseHandler_f *f,void
*param)

3. Frequently Asked Questions

List of Examples

1.1. Set config_file parameter
1.2. Set latency_threshold parameter
1.3. DiameterPeer.xml example

Chapter 1. Admin Guide

Table of Contents

1. Overview
2. How it works
3. Dependencies

3.1. Kamailio Modules
3.2. External Libraries or Applications

4. Parameters

4.1. config_file (string)
4.2. latency_threshold (int)

5. RPC Commands

5.1. cdp.disable_peer
5.2. cdp.enable_peer

6. Configuration Examples

6.1. DiameterPeer.xml example
6.2.

1. Overview

CDP (C Diameter Peer) allows Diameter communication to and from
Kamailio. Most of the code is inherited from DISC
http://developer.berlios.de/projects/disc/ and OpenIMS and modified for
use within Kamailio. A few improvements and new functionality has been
added along the way, for example, threshold reporting on Diameter calls
that are serviced above a certain threshold.

2. How it works

CDP forks the following processes:
* 1 x Timer
* 1 x Acceptor
* k x Workers (k configurable through configuration)
* i x Receivers (one for each peer plus one for unknown peers)

CDP is really only an API and offers all of its methods to other
modules. No commands are made available to the main Kamailio
configuration file. The exported API can be seen in mod.c. The Full
Diameter API is in diameter.h and diameter_api.h. IMS-specific
constants can be found in diameter_ims.h. The protocol coding is
implemented in diameter_avp.c and diameter_msg.c. The diameter state
machine is implemented in peerstatemachine.c - there is one of these
for each peer which maintains all protocol/application state for each
peer. peermanager.c is responsible for peer administration. Diameter
transactions are implemented in transaction.c.

There are 2 configuration areas for CDP. Firstly it must be loaded and
configured in the Kamailio.cfg file (this is the normal task associated
with Kamailio modules). Then, an XML file is required to configure
various Diameter parameters and all related peers and the associated
routes.

3. Dependencies

3.1. Kamailio Modules
3.2. External Libraries or Applications

3.1. Kamailio Modules

The following modules must be loaded before this module:
* None.

3.2. External Libraries or Applications

The following libraries or applications must be installed before
running Kamailio with this module loaded:
* None.

4. Parameters

4.1. config_file (string)
4.2. latency_threshold (int)

4.1. config_file (string)

This is the location of the XML configuration file.

Default value is "DiameterPeer.xml".

Example 1.1. Set config_file parameter
...
modparam("cdp", "config_file", "/etc/kamailio/diametercfg.xml")
...

4.2. latency_threshold (int)

The time in ms above which a log error is wrtten to log file for long
CDP transactions.

Default value is "500".

Example 1.2. Set latency_threshold parameter
...
modparam("cdp", "latency_threshold", 1000)
...

5. RPC Commands

5.1. cdp.disable_peer
5.2. cdp.enable_peer

exported RPC commands.

5.1. cdp.disable_peer

instantly disable a particular diameter peer.

5.2. cdp.enable_peer

enabe/re-enable a diameter peer

6. Configuration Examples

6.1. DiameterPeer.xml example
6.2.

6.1. DiameterPeer.xml example

This is an example CDP configuration file. The location of this file is
configured as a CDP parameter (config_file) - See section 4.1 Above

Example 1.3. DiameterPeer.xml example


FQDN="pcscf.ims.smilecoms.com"
Realm="ims.smilecoms.com"
Vendor_Id="10415"
Product_Name="CDiameterPeer"
AcceptUnknownPeers="0"
DropUnknownOnDisconnect="1"
Tc="30"
Workers="4"
QueueLength="32"
ConnectTimeout="5"
TransactionTimeout="5"
SessionsHashSize="128"
DefaultAuthSessionTimeout="60"
MaxAuthSessionTimeout="300"
>







































Chapter 2. Developer Guide

Table of Contents

1. Available Functions

1.1. load_cdp(struct cdp_binds *cdpb)
1.2. AAACreateRequest(AAAApplicationId app_id, AAACommandCode
command_code, AAAMsgFlag flags, AAASession *session)

1.3. AAACreateResponse(AAAMessage *request)
1.4. AAAReturnCode AAAFreeMessage(AAAMessage **msg)
1.5. AAAReturnCode AAASendMessage(AAAMessage *message,
AAATransactionCallback_f *callback_f, void
*callback_param)

1.6. AAAReturnCode AAASendMessageToPeer(AAAMessage *message, str
*peer_id, AAATransactionCallback_f *callback_f, void
*callback_param)

1.7. AAAMessage* AAASendRecvMessage(AAAMessage *message)
1.8. AAAMessage* AAASendRecvMessageToPeer(AAAMessage *message, str
*peer_id)

1.9. AAASession* AAACreateSession(void *generic_data)
1.10. AAASession* AAAMakeSession(int app_id,int type,str
session_id)

1.11. AAASession* AAAGetSession(str id)
1.12. AAADropSession(AAASession *s)
1.13. AAASessionLock(unsigned int hash)
1.14. AAASessionUnLock(unsigned int hash)
1.15. AAASession* AAACreateClientAuthSession(int
is_statefull,AAASessionCallback_f *cb,void *generic_data)

1.16. AAASession* AAACreateServerAuthSession(AAMessage *msg,int
is_statefull,AAASessionCallback_f *cb,void *generic_data)

1.17. AAASession* AAAGetAuthSession(str id)
1.18. AAADropAuthSession(AAASession *s)
1.19. AAATerminateAuthSession(AAASession *s)
1.20. AAATransaction* AAACreateTransaction(AAAApplicationId
app_id,AAACommandCode cmd_code)

1.21. int AAADropTransaction(AAATransaction *trans)
1.22. AAA_AVP* AAACreateAVP(AAA_AVPCode code, AAA_AVPFlag flags,
AAAVendorId vendorId, char *data, size_t length,
AVPDataStatus data_status)

1.23. AAAReturnCode AAAAddAVPToMessage(AAAMessage *msg, AAA_AVP
*avp, AAA_AVP *position)

1.24. AAA_AVP* AAAFindMatchingAVP(AAAMessage *msg, AAA_AVP
*startAvp, AAA_AVPCode avpCode, AAAVendorId vendorId,
AAASearchType searchType)

1.25. AAA_AVP * AAAGetNextAVP(AAA_AVP *avp)
1.26. AAAReturnCode AAAFreeAVP(AAA_AVP **avp)
1.27. str AAAGroupAVPS(AAA_AVP_LIST avps)
1.28. AAA_AVP_LIST AAAUnGroupAVPS(str buf)
1.29. AAA_AVP* AAAFindMatchingAVPList(AAA_AVP_LIST avpList,
AAA_AVP *startAvp, AAA_AVPCode avpCode, AAAVendorId
vendorId, AAASearchType searchType)

1.30. AAAFreeAVPList(AAA_AVP_LIST *avpList)
1.31. int AAAAddRequestHandler(AAARequestHandler_f *f,void *param)
1.32. int AAAAddResponseHandler(AAAResponseHandler_f *f,void
*param)

1. Available Functions

1.1. load_cdp(struct cdp_binds *cdpb)
1.2. AAACreateRequest(AAAApplicationId app_id, AAACommandCode
command_code, AAAMsgFlag flags, AAASession *session)

1.3. AAACreateResponse(AAAMessage *request)
1.4. AAAReturnCode AAAFreeMessage(AAAMessage **msg)
1.5. AAAReturnCode AAASendMessage(AAAMessage *message,
AAATransactionCallback_f *callback_f, void *callback_param)

1.6. AAAReturnCode AAASendMessageToPeer(AAAMessage *message, str
*peer_id, AAATransactionCallback_f *callback_f, void
*callback_param)

1.7. AAAMessage* AAASendRecvMessage(AAAMessage *message)
1.8. AAAMessage* AAASendRecvMessageToPeer(AAAMessage *message, str
*peer_id)

1.9. AAASession* AAACreateSession(void *generic_data)
1.10. AAASession* AAAMakeSession(int app_id,int type,str session_id)
1.11. AAASession* AAAGetSession(str id)
1.12. AAADropSession(AAASession *s)
1.13. AAASessionLock(unsigned int hash)
1.14. AAASessionUnLock(unsigned int hash)
1.15. AAASession* AAACreateClientAuthSession(int
is_statefull,AAASessionCallback_f *cb,void *generic_data)

1.16. AAASession* AAACreateServerAuthSession(AAMessage *msg,int
is_statefull,AAASessionCallback_f *cb,void *generic_data)

1.17. AAASession* AAAGetAuthSession(str id)
1.18. AAADropAuthSession(AAASession *s)
1.19. AAATerminateAuthSession(AAASession *s)
1.20. AAATransaction* AAACreateTransaction(AAAApplicationId
app_id,AAACommandCode cmd_code)

1.21. int AAADropTransaction(AAATransaction *trans)
1.22. AAA_AVP* AAACreateAVP(AAA_AVPCode code, AAA_AVPFlag flags,
AAAVendorId vendorId, char *data, size_t length, AVPDataStatus
data_status)

1.23. AAAReturnCode AAAAddAVPToMessage(AAAMessage *msg, AAA_AVP *avp,
AAA_AVP *position)

1.24. AAA_AVP* AAAFindMatchingAVP(AAAMessage *msg, AAA_AVP *startAvp,
AAA_AVPCode avpCode, AAAVendorId vendorId, AAASearchType
searchType)

1.25. AAA_AVP * AAAGetNextAVP(AAA_AVP *avp)
1.26. AAAReturnCode AAAFreeAVP(AAA_AVP **avp)
1.27. str AAAGroupAVPS(AAA_AVP_LIST avps)
1.28. AAA_AVP_LIST AAAUnGroupAVPS(str buf)
1.29. AAA_AVP* AAAFindMatchingAVPList(AAA_AVP_LIST avpList, AAA_AVP
*startAvp, AAA_AVPCode avpCode, AAAVendorId vendorId,
AAASearchType searchType)

1.30. AAAFreeAVPList(AAA_AVP_LIST *avpList)
1.31. int AAAAddRequestHandler(AAARequestHandler_f *f,void *param)
1.32. int AAAAddResponseHandler(AAAResponseHandler_f *f,void *param)

1.1. load_cdp(struct cdp_binds *cdpb)

Find and load the CDiameterPeer function bindings

Meaning of the parameters is as follows:
* struct cdp_binds *cdpb - structure holding function pointers

1.2. AAACreateRequest(AAAApplicationId app_id, AAACommandCode command_code,
AAAMsgFlag flags, AAASession *session)

Create a Diameter request

Meaning of the parameters is as follows:
* AAAApplicationId app_id - structure holding function pointers
* AAACommandCode command_code - command code for the message
* AAAMsgFlag flags - flags to be set
* AAASession *session - session id to be set

1.3. AAACreateResponse(AAAMessage *request)

Create a Diameter response to a give request

Meaning of the parameters is as follows:
* AAAMessage *request - request that this response is for

1.4. AAAReturnCode AAAFreeMessage(AAAMessage **msg)

Free up memory used by Diameter message

Meaning of the parameters is as follows:
* AAAMessage **msg - pointer to the pointer containing the message

1.5. AAAReturnCode AAASendMessage(AAAMessage *message,
AAATransactionCallback_f *callback_f, void *callback_param)

Send Diameter message asynchronously

Meaning of the parameters is as follows:
* AAAMessage *message - request message to be sent
* AAATransactionCallback_f *callback_f - When the response is
received, the callback_f(callback_param,...) is called
* void *callback_param - generic param for callback

1.6. AAAReturnCode AAASendMessageToPeer(AAAMessage *message, str *peer_id,
AAATransactionCallback_f *callback_f, void *callback_param)

Send Diameter message to specific peer asynchronously

Meaning of the parameters is as follows:
* AAAMessage *message - request message to send
* str *peer_id - FQDN of peer to send to
* AAATransactionCallback_f *callback_f - When the response is
received, the callback_f(callback_param,...) is called
* void *callback_param - generic param for callback

1.7. AAAMessage* AAASendRecvMessage(AAAMessage *message)

Send Diameter message synchronously. This blocks until a response is
received or a transactional time-out happens.

Meaning of the parameters is as follows:
* AAAMessage *message - request message to be sent

1.8. AAAMessage* AAASendRecvMessageToPeer(AAAMessage *message, str *peer_id)

Send Diameter message to specific peer synchronously. This blocks until
a response is received or a transactional time-out happens.

Meaning of the parameters is as follows:
* AAAMessage *message - request message to send
* str *peer_id - FQDN of peer to send to.

1.9. AAASession* AAACreateSession(void *generic_data)

Create a generic Diameter session

Meaning of the parameters is as follows:
* void *generic_data - data to be save to session, useful for
attaching app specific data to the session

1.10. AAASession* AAAMakeSession(int app_id,int type,str session_id)

Create a Diameter session using already known params

Meaning of the parameters is as follows:
* int app_id - app id to use
* int type - type of session
* str session_id - session ID

1.11. AAASession* AAAGetSession(str id)

Retrieve a Diameter session. Returns with a lock on AAASession->hash -
Unlock when done working with result

Meaning of the parameters is as follows:
* str id - Diameter session ID to search for

1.12. AAADropSession(AAASession *s)

Drop a Diameter session - deallocating all memory

Meaning of the parameters is as follows:
* AAASession *s - session to drop

1.13. AAASessionLock(unsigned int hash)

Lock a Diameter session (hash table row)

Meaning of the parameters is as follows:
* unsigned int hash - hash to lock

1.14. AAASessionUnLock(unsigned int hash)

Unlock a Diameter session (hash table row)

Meaning of the parameters is as follows:
* unsigned int hash - hash to unlock

1.15. AAASession* AAACreateClientAuthSession(int
is_statefull,AAASessionCallback_f *cb,void *generic_data)

Creates an Authorisation session for the Client. It generate a new ID
and adds to the list of CDP sessions. Returns with a lock on
AAASession->hash

Meaning of the parameters is as follows:
* int is_statefull - is session stateful or not
* AAASessionCallback_f *cb - callback function on session state
change
* void *generic_data - generic callback data

1.16. AAASession* AAACreateServerAuthSession(AAMessage *msg,int
is_statefull,AAASessionCallback_f *cb,void *generic_data)

Create authorisation session for the Server. Generates a new ID and add
to CDP list of sessions. Returns with a lock on AAASession->hash.

Meaning of the parameters is as follows:
* AAMessage *msg - request message from which to create server
session
* int is_statefull - is session stateful or not
* AAASessionCallback_f *cb - callback function on session state
change
* void *generic_data - generic callback data

1.17. AAASession* AAAGetAuthSession(str id)

Look for an authorisation session. Returns with lock on
AAASession->hash

Meaning of the parameters is as follows:
* str id - ID of Auth session to search for

1.18. AAADropAuthSession(AAASession *s)

Deallocates the memory taken by a Authorisation session

Meaning of the parameters is as follows:
* AAASession *s - Session to drop and deallocate memory for

1.19. AAATerminateAuthSession(AAASession *s)

Sends a service terminated event to the session

Meaning of the parameters is as follows:
* AAASession *s - authhorisation session to terminate

1.20. AAATransaction* AAACreateTransaction(AAAApplicationId
app_id,AAACommandCode cmd_code)

Create a AAATransaction for the given request

Meaning of the parameters is as follows:
* AAAApplicationId app_id - ID of the request's application
* AAACommandCode cmd_code - request's code

1.21. int AAADropTransaction(AAATransaction *trans)

Deallocates the memory taken by AAA transaction

Meaning of the parameters is as follows:
* AAATransaction *trans - transaction to free

1.22. AAA_AVP* AAACreateAVP(AAA_AVPCode code, AAA_AVPFlag flags, AAAVendorId
vendorId, char *data, size_t length, AVPDataStatus data_status)

Create new AVP and return pointer to it

Meaning of the parameters is as follows:
* AAA_AVPCode code - code for new AVP
* AAA_AVPFlag flags - flags to set
* AAAVendorId vendorId - vendor ID for AVP
* char *data - generic payload data
* size_t length - length of payload data
* AVPDataStatus data_status - what to do with the payload, duplicate,
free with message, etc

1.23. AAAReturnCode AAAAddAVPToMessage(AAAMessage *msg, AAA_AVP *avp, AAA_AVP
*position)

Find and load the CDiameterPeer function bindings

Meaning of the parameters is as follows:
* AAAMessage *msg - the message to add to
* AAA_AVP *avp - the AVP to add
* AAA_AVP *position - AVP to add after. if NULL, we add at beginning

1.24. AAA_AVP* AAAFindMatchingAVP(AAAMessage *msg, AAA_AVP *startAvp,
AAA_AVPCode avpCode, AAAVendorId vendorId, AAASearchType searchType)

Find and load the CDiameterPeer function bindings

Meaning of the parameters is as follows:
* AAAMessage *msg - the message to search in
* AAA_AVP *startAvp - at which AVP to start the search. usefull for
looking for more of the same name
* AAA_AVPCode avpCode - AVP code to match
* AAAVendorId vendorId - AVP vendor ID to match
* AAASearchType searchType - look forward or backward

1.25. AAA_AVP * AAAGetNextAVP(AAA_AVP *avp)

Find and load the CDiameterPeer function bindings

Meaning of the parameters is as follows:
* AAA_AVP *avp - reference AVP

1.26. AAAReturnCode AAAFreeAVP(AAA_AVP **avp)

Find and load the CDiameterPeer function bindings

Meaning of the parameters is as follows:
* AAA_AVP **avp - pointer memory to be freed

1.27. str AAAGroupAVPS(AAA_AVP_LIST avps)

Groups a list of AVPS into a data buffer

Meaning of the parameters is as follows:
* AAA_AVP_LIST avps - list of AVPS to group

1.28. AAA_AVP_LIST AAAUnGroupAVPS(str buf)

Ungroup a data buffer into a list of AVPs

Meaning of the parameters is as follows:
* str buf - payload to ungroup list from

1.29. AAA_AVP* AAAFindMatchingAVPList(AAA_AVP_LIST avpList, AAA_AVP
*startAvp, AAA_AVPCode avpCode, AAAVendorId vendorId, AAASearchType
searchType)

Find an AVP in an AVP list

Meaning of the parameters is as follows:
* AAA_AVP_LIST avpList - AVP list to search
* AAA_AVP *startAvp - where to start the search
* AAA_AVPCode avpCode - AVP code to match
* AAAVendorId vendorId - vendor ID to match
* AAASearchType searchType - forwards or backwards

1.30. AAAFreeAVPList(AAA_AVP_LIST *avpList)

Free AVP list and all its members

Meaning of the parameters is as follows:
* AAA_AVP_LIST *avpList - list to be freed

1.31. int AAAAddRequestHandler(AAARequestHandler_f *f,void *param)

add a #AAARequestHandler_f callback to request being received

Meaning of the parameters is as follows:
* AAARequestHandler_f *f - callback function to be called on incoming
requests
* void *param - generic data passed to callback function

1.32. int AAAAddResponseHandler(AAAResponseHandler_f *f,void *param)

add a #AAAResponseHandler_f callback to responses being received

Meaning of the parameters is as follows:
* AAAResponseHandler_f *f - callback function to be called on
incoming responses
* void *param - generic data to be bassed to callback function

Chapter 3. Frequently Asked Questions

3.1. Where can I find more about Kamailio?
3.2. Where can I post a question about this module?
3.3. How can I report a bug?

3.1.

Where can I find more about Kamailio?

Take a look at http://www.kamailio.org/.

3.2.

Where can I post a question about this module?

First at all check if your question was already answered on one of our
mailing lists:
* User Mailing List -
http://lists.sip-router.org/cgi-bin/mailman/listinfo/sr-users
* Developer Mailing List -
http://lists.sip-router.org/cgi-bin/mailman/listinfo/sr-dev

E-mails regarding any stable Kamailio release should be sent to
and e-mails regarding development
versions should be sent to .

If you want to keep the mail private, send it to
.

3.3.

How can I report a bug?

Please follow the guidelines provided at:
http://sip-router.org/tracker.