Metaswitch outbound configuration for ClearIP

ClearIP is a cloud-based solution that complements the Metaswitch CFS with a variety of services, including:

  • Analytics
  • Telecom fraud prevention
  • Robocall and TDoS prevention
  • Jurisdictional static and least cost routing
  • STIR/SHAKEN caller ID authentication and verification
  • CNAM caller ID name information

ClearIP integrates with the Metaswitch CFS using a SIP INVITE—Redirect transaction. SIP messages between the CFS and ClearIP will pass through the Metaswitch Perimeta SBC. The Perimeta will connect to ClearIP over the internet using either a TCP or TLS connection.

This documentation guides you on configuring your Metaswitch CFS and Perimeta to route outbound calls from your network to ClearIP before they are routed to an outbound trunk. These instructions assume you are familiar with using MetaView Explorer.

At the end of this page, we’ve provided a complete reference for the Remote Media Gateway model. In all configuration examples, we have highlighted values you should change to match names used in your network.

1. Create a new peering adjacency to your Perimeta SBC

Create an adjacency facing the external ClearIP service on the public internet. There’s nothing unusual about the ClearIP adjacency; just follow the standard Metaswitch documentation.

If you plan to send both outbound and inbound traffic to ClearIP, then ClearIP needs a way to distinguish between outbound and inbound calls. This can be done by setting up two adjacencies: one for outbound calls, and the other for inbound calls. You will need two publicly-addressable IP addresses, one for each adjacency. The adjacency for inbound calls should use a different source IP address than the adjacency for outbound calls.

You may want to add ClearIP’s IP range into your network’s access control list.

  • Here’s a sample Perimeta adjacency configuration for outbound calls:
    adjacency sip ClearIP Outbound
      regs 0
      regs-rate sustain 0 per-second
      media-bypass-policy forbid
    listen-transports tcp
    adjacency-type preset-peering
    mandated-transport tcp
    privacy trusted
    realm ClearIP
    service-address Service Address
      # service-network 2
      # signaling-local-address ipv4 External IP One
    signaling-local-port 5060
    remote-address-range ipv4 prefix-len 26
    signaling-peer-port 5060
    statistics-setting detail
    default-interop-profile Peer
    deactivation-mode normal

To ensure the Perimeta can resolve ClearIP’s fully-qualified domain name, please check that DNS servers have been configured. This can be done by logging into the Craft Terminal. Select Admin, then Network, then DNS. You will have the option to check the current DNS configuration, set new DNS servers, and test DNS. Please perform a test DNS lookup on If the DNS lookup is successful, you will see a confirmation message like the example below. If the DNS lookup fails, then you will see an error or timeout message and should configure a DNS server.

  • Here’s an example of a successful DNS lookup test:
    Perimeta ISC LabPerimeta is running
    This is processor-blade B; processor-blade A is contactable;
    Session Controller is partnered; processor-blade B is primary 
    [Main->Admin->Network->DNS] [=2 6 4]
      Manage the DNS server configuration
      Press ENTER to refresh
    0   Back               < Back to previous menu
    1   Get DNS info         Get the current DNS configuration
    2   Set DNS servers      Set DNS servers
    3   Set selection mode   Set server selection mode
    4   Test DNS             Perform a DNS lookup
    : 4
    Test DNS
    Perform a DNS lookup to test the configured DNS servers.
      Enter domain name to query for
    Default value is: <BLANK>
    Test DNS - Perform a DNS lookup
      Please verify that this command is correct
    1  *OK        Execute this command
    2   Cancel    Cancel this operation
    3   Modify    Modify the parameters of this command
    * 1
    Testing DNS server
    Looking up
    Using domain server:
    Aliases:  has address has address has address has address
    Testing DNS server
    Looking up
    Using domain server:
    Aliases:  has address has address has address has address
    Result: The command has completed successfully
    Press ENTER to get list of commands: 

2. Install our Remote Media Gateway model

At the bottom of this page, you’ll find the Remote Media Gateway model that you need to use for this connection. This is the same Remote Media Gateway model used for sending inbound calls to ClearIP.

