Skip to content

Identities#

Howto's#

Defaults#

Commented File-structure#

identities.xml
<?xml version="1.0" encoding="utf-8"?>
<!-- Identities
     type: list
     minimum: 6 elements
     maximum: 6 elements -->
<identities version="1.26.11">
  <!-- Describes a single identity -->
  <identity>
    <!-- enables the identity for registration
         type: boolean -->
    <active>false</active>
    <!-- The user part of a SIP URI to register the identity
         type: string -->
    <username>5551234</username>
    <!-- The password to authenticate the identity register
         type: string -->
    <password>secretPassword</password>
    <!-- The display name of the identity
         type: string -->
    <displayname></displayname>
    <!-- The SIP registrar hostname/address
         type: string -->
    <registrar>sip.example.org</registrar>
    <!-- The SIP registrar port
         type: integer
         minimum: 1
         maximum: 65535 -->
    <registrarPort>5060</registrarPort>
    <!-- How to signal dtmf-digits:
         - rtpPayload: use event-packages in rtp-stream
         - inband: code tone-signal right into the rtp-stream
         - sipInfo: use sip-info messages
         type: enum
         accepted values:
           rtpPayload
           inband
           sipInfo -->
    <dtmfMethod>rtpPayload</dtmfMethod>
    <!-- The domain of the identity (may differ from registrar).
         There are scenarios, where the registrar is a specific host e.g sip.example.com
         but the sip participants are using a different domain e.g alice@example.org.
         In the above example, the domain would be example.org.
         type: string -->
    <domain></domain>
    <!-- If true a SIP REGISTER will be send
         type: boolean -->
    <sendRegister>true</sendRegister>
    <!-- Timeout of registration in minutes
         type: integer
         minimum: 5
         maximum: 60 -->
    <registerInterval>30</registerInterval>
    <!-- Timeout of subscriptions in minutes. Shorter values can produce a significant performance impact.
         type: integer
         minimum: 1
         maximum: 120 -->
    <subscriptionInterval>45</subscriptionInterval>
    <!-- What to do when a subscription fails. -->
    <subscriptionFailureHandling>
      <!-- When to retry: either never, or every xy seconds (linear) or quadratic (i.e. first wait xy seconds, if that retry fails wait 2 times xy seconds, if that fails wait 4 times as long until another attempt).
           type: enum
           accepted values:
             never
             linear
             quadratic -->
      <retryType></retryType>
      <!-- Interval in seconds until a subscription is retried after it got terminated by remote. Different subscripton-failures use this setting differently. E.g. a notify with `Subscription-State: terminated` follows this setting 1:1 while a subscription-request that gets answered with `500 Server Internal Error` multiplies this setting by 10.
           type: integer
           minimum: 10 -->
      <retryInterval>180</retryInterval>
    </subscriptionFailureHandling>
    <!-- What to do when a registration fails. -->
    <registrationFailureHandling>
      <!-- When to retry: either never, or every xy seconds (linear) or quadratic (i.e. first wait xy seconds, if that retry fails wait 2 times xy seconds, if that fails wait 4 times as long until another attempt).
           type: enum
           accepted values:
             never
             linear
             quadratic -->
      <retryType>linear</retryType>
      <!-- Interval in seconds until a registration is retried after it failed.
           type: integer
           minimum: 1 -->
      <retryInterval>10</retryInterval>
    </registrationFailureHandling>
    <!-- Settings that are needed for networks where a network address translation is active -->
    <nat>
      <!-- type: enum
           accepted values:
             inactive
             active -->
      <useStunSip>inactive</useStunSip>
      <!-- type: enum
           accepted values:
             inactive
             active -->
      <useStunRtp>inactive</useStunRtp>
      <!-- interval in which keepalive packets are send. Value in seconds. Used to ensure that every network component in use is reminded, that our connection is still active.
           type: integer
           minimum: 15
           maximum: 255 -->
      <keepaliveInterval>45</keepaliveInterval>
    </nat>
    <outboundProxy>
      <!-- type: enum
           accepted values:
             inactive
             automatic
             manual -->
      <mode>inactive</mode>
      <!-- type: string -->
      <url></url>
      <!-- type: integer
           minimum: 1
           maximum: 65535 -->
      <port>5060</port>
      <!-- type: string -->
      <url2></url2>
      <!-- type: integer
           minimum: 1
           maximum: 65535 -->
      <port2>5060</port2>
    </outboundProxy>
    <!-- a set of rules, that are applied on outgoing calls and can modify the number, so that this number can be routed on the outside network. The order of the rules is important. The first matching rule is used.
         type: list
         minimum: 1 element -->
    <dialplan>
      <!-- if the pattern matches, the replace string is used. (...) defines blocks, that can be reused with $NUMBER. If three blocks are used in the pattern, we can use $1 $2 and $3 in the replace. -->
      <rule>
        <!-- a regular expression
             type: string -->
        <pattern>555-(1234)</pattern>
        <!-- type: string -->
        <replace>$1</replace>
      </rule>
    </dialplan>
    <!-- Use the dialplan when starting a call from the CallLog.
         type: boolean -->
    <useDialplanInCallLog>false</useDialplanInCallLog>
    <!-- for roaming users this setting marks wether or not a roaming user is logged in. Whenever a roaming user loggs out we clear the callists and other sensitive data. Though this setting is identity-based we do global clearing of all sensitive data.
         type: boolean -->
    <isLoggedInRoamer>false</isLoggedInRoamer>
    <!-- List of supported audio codecs. The order of the list is important. When creating a connection, the server and the client use the first codec, that is supported by both parties.
         type: list
         minimum: 1 element -->
    <audiocodecs>
      <!-- type: enum
           accepted values:
             G.711
             G.722
             G.726
             G.729
             iLBC
             speex
             opus -->
      <audiocodec>G.722</audiocodec>
      <audiocodec>G.711</audiocodec>
      <audiocodec>G.726</audiocodec>
      <audiocodec>G.729</audiocodec>
      <audiocodec>iLBC</audiocodec>
      <audiocodec>speex</audiocodec>
      <audiocodec>opus</audiocodec>
    </audiocodecs>
    <!-- When a sip-Message (an instant text-message) is received and shown: also sound an alert tone or not.
         type: boolean -->
    <messagesAlertWithSound>true</messagesAlertWithSound>
    <!-- "When clir is enabled we set the X-Privacy-Header in outgoing calls. We also change the From-Header to either:" "- say the display-name is 'anonymous'" "- have the username set to anonymous, i.e. anonymous@registrar"
         type: enum
         accepted values:
           displayAnonymous
           userAnonymous -->
    <clir>displayAnonymous</clir>
    <!-- Pbx sometimes uses P-Asserted-Identity headers to signal a transfer. This is usually not the case except
          for Auerswald PBXes. When set to true: phone re-interprets those headers as transfers if the target number
          is sufficiently different from the original number.
         type: boolean -->
    <pAssertedMightBeTransfer>true</pAssertedMightBeTransfer>
    <!-- The sip-username where the phone should subscribe to to get information about voice-messages. It is also used to make the call when trying to access these messages.
         type: string -->
    <vmb></vmb>
    <!-- plays local music on hold if a call of this identity is set on hold. When enabled, held calls will take away one audio-channel. Since our phones only have 2 channels, this will limit the number of simultaneous calls to two.
         type: boolean -->
    <localmoh>false</localmoh>
    <!-- Activates sips (SIP over TLS) on connections with this identity. Most likely you have to provide a certificate for the host you provided to be able to connect safely and successfully.
         type: boolean -->
    <secureConnection>false</secureConnection>
    <!-- Use ICE to determine audio-connection. Disable this when ICE is not needed/used, this helps our SipStack to add the correct IP in sdp-offers, especially in VPN-scenarios.
         type: boolean -->
    <useIce>false</useIce>
    <!-- This option controls whether the IP address in SDP should be replaced with the IP address found in Via header of the REGISTER response, ONLY when STUN and ICE are not used. If the value is FALSE (the original behavior), then the local IP address will be used. If TRUE, and when STUN and ICE are disabled, then the IP address found in registration response will be used.
         type: boolean -->
    <sdpNatRewriteUse>true</sdpNatRewriteUse>
    <!-- This option controls whether the IP address in SDP should be determined by resolving the interface by the registar address.
         this can be useful if an registar is only available on a not primarily routed network, for example vpn
         type: boolean -->
    <sdpInterfaceDetection>false</sdpInterfaceDetection>
    <!-- type: enum
         accepted values:
           mandatory
           optional
           disabled -->
    <srtp>disabled</srtp>
    <!-- SIPS scheme is used if activated. Means the whole SIP path must be encrypted by TLS
         type: boolean -->
    <Peer2PeerTls>false</Peer2PeerTls>
    <!-- X509 certificate in PEM format
         type: string -->
    <certificate></certificate>
    <!-- used as pre code for the user part in an invite URI in case of a pickup szenario. e.g. '##06'
         type: string -->
    <pickupCode></pickupCode>
    <!-- When set, overwrites the country-specific dial-tone you hear when lifting the handset. Uses an internal tone-generator-syntax called CPT. e.g. 425@-6;(*/0/1).
         See https://wiki.auerswald.de/comfortel-d-series/developer/cpt/
         type: string -->
    <dialTone></dialTone>
    <!-- type: enum
         accepted values:
           IpV4
           IpV6
           IpAuto -->
    <ipVersion>IpAuto</ipVersion>
    <!-- optional authentication username used by some of the providers
         type: string -->
    <authenticationUsername></authenticationUsername>
    <!-- protocol used for network traffic
         type: enum
         accepted values:
           udp
           tcp -->
    <protocolType>tcp</protocolType>
    <!-- use timeout for SIP sessions
         type: boolean -->
    <sessionTimerActive>true</sessionTimerActive>
    <!-- timeout for SIP sessions in minutes
         type: integer
         minimum: 2
         maximum: 255 -->
    <sessionTimerValue>15</sessionTimerValue>
    <!-- the identity which this one is the fallback for (if the actual one cannot register) 0 := this is not a fallback identity
         type: integer
         maximum: 6 -->
    <fallbackFor>0</fallbackFor>
    <!-- ringtone assigned to this identity
         type: string -->
    <ringtone>SystemDefaultRingtone</ringtone>
    <!-- when a party wants two way early media, this setting sets the mic to muted.
         The mute will be released automatically when the call is connected.
         type: boolean -->
    <startEarlyMediaMuted>false</startEarlyMediaMuted>
    <!-- The sip-uri or number of an conference bridge. When configured conferences will be started in that bridge instead of locally.
         type: string -->
    <conferenceBridge>3344</conferenceBridge>
    <!-- when the dialscreen is opened, and a call will be created for this identity
         the input method will be set accoring to this setting
         type: boolean -->
    <startDialscreenAlphanumeric>false</startDialscreenAlphanumeric>
    <!-- PjSip-option contactRewriteUse (google for more details). Controls how often the send contact-header gets
         changed. Defaults to 2 (lots), set to 0 to have it all but fixed or 1 for an intermediate state.
         type: integer
         maximum: 2 -->
    <rewriteContact>2</rewriteContact>
    <!-- Specify the number of seconds to refresh the client registration
         before the registration expires.
         The value should be lower than the configured registration time.
         This setting is ignored when useHalvedExpiry is enabled.
         type: integer
         minimum: 5
         maximum: 3600 -->
    <earlyRefreshRegOffset>5</earlyRefreshRegOffset>
    <!-- Send re-register after the halved expiry duration elapsed
         type: boolean -->
    <useHalvedExpiry>false</useHalvedExpiry>
  </identity>
</identities>