Provisioning: SIP

AG Projects RTC Platforms (Provisioning Guides)

This guide describes the provisioning functions for SIP.

SIP Domains

Before creating SIP accounts you need to create at least one SIP domain. (e.g. example.com)

SOAP/XML functions

• SipPort → addDomain()
• SipPort → updateDomain()
• SipPort → deleteDomain()
• SipPort → getDomains()

Graphical client

CDRTool → Accounts → SIP domains

SIP Accounts

The provisioning of SIP account is performed using the SOAP/XML functions present in the Sip port described in NGNPro WSDL.

You must add at least one SIP domain before adding a SIP account.

SIP account passwords can be stored in clear text or encrypted formats depending on how you supply the password. NGNPro needs two MD5 checksums (hexdigests) computed based on the (id.username, id.domain, password) tuple. A hexdigest must be a string of length 32, containing only hexadecimal digits. These hexdigests can be computed by the client and given to NGNPro instead of a clear text password. To use this, the password field must be in "digest1:digest2" form:

• digest1=MD5("username:domain:password")
• digest2=MD5("username@domain:domain:password")

To !not! use this, the password should be given in clear text. NGNPro computes these two digests and stores them. The configuration option store_clear_text_passwords determines how the password is stored:

• Yes (the default value): the clear text password will be also be stored,
• No: the password will not be stored and it will not be available in the future.

To enable different rights for SIP accounts, they must be part of specific groups.