Copy the text for this model and save it as a text file on your computer with name ClearIPRMGM.txt. Use WinSCP to copy this model text file to your MetaView Server (logging in to WinSCP as defcraft), saving it in the EMSftp directory. If you’re not familiar with using WinSCP, please follow the Metaswitch documentation.

In MetaView Explorer, go to Call Feature Server➔Controlled Networks➔Remote Media Gateway Models.

Find the Import field and enter the name of the file you just uploaded, ClearIPRMGM.txt.

MetaView Explorer import dialog

Press Apply, then press the Import button at the bottom of the screen. The new model should be imported.

MetaView Explorer controls

Check the Status field to see if it was successful. If not, look at the error log.

If you have trouble importing the Remove Media Gateway model, you can create it manually using the reference output at the end of this page.

3. Create a configured SIP binding for outbound calls

Follow the standard Metaswitch instructions to create a configured SIP binding.

The values should be as follows:

  • Set the Contact Domain Name as
  • Set Usage as Trunk.
  • Use 5060 as your port, with Contact Address Scheme: Domain name A/AAAA lookup.
  • Use the core network IP and port of Perimeta as your proxy IP and port.
  • Set Transport Protocol to TCP.
  • Select the remote media gateway model you imported above (TransNexus ClearIP).
  • Force validation of redirection number: False.
  • Perform translations on redirected numbers: False.
  • Select new trunk on 3xx response: True.
  • Use trunk routing tables to match TG-ID: False.
  • Return codes preventing call redirection: 486,600,603,604.

Apply the changes.

  • Here’s a sample configured SIP binding configuration for outbound calls:
    begin ConfiguredSIPBinding ConfiguredSIPBinding.536872105 // Configured SIP Binding "TransNexus ClearIP Outbound"
      Name                                           TransNexus ClearIP Outbound
      Usage                                          Trunk
      UseDNForIdentification                         True
      IPAddressMatchRequired                         False
      ContactAddressScheme                           Domain name A/AAAA lookup
      ContactIPPort                                  5060
      SupportedPreferredMediaAddressFamilies         Use default
        SupportedPreferredMediaAddressFamiliesDefaultValue IPv4
        SupportedPreferredMediaAddressFamiliesSpecificValue IPv4
      SupportedIncomingTrunkGroupParameterType       None
      TrunkGroupParameterTypeOnOutgoingMessages      None
      ProxyAddressScheme                             IP address and port
      ProxyIPAddress                                 Perimeta IP Address
      ProxyIPPort                                    5060
      TransportProtocol                              TCP
      MediaGatewayModel                              ../../MediaGatewayModelContainer/MediaGatewayModel.46 //Remote Media Gateway Model "TransNexus ClearIP"
      UseMediaIPAddressForNetworkNodeAssignment      False
      NetworkNode                                    Use default
        NetworkNodeDefaultValue                        None
        NetworkNodeSpecificValue                       None
      SIPBindingLocation                             None
      ESAProtectionDomain                            None
      Trusted                                        True
      UseCallerNameProvidedBySIPDevice               True
      PlayAnnouncementsWhenErrorConditionsOccur      False
      UseStaticNATMapping                            False
      MaximumCallAppearances                         1024
      MaximumConcurrentHighBandwidthCallAppearancesAllowed 0
      PollPeerDevice                                 True
      PollingInterval                                30
      UseCustomSIPINVITEResponseTimeout              False
      PollCallPaths                                  False
      ConcurrentNumberOfCallAppearancesInUse         0
      ConcurrentNumberOfHighBandwidthCallAppearancesInUse 0
      SuppressRedirectionInformation                 False
      ForceValidationOfRedirectionNumber             False
      PerformTranslationsOnRedirectedNumbers         False
      SelectNewTrunkOn3xxResponse                    True
      UseNormalTrunkRoutingTablesToMatchTgId         False
      ReturnCodesPreventingCallRedirection           486,600,603,604
      SignalCallingPartyLATAOnOutboundRequests       False
      DeactivationMode                               Normal
      SIPProtocolOptsHeading                         SIP protocol options
      SIPProtocolOptsSIPType                         Basic SIP
      SIPProtocolOptsDisallowSigForLRN               False
      SIPProtocolOptsAcceptTNSParam                  False
      LastCallFailure                                Last call failure
      LastCallFailureCause                           No failure
      LastCallFailureLogCorrelator                   0000 0000 0000 0000
      AlarmsHeading                                  Alarms
      FaultMonitoringProfile                         None
      AllowFMPsFromRelatedObjectsToApply             True
      AlarmState                                     Attention Required
      StatisticsAlarms                               0
      AlarmLogCorrelator                             042e 0721 ac4e b84f
      AttentionRequiredAlarmEvents                   1
      AlarmStateTimestamp                            1/16/20 3:02:28 PM
      AlarmResetTimestamp                            1/16/20 3:01:32 PM
      DiagnosticsHeading                             Diagnostics
      DiagnosticsLogLevel                            Default level
      DiagnosticsAPITraceEnabled                     False
      ExportHeading                                  Export
      StatusHeading                                  Status
      RequestedStatus                                Active
    end //ConfiguredSIPBinding

