Configuring an Application Server¶
This document explains how to configure an application server for use in a Clearwater deployment.
Network configuration¶
Each application server must be able to communicate with Sprout and Bono in both directions.
- The application server must be able to contact all sprout and bono nodes on the trusted SIP ports, 5054 and 5058 (respectively, for both TCP and UDP).
- All sprout and bono nodes must be able to contact the application server on the port and protocol configured in your subscribers’ iFCs (typically TCP and UDP port 5060).
- The application server must also be able to exchange SIP messages (in both directions) with any other application server that may appear in the signaling path of any call going through it.
- Since the application server is in the trusted zone, it should not be accessible to untrusted SIP entities.
If Clearwater and your application server are both in the Amazon EC2
cloud, you can achieve all of these by placing the application server in
the <deployment>-sprout
security group.
Application server configuration¶
No special application server configuration is required.
- Your application server should be prepared to accept SIP messages from any of your deployment’s bono or sprout nodes, and from any SIP entity that may appear in the signaling path of any call going through it.
- If your application server needs to spontaneously originate calls, it
should do this via Sprout’s trusted interface:
sprout.<deployment-domain>:5054
over either TCP or UDP.
The headers set by Clearwater are described in the Application Server Guide.
iFC configuration¶
To configure a subscriber to invoke your application server, you must configure the appropriate iFCs for that subscriber. You can do this via the Ellis UI, the Homestead API, or if you are using an HSS, directly in the HSS.
Web UI configuration via Ellis¶
Ellis allows you to specify a mapping between application server names
and XML nodes. This is done by editing the
/usr/share/clearwater/ellis/web-content/js/app-servers.json
file,
which is in
JSON
format. An example file would be:
{
"MMTEL" : "<InitialFilterCriteria><Priority>0</Priority><TriggerPoint><ConditionTypeCNF></ConditionTypeCNF><SPT><ConditionNegated>0</ConditionNegated><Group>0</Group><Method>INVITE</Method><Extension></Extension></SPT></TriggerPoint><ApplicationServer><ServerName>sip:mmtel.example.com</ServerName><DefaultHandling>0</DefaultHandling></ApplicationServer></InitialFilterCriteria>",
"Voicemail" : "<InitialFilterCriteria><Priority>1</Priority><TriggerPoint><ConditionTypeCNF></ConditionTypeCNF><SPT><ConditionNegated>0</ConditionNegated><Group>0</Group><Method>INVITE</Method><Extension></Extension></SPT></TriggerPoint><ApplicationServer><ServerName>sip:vm.example.com</ServerName><DefaultHandling>0</DefaultHandling></ApplicationServer></InitialFilterCriteria>"
}
Once this is saved, the list of application server names will appear in the Ellis UI (on the ‘Application Servers’ tab of the Configure dialog), and selecting or deselecting them will add or remove the relevant XML from Homestead. This change takes effect immediately. If an node in the iFC XML is not included in app-servers.json, Ellis will leave it untouched.
Direct configuration via cURL¶
You can also configure iFCs directly using Homestead.
Here is an example of how to use curl
to configure iFCs directly.
This configures a very basic iFC, which fires on INVITEs only, with no
conditions on session case. See an iFC reference for more details, e.g.,
3GPP TS
29.228
appendices B and F.
To simplify the following commands, define the following variables - set the user, application server(s), and Homestead name as appropriate for your deployment.
user=sip:6505550269@example.com
as_hostnames="as1.example.com mmtel.example.com" # the list of zero or more application servers to invoke - don't forget mmtel
hs_hostname=hs.example.com:8888
Be careful - the user must be exactly right, including the sip:
prefix, and also +1
if and only if it is a PSTN line. We have seen
problems with PSTN lines; if the above syntax does not work, try
URL-encoding the user, e.g., for +16505550269@example.com write
user=sip%3A%2B16505550269%40example.com
.
To retrieve the current configuration, invoke curl
as follows. You
must be able to access $hs_hostname; check your firewall configuration.
curl http://$hs_hostname:8889/public/$user/service_profile
This will return a 303 if the user exists, with the service profile URL in the Location header, e.g.
Location: /irs/<irs-uuid>/service_profiles/<service-profile-uuid>
Then invoke curl
as follows, using the values from the Location
header retrieved above:
curl http://$hs_hostname:8889/irs/<irs-uuid>/service_profiles/<service-profile-uuid>/filter_criteria
To update the configuration, invoke curl
as follows. The first stage
builds the new XML document and the second pushes it to the server.
{ cat <<EOF
<?xml version="1.0" encoding="UTF-8"?>
<ServiceProfile>
EOF
for as_hostname in $as_hostnames ; do
cat <<EOF
<InitialFilterCriteria>
<Priority>1</Priority>
<TriggerPoint>
<ConditionTypeCNF>0</ConditionTypeCNF>
<SPT>
<ConditionNegated>0</ConditionNegated>
<Group>0</Group>
<Method>INVITE</Method>
<Extension></Extension>
</SPT>
</TriggerPoint>
<ApplicationServer>
<ServerName>sip:$as_hostname</ServerName>
<DefaultHandling>0</DefaultHandling>
</ApplicationServer>
</InitialFilterCriteria>
EOF
done
cat <<EOF
</ServiceProfile>
EOF
} | curl -X PUT http://$hs_hostname:8889/irs/<irs-uuid>/service_profiles/<service-profile-uuid>/filter_criteria --data-binary @-
The subscriber will now have the desired configuration. You can confirm this by running the retrieval command again.
SIP-over-UDP configuration¶
While our default configuration for Clearwater deployments is to send SIP over TCP, it is possible to create a SIP-over-UDP deployment, with certain restrictions.
Restrictions¶
If you want to create a SIP-over-UDP deployment, it will be necessary for all of Sprout’s SIP peers to send SIP over UDP to it. It is not possible to set up some peers to use TCP and some to use UDP. This is because Sprout won’t do UDP/TCP interworking.
Configuration¶
To enable SIP-over-UDP, you will need to set the following configuration options.
In shared_config
set or update the fields:
scscf_uri="sip:scscf.<sprout_hostname>;transport=udp"
disable_tcp_switch=Y
In /etc/clearwater/local_config
set or update the field on each of
your Sprout nodes:
scscf_node_uri="sip:<local_ip>:5054;transport=udp"
You may also need to:
- Set up your P-CSCF and any application servers to send SIP over UDP.
- Add new SRV entries to your DNS server for your Application Server.
- Add
transport=udp
to your Application Server’s SIP URI on your HSS.
You should now be able to make calls where SIP is sent over UDP.