You can add or remove a SIP account from a group by using Sip.addToGroup() and Sip.removeFromGroup() SOAP methods. The list of groups to which a SIP account belongs can also be set using the `groups' attribute of the SipAccount structure in Sip.addAccount() and Sip.updateAccount() methods. When you're using a group list for modification, all the old groups will be deleted and the new ones will be inserted in place.

To enable PSTN calls to a SIP account, that account must be in the free-pstn group.

If you want to limit the access to PSTN, in the margins of a predefined quota (expressed in the currency used by CDRTool rating engine), the SIP account must have a positive value set for the 'quota' attribute in the SipAccount structure. In this case, the CDRTool quota system blocks the user if the traffic exceedes the predefined quota by adding the user to the 'quota' group. In this case the SIP account can still place free calls.

A SIP account can be administratively blocked (it cannot make any calls and it cannot register thus not receiving calls), if it's part of the 'blocked' group.

If you want a SIP account to make calls marked as anonymous, that SIP account must be placed in the 'anonymous' group.

To mark a SIP account as prepaid, the 'prepaid' attribute of the SipAccount structure must be set to True.

SipAccount.properties attribute can be used to store per-account information in the form of name-value pairs and they can then be used on the client side for its own purposes. Properties do not influence routing decisions. Their meaning depends on the interpretation the client side gives them, for example they can be used from a web-based interface to store settings like the display language or the account type.

Diversion rules routing order:

1. Unavailable,
2. Unconditional
3. Not-online
4. Busy
5. No-answer

Not-online means there is no registered device for that account, Unavailable means that the subscriber has accept rules in place that forbid the caller at the current time, accept rules can be temporary (valid a a number of minutes after which they'll be discarded) or scheduled (permanent rules based on time of day and day of week).

The last 2 rules are not handled together with the other 3, they are only handled if the call fails.

SOAP/XML functions

• SipPort → addAccount()
• SipPort → updateAccount()
• SipPort → deleteAccount()
• SipPort → getAccount()
• SipPort → getAccounts()
• SipPort → addToGroup()
• SipPort → removeFromGroup()
• SipPort → getGroups()
• SipPort → addPhonebookEntry()
• SipPort → updatePhonebookEntry()
• SipPort → deletePhonebookEntry()
• SipPort → getPhonebookEntries()
• SipPort → setRejectMembers()
• SipPort → getRejectMembers()
• SipPort → setAcceptRules()
• SipPort → getAcceptRules()
• SipPort → setBarringPrefixes()
• SipPort → getBarringPrefixes()
• SipPort → setCallDiversions()
• SipPort → getCallDiversions()
• SipPort → getCalls()
• SipPort → getCallStatistics()
• SipPort → getSipDeviceLocations()

SIP account attributes:

<complexType name="SipAccount">
    −
    <sequence>
        <element name="id" nillable="false" type="ngnpro:SipId"/>
        <element name="password" nillable="true" type="xsd:string"/>
        <element name="firstName" nillable="true" type="xsd:string"/>
        <element name="lastName" nillable="true" type="xsd:string"/>
        <element name="email" nillable="true" type="xsd:string"/>
        <element name="acl" nillable="true" type="ngnpro:SubscriberACLArray"/>
        <element name="groups" nillable="true" type="ngnpro:StringArray"/>
        <element name="properties" nillable="true" type="ngnpro:PropertyArray"/>
        <element name="timezone" nillable="true" type="xsd:string"/>
        <element name="rpid" nillable="true" type="xsd:string"/>
        <element name="quota" nillable="true" type="xsd:int"/>
        <element name="quickdialPrefix" nillable="true" type="xsd:string"/>
        <element name="callLimit" nillable="true" type="xsd:int"/>
        <element name="prepaid" nillable="true" type="xsd:boolean"/>
        <element name="region" nillable="true" type="xsd:string"/>
        <element name="timeout" nillable="true" type="xsd:nonNegativeInteger"/>
        <element name="owner" nillable="true" type="xsd:integer"/>
        <element name="customer" nillable="true" type="xsd:integer"/>
        <element name="reseller" nillable="true" type="xsd:integer"/>
        <element name="changeDate" nillable="true" type="xsd:string"/>
        <element name="createDate" nillable="true" type="xsd:string"/>
    </sequence>
</complexType>

Meaning of SIP account attributes:

• rpid: caller id presented to the callee when calling to PSTN destinations
• prepaid: if true, subscriber may call within the limit of its prepaid balance, when balance is zero all calls in progress are cut
• properties: list with attribute/value pairs, used to store arbitrary data per subscriber
• quota: if set to a possitive integer, the subscriber may call to the PSTN up to this limit, calls in progress continue, the usage is reset each calendar month
• region: label that matches a region when calling an emergency number, the call is routed to the emergency point defined for that region
• callLimit: maximum amount of concurrent PSTN calls allowed
• acl: a list of allowed IP networks
• groups: group membership for SIP accounts. Available groups and their meaning:
  • free-pstn: subscriber may call to PSTN destinations
  • blocked: only calls to emergency numbers defind in the SIP Proxy are allowed
  • anonymous: hide caller id when calling to the PSTN (using Privacy headers)
  • anonymous-reject: reject calls from "anonymous@anonymous.invalid":mailto:anonymous@anonymous.invalid
  • quota: subscriber has been blocked because monthy quota has been exceeded, calls to PSTN destinations are denied
  • missed-calls: subscriber will be notifie by email about his sessions in the last 24 hours

Reserved groups for internal use (do not change them):

• prepaid, intercept

On updateAccount() operation all attributes must be supplied otherwise any missing attribute will be deleted. First perform a getAccount() operation, update the attributes that need to be changed and finally perform an updateAccount() with the modified object.

Call information functions

One can retrieve the list of calls for a given SIP account using this function:

• SipPort → getCalls(CallsQuery)

Call query attributes:

<complexType name="CallsQuery">
    <sequence>
        <element name="placed"   nillable="true" type="ngnpro:CallQuery"/>
        <element name="received" nillable="true" type="ngnpro:CallQuery"/>
    </sequence>
</complexType>

One can retrieve the SIP trace for a call by using this function:

• SipPort → getSipTrace(SipTraceFilter)

To find the trace for a SIP call, one must supply a proper filter with these paramenters:

SIP filter attributes:

<complexType name="SipTraceFilter">
    <sequence>
        <element name="nodeIp"    nillable="false" type="xsd:string"/>
        <element name="callId"    nillable="false" type="xsd:string"/>
        <element name="fromTag"   nillable="false" type="xsd:string"/>
        <element name="toTag"     nillable="true" type="xsd:string"/>
        </sequence>
</complexType>

The paramenters must be retrieved first from the CDR for the call.

One can retrieve the media information for a call by using this function:

• SipPort → getMediaTrace(MediaTraceFilter)

Media filter attributes:

<complexType name="MediaTraceFilter">
    <sequence>
    <element name="nodeIp"    nillable="false" type="xsd:string"/>
    <element name="callId"    nillable="false" type="xsd:string"/>
    <element name="fromTag"   nillable="false" type="xsd:string"/>
    <element name="toTag"     nillable="true" type="xsd:string"/>
</sequence>

The paramenters must be retrieved first from the CDR for the call.

Graphical client

CDRTool → Accounts → SIP accounts

Control panel

The above menu gives you access to various settings and information related to your SIP account.

Voicemail

This panel can set the way the voicemail messages are delivered.

Online devices

This panel displays the list of registered SIP devices.

Accept calls

This panel control when and from whom calls are accepted.

Call diversions

This panel controls the call diversions.

Call diversions data type:

<complexType name="CallDiversions">
    −
    <sequence>
        −
        <!--

            FUNC - forward unconditionally
            FNOL - forward if not online
            FUNV - forward if not available
            FNOA - forward if no answer
            FBUS - forward if busy
            RUNC - redirect unconditionally
            RNOL - redirect if not online
            RUNV - redirect if not available
            RNOA - redirect if no answer
            RBUS - redirect if busy

            - Forward conditions cause the traffic to be routed and accounted through the SIP Proxy
            - Redirect conditions cause traffic to be made directly between the caller and end destination, 
            bypassing the SIP Proxy
            - Always used FXXX conditions when accounting is desired

        -->
        <element name="FUNC" nillable="true" type="xsd:string"/>
        <element name="FNOL" nillable="true" type="xsd:string"/>
        <element name="FUNV" nillable="true" type="xsd:string"/>
        <element name="FNOA" nillable="true" type="xsd:string"/>
        <element name="FBUS" nillable="true" type="xsd:string"/>
        <element name="RUNC" nillable="true" type="xsd:string"/>
        <element name="RNOL" nillable="true" type="xsd:string"/>
        <element name="RUNV" nillable="true" type="xsd:string"/>
        <element name="RNOA" nillable="true" type="xsd:string"/>
        <element name="RBUS" nillable="true" type="xsd:string"/>
    </sequence>
</complexType>

Aliases

This panel displays the aliases associated with a SIP account.

SIP Aliases

Aliases can be used to provide custom SIP addresses that map to exiting SIP accounts.

SOAP/XML functions

• SipPort → addAlias()
• SipPort → updateAlias()
• SipPort → deleteAlias()
• SipPort → getAlias()
• SipPort → getAliasesForAccount()
• SipPort → getAliases()

Graphical client

CDRTool → Accounts → SIP aliases

Next Steps

Continue by:

• learning about Main Entities used in Provisioning; or
• learning about Provisioning: DNS; or
• learning about Provisioning: Emergency Numbers; or
• learning about Provisioning: ENUM; or
• learning about Provisioning: PSTN; or
• learning about Provisioning: Trusted Peers; or
• learning about Provisioning: User Notifications; or
• learning about Provisioning: Voicemail; or
• going back to Provisioning Introduction.