4. Create a SIP trunk

Follow the standard Metaswitch instructions to create a SIP trunk (under Signaling/SIP/SIP trunks) that uses the configured SIP binding created above for ClearIP.

The following should be configured:

  • Select an available Trunk group number.
  • Select an available Network number.
  • Set Configured SIP Binding to the SIP binding you created for ClearIP above.
  • All other fields can be left at the default values.

Apply the changes.

Metaswitch SIP trunk configuration

At this point, you’ve built the connection. You have your SIP trunk using a configured SIP binding, optionally routing through the Perimeta over to ClearIP. If you activate this configuration and wait one minute, the binding and the trunk should stay green to indicate that the SIP connection has been established.

SIP trunk has been established

5. Update trunk routing

Now that you’ve created the connection, you next need to add it into your trunk routing so that you can use ClearIP.

It is not possible to give step-by-step instructions here, as the details will depend on how your trunk routing tables are configured. Nevertheless, we’ll explain the logic so you can apply the changes to your situation.

First, as with any translations change, make a copy of your active config set, and start editing that copy.

Create a new Trunk Routing table with the following parameters:

  • Routing Table type: Destination address
  • Routing Table name: Toll calls to ClearIP
  • You can use any free Routing Table index
Trunk Routing table parameters

Now create the first Routing Action within that table with the following parameters:

  • Description: Send to ClearIP first
  • Address type: E.164
  • Address scope: Match any
  • Wildcard address type: Full wildcard - any type
  • Action: Routing complete
  • Media channel: ClearIP (found under SIP trunks)

Optional attributes:

  • AAR allowed: True
  • ARR allowed: True

You now need to decide where to place this new table in your trunk routing logic.

In a typical least cost routing application, you’ll want to route all toll calls to this SIP trunk and rely on ClearIP to return the trunk group numbers to use for each call. If ClearIP is unable to route the call for some reason, then your existing trunk routing tables will be used as backup.

If you’re using CleariP for telecom fraud detection, then you’ll want to route all toll calls to this SIP trunk. The behavior will be slightly different. If ClearIP detects fraud, then it can return a SIP 603 Decline so the call is blocked. With normal calls, ClearIP will return a SIP 404 Not Found, which will cause the Metaswitch to overflow to your standard trunk routing logic.

In either case, you’re looking for the place in your trunk routing tables where you first split off toll calls. Often your routing will start by identifying operator and 911 calls. Then perhaps you’ll have a table that identifies toll calls versus local calls. Assuming you find this place, here’s what you need to do:

  • Find the routing action that matches on toll calls and take a note of the next table parameter. Let’s say the next table is table N.
  • Modify this routing action so the next table is set to your new table, Toll calls to ClearIP.
  • Create a second routing action under the Toll calls to ClearIP table with the following parameters:
    • Address type: E.164
    • Address scope: Match any
    • Wildcard address type: Full wildcard - any type
    • Action: Table lookup
    • Next table: Routing table N
Outbound calls route to ClearIP first

As you look at the logic, you’ll see that now all toll calls route through the ClearIP table and are routed over the ClearIP SIP trunk first.

If ClearIP identifies telecom fraud, it will return a SIP 603 Decline to reject the call. If it ClearIP can route the call, it will send back a SIP 302 Moved Temporarily identifying which trunk to use. Otherwise, for normal calls, ClearIP will return a SIP 404 Not Found and the call will pass back into your existing routing logic (table N).

In some routing schemes, international calls may be split out separately from national long distance calls, in which case you’ll also want to route them to ClearIP. The simplest way to handle this is to create a duplicate Routing Table to send international calls to ClearIP, duplicating all the above logic but for international calls.

6. Testing

Once you’ve built all this configuration, you’ll want to test the solution before deploying to your entire network. In order to do this, we recommend setting up a test line and using the Overriding config set parameter on that line to use the new config set for all calls from that test line, without activating the new config set globally on the switch.

Once you’ve done that, you should work with the TransNexus team to perform some basic tests and then figure out the best plan to roll out the solution more widely to your subscribers.

A note about SIP response codes

When ClearIP rejects a call for suspected fraud, it returns a SIP 603 Decline response, indicating that the call has failed and should not be retried. The configuration described above prevents the Metaswitch from attempting to re-route these rejected calls to an overflow trunk and will set the internal Q.850 code used to track the call failure to be 21, which means call rejected.

However, if this call originally arrived at your Metaswitch over a SIP trunk (perhaps your Metaswitch is tandeming the call or it was placed from a SIP PBX) then be aware that by default the Metaswitch will send a SIP 486 Busy Here to the SIP caller (it doesn’t use the same 603 response code).

In general this is fine, but if you wish to replace that error response with something different (e.g. a 603) you can do so by modifying the Remote Media Gateway Model(s) associated with the relevant inbound Configured SIP Bindings (e.g. your network SIP trunk or SIP PBX).

On each Remote Media Gateway Model, you can explicitly request the Metaswitch to send a 603 response when using a Q.850 code of 21. To do this, find the parameter Q.850 cause code to SIP response code mapping table, and add a new line that says: 21,603

Reference: Remote Media Gateway model

begin MediaGatewayModel // Remote Media Gateway Model “TransNexus ClearIP”
  Category                                       SIP
  ModelName                                      TransNexus ClearIP
  Description                                    TransNexus ClearIP
  ControlProtocol                                SIP
  DefaultModel                                   False
  AlertInfoStringsForDistinctiveRingingHeading   Alert-Info strings for Distinctive Ringing
  NumberFormatsHeading                           Number formats
  NumberFormatsOverrideAutogeneratedCallerID     False
  SignalingSettingsHeading                       Signaling settings
  SupportedHighBandwidthMediaFormats             {G.711 u-law}
  LowBandwidthVoiceCodecsSupportedAsStandard     {}
  SupportedDataCodecs                            {}
  AdvancedVoiceCodecsPermitted                   No
  VideoCodecsPermitted                           No
  MaximumNumberOfVoiceCodecsSupported            5
  PacketizationInterval                          20
  SilenceSuppressionAllowed                      False
  MaximumSimultaneousTransactionsOutstanding     300
  DigitOverhangTime                              250
  OverrideToHeaderUserPartOnINVITEs              False
  FixBitsMGCPMeGaCoSIPMSML                       {Cannot be hub,Simple contexts,No loopback between contexts,Restricted direct media,Cannot play ringback,Cannot control endpoint connectivity,Connections always receive,Cannot report detection of call-type discrimination tones}
  DynamicFixBitsMGCPMeGaCoSIPMSML                {}
  FixBitsSIP                                     {Use E164 numbers,Include transport parameter in From header,May loop calls back to MetaSwitch,Trust number portability information (npdi),Supports receiving number portability information (npdi),Supports receiving carrier information (cic=XXXX)}
  FixBitsSIP2                                    {Supports GETS Resource-Priority header}
  FixBitsSIP3                                    {}
  FixBitsSIP4                                    {}
  SIPResponseCodeToQ850CauseCodeMappingTable     603,21
  SIPResponseCodeForESAFailure                   503
  SIPResponseCodeForCongestion                   500
  ParameterNamesForLineClassCodeHeading          Parameter names for Line Class Code
  ExportHeading                                  Export
  StatusHeading                                  Status
  RequestedStatus                                Enabled
end //MediaGatewayModel


How to configure Metaswitch for ClearIP services on inbound calls