Settings.xml ============ .. contents:: :local: :depth: 3 The SIPIS configuration file is an XML file defined by the following schema. .. code-block:: xml … … … … … … … … … … … … … … … … ``Sipis[Defaults]`` (Since 3.50) This attribute specifies a path to another settings file. If this attribute is specified, sipis will first load the referenced file and then overwrite or add attributes specified in the current settings file. Relative paths are resolved relative to the path of the current settings file. .. note:: This simple overwriting mechanism works only for attributes with unique absolute path in the XML file. In particular, this mechanism WILL NOT work for attributes of lists of same-named elements. ``Sipis/Server`` ---------------- This element defines properties of the UDP server that processes SIPIS messages coming from softphones and also common properties of SIP clients running inside SIPIS. .. code-block:: xml .. _label-sipis-settings-servername: ``Sipis/Server[Name]`` Each SIPIS must be assigned a unique name. This name is used in a few SQL queries. ``Sipis/Server[Address, Port]`` These attributes specify address and port where SIPIS will accept connections from LoadBalancer2. Use 0.0.0.0 as a “don't care” value. ``Sipis/Server[Transport]`` (Since 4.1) This attribute specifies whether connections between SIPIS and LoadBalancer2 are encrypted or not. Possible values are ``Tcp`` and ``Tls``. Default value: ``Tcp``. ``Sipis/Server[PublicAddress]`` When specified, this address is used instead of a socket's local address in the ``Via`` and ``Contact`` SIP headers if a VoIP provider prohibits local addresses in those headers (DiscoverGlobalIP=Yes). ``Sipis/Server[PrivateAddress]`` When specified, this address is used instead of a socket's local address in the ``Via`` and ``Contact`` SIP headers if a VoIP provider permits local addresses in those headers (DiscoverGlobalIP=No). .. note:: In case SIPIS is hosted on a machine with only a public interface it is advisable to specify an arbitrary private address in the ``Sipis/Server[PrivateAddress]`` attribute. This allows sipis to properly simulate being behind NAT, which helps interoperability with certain service providers. ``Sipis/Server[Realm]`` (Since 3.50) This attribute specifies the realm parameter of the digest authentication mechanism. If not specified ``Sipis/Server[Name]`` is used instead. ``Sipis/Server[FilterInstancesAccordingToLoadBalancer2BackendSection]`` (Since 3.50) If this attribute is set to ``Yes``, then, during restart, SIPIS will load from the restart table only instances whose selector matches the corresponding ``LoadBalancer2/Backend/Sipis`` entry from the ``/etc/acrobits/LoadBalancer2/Settings.xml`` file. The corresponding entry is found by matching the ``Sipis/Server[Name]`` and ``LoadBalancer2/Backend/Sipis[Name]`` attributes. ``Sipis/HttpServer`` -------------------- The HTTP server, built into SIPIS, can be used to display various server statistics in a web browser. Use `http://\:\/stats` URI to access these statistics. .. code-block:: xml ``Sipis/HttpServer[Address]`` This attribute specifies an IPv4 address the HTTP server binds to. Use 0.0.0.0 as a “don't care” value. ``Sipis/HttpServer[Port]`` This attribute specifies a port number the HTTP server binds to. ``Sipis/HttpServer[AuthenticationMethod]`` (Since 3.59) This attribute specifies authentication method used to resrict access to server statistics. Possible values are ``None``, ``Basic`` and ``Digest``. Default value: ``Digest``. ``Sipis/Administrator`` ----------------------- This element specifies administrator’s credentials required to perform actions via the built-in HTTP server. Note that some (most) web browsers will cache the entered credentials and will use these cached values whenever a server issues another challenge — in other words, they will not ask the user for the credentials ever again. It is therefore advisable not to leave the administrator's workstation unattended. .. code-block:: xml ``Sipis/Administrator[UserName]`` This attribute specifies administrator's user name. ``Sipis/Administrator[Password]`` This attribute specifies administrator's password in plain text. ``Sipis/Database`` ------------------ This element provides information about the backend PostgreSQL database. When a connection to database fails, SIPIS waits one second before trying to establish a new connection to the same database. If the new connection cannot be established, SIPIS tries to connect to alternative databases in a round robin fashion, waiting one second before each connection attempt. If no database can be contacted, SIPIS retries this entire cycle ten times before it finally gives up and shuts itself down. .. code-block:: xml ``Sipis/Database[OpenString]`` This attribute specifies connection string for the global sipis database. This string is passed directly to the ``PQconnectdb`` function. ``Sipis/Database/Alternatives/Alternative[OpenString]`` (Up to 3.59) This attribute specifies an alternative database connection string which is passed directly to the ``PQconnectdb`` function. ``Sipis/Database/LoadBalancing/Database[SelectorPrefix]`` (Since 4.0) This attribute specifies selector prefix of the selector sipis database. The prefix specification consists of a string of hexadecimal characters followed by slash followed by decimal number specifying the actual number of bits in the prefix. E.g. "A/3" specifies 3-bit binary prefix "101". ``Sipis/Database/LoadBalancing/Database[OpenString]`` (Since 4.0) This attribute specifies connection string for the selector sipis database. This string is passed directly to the ``PQconnectdb`` function. .. _label-foo: ``Sipis/Lock`` -------------- .. code-block:: xml ``Sipis/Lock[FileName]`` This attribute specifies a path and a file name of the lock file which is used to prevent multiple SIPIS binaries running with the same settings on the same machine. For easy identification, the file name should include the server’s name as specified in :ref:`Sipis/Server[Name]`. ``Sipis/Log`` ------------- This element specifies where SIPIS is supposed to store its diagnostic logs and what to include in them. .. code-block:: xml … … … ``Sipis/Log[Level]`` (Since 3.20) This attribute specifies the verbosity of the diagnostic log. There are three levels defined: ``Info``, ``Warning`` and ``Error``. Default value: ``Warning``. ``Sipis/Log[Stdio]`` (Since 3.20) This attribute specifies the standard stream to write the diagnostic log to. Supported values are: ``None``, ``Stdout`` and ``Stderr``. Default value: ``Stdout``. ``Sipis/Log[Format]`` (Since 3.55) This attribute specifies the format of the main diagnostic log. Supported values are: ``Plaintext`` and ``Json``. The ``Json`` format follows the JavaScript Object Notation (JSON) Text Sequences specification (https://tools.ietf.org/html/rfc7464). Default value: ``Plaintext``. ``Sipis/Log[FileName]`` (Required upto 3.19; optional since 3.20) This attribute specifies a path and a file name of the main log file. ``Sipis/Log[MaxFileSize]`` (Since 4.1) This attribute specifies maximum allowed size of the main log file. Value of zero means unbounded. Default value: ``0``. .. note:: In case of non-zero max file size value, log entries are written to the log file in a circular fashion and the format of the log file is as follows. The file begins with 8 hexadecimal characters specifying the actual ``content_end`` position. This value, together with the actual ``file_size``, can be used to unwrap the rest of the file if necessary. Example 1 (no unwrapping needed): xxxxxxxx|------------------| |0 8 |content_end = file_size content = file[8..content_end) Example 2 (unwrapping needed): xxxxxxxx|------------------|---------------------------| |0 8 |content_end |file_size content = file[content_end..file_size) + file[8..content_end) ``Sipis/Log[InstanceFormat]`` (Since 3.55) This attribute specifies the format of the instance diagnostic log. Supported values are: ``Plaintext`` and ``Json``. The ``Json`` format follows the JavaScript Object Notation (JSON) Text Sequences specification (https://tools.ietf.org/html/rfc7464). Default value: ``Plaintext``. ``Sipis/Log[InstanceFileName]`` This attribute specifies a path and a file name of an instance specific log file. The path or file name should include the ``$SELECTOR$`` placeholder which will be replaced by the actual instance selector. ``Sipis/Log[InstanceMaxFileSize]`` (Since 4.1) This attribute specifies maximum allowed size of an instance specific log file. Value of zero means unbounded. Default value: ``0``. .. note:: In case of non-zero max file size value, see note for ``Sipis/Log[MaxFileSize]``. ``Sipis/Log[ProblematicInstancesAutomatically]`` (Up to 3.41) This attribute specifies whether or not SIPIS should turn instance logging on automatically, when it detects problems with a particular instance. .. note:: This attribute has no effect since version 3.42. ``Sipis/Log/Email`` ................... SIPIS is able to send e-mails supplying an administrator with a periodically generated summary information about its logging activity or notifying an administrator about predetermined logging events. .. code-block:: xml … … ``Sipis/Log/Email[To]`` This attribute specifies an e-mail address SIPIS sends its e-mails to. ``Sipis/Log/Email[From]`` This attribute specifies an e-mail address SIPIS places in the ``From`` header field of its e-mail messages. ``Sipis/Log/Email/Summary`` ``````````````````````````` This element specifies information about periodic summary e-mails. .. code-block:: xml ``Sipis/Log/Email/Summary[Enabled]`` This attribute specifies whether or not SIPIS generates periodic summary e-mails. ``Sipis/Log/Email/Summary/Period[Days, Hours, Minutes, Seconds]`` These attributes specify a period with which SIPIS generates summary e-mails. Values in all specified attributes accumulate. ``Sipis/Log/Email/Summary/StartingAt[Hour, Minute, Second]`` These attributes specify at which time of day the period begins. ``Sipis/Log/Email/Excerpt`` ``````````````````````````` This element specifies information about specific logging events an administrator is interested in. SIPIS includes log excerpts of these events inside the generated e-mails. .. code-block:: xml ``Sipis/Log/Email/Excerpt[Enabled]`` This attribute specifies whether or not SIPIS pays attention to particular logging events. ``Sipis/Log/Email/Excerpt/MinPeriod[Days, Hours, Minutes, Seconds]`` These attributes specify the minimal period with which SIPIS will send notification e-mails. This period starts automatically whenever a logging event passes the filter for the first time after the previous notification e-mail was sent. Additional desired logging events are accumulated to be sent at once at the end of this period. ``Sipis/Log/Email/Excerpt/MaxSize[MegaBytes, KiloBytes, Bytes]`` These attributes specify the maximal size of the generated e-mail message. Values in all specified attributes accumulate. SIPIS never generates notification e-mail larger than this specified maximum size, truncating the log excerpt if necessary. ``Sipis/Log/Email/Excerpt/Filter`` ,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,, This element specifies sequence of tests all logging events pass through. These tests are performed in the same order as specified here. Each successful test overwrites a boolean variable with either true (Include rule) or false (Exclude rule) value. The starting value of this variable is true and its final value determines whether an event should be included in the log excerpt. ``Sipis/Log/Email/Excerpt/Filter/Include and Sipis/Log/Email/Excerpt/Filter/Exclude`` ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ These elements define the result of a single test performed by the logging event filter. The test succeeds when all the specified attributes match. .. code-block:: xml ``Sipis/Log/Email/Excerpt/Filter/Include[Severity]`` and ``Sipis/Log/Email/Excerpt/Filter/Exclude[Severity]`` This attribute matches the logging event's severity. Possible values are ``Debug``, ``Info``, ``Warning``, ``Error``, ``Bug`` or ``*``. ``Sipis/Log/Email/Excerpt/Filter/Include[Source]`` and ``Sipis/Log/Email/Excerpt/Filter/Exclude[Source]`` This attribute matches the logging event's source. The matching is case insensitive. ``Sipis/Log/Email/Excerpt/Filter/Include[Field]`` and ``Sipis/Log/Email/Excerpt/Filter/Exclude[Field]`` (Since 3.29) This attribute selects the logging event's field for subsequent matching. ``Sipis/Log/Email/Excerpt/Filter/Include[DetailName]`` and ``Sipis/Log/Email/Excerpt/Filter/Exclude[DetailName]`` (Since 3.29) This attribute selects the particular logging event's detail (if Field='Detail') for subsequent matching. ``Sipis/Log/Email/Excerpt/Filter/Include[StartsWith]`` and ``Sipis/Log/Email/Excerpt/Filter/Exclude[StartsWith]`` This attribute matches if the selected logging event field starts with the specified string. The matching is case insensitive. ``Sipis/Log/Email/Excerpt/Filter/Include[Contains]`` and ``Sipis/Log/Email/Excerpt/Filter/Exclude[Contains]`` This attribute matches if the selected logging event field contains the specified string. The matching is case insensitive. ``Sipis/Log/Email/Excerpt/Filter/Include[EndsWith]`` and ``Sipis/Log/Email/Excerpt/Filter/Exclude[EndsWith]`` This attribute matches if the selected logging event field ends with the specified string. The matching is case insensitive. ``Sipis/Log/Email/Excerpt/Filter/Include[Equal]`` and ``Sipis/Log/Email/Excerpt/Filter/Exclude[Equal]`` This attribute matches if the selected logging event field is equal to the specified string. The matching is case insensitive. ``Sipis/Log/Email/Excerpt/Filter/Include[NotEqual]`` and ``Sipis/Log/Email/Excerpt/Filter/Exclude[NotEqual]`` This attribute matches if the selected logging event field is not equal to the specified string. The matching is case insensitive. ``Sipis/Log/Email/Excerpt/Filter/Include[Enabled]`` and ``Sipis/Log/Email/Excerpt/Filter/Exclude[Enabled]`` This attribute specifies whether or not this rule is skipped during the filtering process. ``Sipis/Log/Http`` .................. .. code-block:: xml ``Sipis/Log/Http[RequestBody]`` This attribute specifies whether SIPIS should log HTTP request bodies. ``Sipis/Log/Http/Filter`` ````````````````````````` This element specifies sequence of tests all HTTP requests pass through. These tests are performed in the same order as specified here. Each successful test overwrites a boolean variable with either true (Include rule) or false (Exclude rule) value. The starting value of this variable is true and its final value determines whether an HTTP request should be written into the log. ``Sipis/Log/Http/Filter/Include`` and ``Sipis/Log/Http/Filter/Exclude`` ,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,, These elements define the result of a single test performed by the HTTP request filter. The test succeeds when all the specified attributes match. .. code-block:: xml ``Sipis/Log/Http/Filter/Include[Method]`` and ``Sipis/Log/Http/Filter/Exclude[Method]`` This attribute matches the HTTP request method. The matching is case insensitive. Possible values are ``GET``, ``POST`` or ``*``. ``Sipis/Log/Http/Filter/Include[Response]`` and ``Sipis/Log/Http/Filter/Exclude[Response]`` This attribute matches the HTTP response *code*. ``Sipis/Log/Http/Filter/Include[Enabled]`` and ``Sipis/Log/Http/Filter/Exclude[Enabled]`` This attribute specifies whether or not this rule is skipped during the filtering process. ``Sipis/Log/Http/Filter/Include/Header[Name]`` and ``Sipis/Log/Http/Filter/Exclude/Header[Name]`` This attribute specifies the HTTP request header name whose value is to be tested. ``Sipis/Log/Http/Filter/Include/Uri[StartsWith]``, ``Sipis/Log/Http/Filter/Exclude/Uri[StartsWith]``, ``Sipis/Log/Http/Filter/Include/Header[StartsWith]`` and ``Sipis/Log/Http/Filter/Exclude/Header[StartsWith]`` This attribute matches if the HTTP request uri or a particular header value starts with the specified string. The matching is case insensitive. ``Sipis/Log/Http/Filter/Include/Uri[Contains]``, ``Sipis/Log/Http/Filter/Exclude/Uri[Contains]``, ``Sipis/Log/Http/Filter/Include/Header[Contains]`` and ``Sipis/Log/Http/Filter/Exclude/Header[Contains]`` This attribute matches if the HTTP request uri or a particular header value contains the specified string. The matching is case insensitive. ``Sipis/Log/Http/Filter/Include/Uri[EndsWith]``, ``Sipis/Log/Http/Filter/Exclude/Uri[EndsWith]``, ``Sipis/Log/Http/Filter/Include/Header[EndsWith]`` and ``Sipis/Log/Http/Filter/Exclude/Header[EndsWith]`` This attribute matches if the HTTP request uri or a particular header value ends with the specified string. The matching is case insensitive. ``Sipis/Log/Http/Filter/Include/Uri[Equal]``, ``Sipis/Log/Http/Filter/Exclude/Uri[Equal]``, ``Sipis/Log/Http/Filter/Include/Header[Equal]`` and ``Sipis/Log/Http/Filter/Exclude/Header[Equal]`` This attribute matches if the HTTP request uri or a particular header value is equal to the specified string. The matching is case insensitive. ``Sipis/Log/Http/Filter/Include/Uri[NotEqual]``, ``Sipis/Log/Http/Filter/Exclude/Uri[NotEqual]``, ``Sipis/Log/Http/Filter/Include/Header[NotEqual]`` and ``Sipis/Log/Http/Filter/Exclude/Header[NotEqual]`` This attribute matches if the HTTP request uri or a particular header value is not equal to the specified string. The matching is case insensitive. ``Sipis/Log/Instance`` ...................... This element allows you to turn logging on for a specific instance based on its selector. .. code-block:: xml ``Sipis/Log/Instance[Selector]`` You can also specify a single star character * to turn instance logging on for all instances managed by SIPIS. ``Sipis/Log/Instance/DeleteOn[Year, Month, Day]``, ``Sipis/Log/Instance/StopOn[Year, Month, Day]`` (Since 3.42) This element specifies a date on which sipis shall stop logging activity for the specified instance. In case the DeleteOn element is used, sipis will also delete the corresponding instance log file. ``Sipis/NotificationServers`` ----------------------------- This element provides information about all Push Notification Mediator servers that are available to process push notifications generated by SIPIS. .. code-block:: xml ``Sipis/NotificationServers/NotificationServer[Name]`` Each notification server must be assigned a unique name. Moreover, this name must be known to softphone. Note this attribute is also known as AppId. ``Sipis/NotificationServers/NotificationServer[Host]`` This attribute specifies a host address of the notification server. It can be FQDN. ``Sipis/NotificationServers/NotificationServer/Alternatives/Alternative[Host]`` This attribute specifies an alternative host address of the notification server. It can be FQDN. ``Sipis/NotificationServers/NotificationServer[Port]`` This attribute specifies a port number the notification server listens on. ``Sipis/NotificationServers/NotificationServer/Alternatives/Alternative[Port]`` This attribute specifies a port number the alternative notification server listens on. ``Sipis/NotificationServers/NotificationServer[RequiresTls]`` This attribute specifies whether SIPIS must use TLS to communicate with this notification server. ``Sipis/NotificationServers/NotificationServer/Alternatives/Alternative[RequiresTls]`` This attribute specifies whether SIPIS must use TLS to communicate with the alternative notification server. This attribute is optional for the alternative servers — when missing the value from the primary server is assumed. ``Sipis/NotificationServers/NotificationServer[Premium]`` This attribute specifies whether instances using this notification server should be treated as premium. ``Sipis/IgnoredAppIds`` (Since 3.20) ------------------------------------ This element provides information about applications whose requests will be ignored by SIPIS. .. code-block:: xml ``Sipis/IgnoredAppIds/AppId[Name]`` This attribute specifies the banned application's identifier (AppId). ``Sipis/TlsClientCertificates`` ------------------------------- This element provides information about all installed client certificates used for TLS negotiation. .. code-block:: xml ``Sipis/TlsClientCertificates/Certificate[Host]`` This attribute specifies FQDN of a server this certificate is intended for. ``Sipis/TlsClientCertificates/Certificate[FileName]`` This attribute specifies a path and a file name of a DER[+PEM] encoded X.509 certificate. ``Sipis/TlsClientCertificates/Certificate[RsaPrivateKeyFileName]`` This attribute specifies a path and a file name of a DER[+PEM] encoded RSA private key corresponding to this certificate. ``Sipis/TlsServerOptions`` (Since 4.1) -------------------------- This element provides information about TLS server parameters. .. note:: This element is required if ``Sipis/Server[Transport]="Tls"``. .. code-block:: xml ``Sipis/TlsServerOptions[MinVersion, MaxVersion]`` These attributes specify the range of acceptable TLS versions. Possible values are ``1.0``, ``1.1`` and ``1.2``. Default value: ``1.2``. ``Sipis/TlsServerOptions[MinRsaModulusSizeInBits, MinDhModulusSizeInBits]`` These attributes specify minimum acceptable modulus size for RSA and Diffie–Hellman calculations. Default value: ``1024``. ``Sipis/TlsServerOptions/CipherSuites`` This element specifies list of enabled TLS cipher suites. For possible values see ``TlsCipherSuiteType`` definition in the full scheme at the and of this document. ``Sipis/TlsServerOptions/EllipticCurves`` This element specifies list of enabled elliptic curves. For possible values see ``TlsEllipticCurveType`` definition in the full scheme at the and of this document. ``Sipis/TlsServerOptions/Certificate[Host]`` and ``Sipis/TlsServerOptions/PrivateKey[Host]`` This attribute specifies FQDN that will be matched against the Server Name Indication TLS extension. ``Sipis/TlsServerOptions/Certificate[FileName]`` This attribute specifies a path and a file name of a DER[+PEM] encoded X.509 certificate. ``Sipis/TlsServerOptions/PrivateKey[FileName]`` This attribute specifies a path and a file name of a DER[+PEM] encoded private key. ``Sipis/TrustedCertificates`` ----------------------------- This element provides information about trusted certificates. These are primarily used for verifying TLS server certificates. .. note:: This element is optional; when absent, SIPIS **doesn't verify** TLS server certificates. .. code-block:: xml ``Sipis/TrustedCertificates[FileName]`` This attribute specifies a path and a file name of a bundle of PEM encoded X.509 certificates. Individual certificates are expected to be delimited by .. code-block:: none -----BEGIN CERTIFICATE----- ⋮ -----END CERTIFICATE----- ``Sipis/Instance`` ------------------ .. code-block:: xml … ``Sipis/Instance[UserAgent]`` This attribute specifies the string used by SIPIS to populate the SIP User-Agent header. Default value: "Acrobits SIPIS (www.acrobits.net)". ``Sipis/Instance[EnableToHeaderMismatch]`` This attribute specifies global override of the "enable To header mismatch" option. Default value: Supplied by clients during registration. ``Sipis/Instance[AllowSipProxiesWithPrivateIpAddresses]`` (Since 3.33) This attribute specifies whether SIPIS should accept instances whose SIP proxy setting contain private IP address. Default value: ``Yes``. .. note:: Older versions of SIPIS don't accept instances whose SIP proxy setting contain private IP address. ``Sipis/Instance[EnableDnsAaaa]`` (Since 3.45) By default, SIPIS will NOT try to discover IPv6 addresses of SIP proxies. The reason is simply that, in general, the number of "working" mixed IPv4/IPv6 scenarios is greater when sipis is communicating with a SIP backend via IPv4 interface. This attribute allows the addministrator to revert the default behavior. ``Sipis/Instance[KeepOnlyTheMostRecentDeviceToken]`` (Since 3.49) When set to ``Yes``, SIP client instances will store only the most recently received device token and as a consequence will send push notifications only to the single device which communicated with SIPIS most recently. ``Sipis/Instance[LocalAddress]`` (Since 3.53) This attribute allows the administrator to specify IP address of a local interface to be used for SIP traffic. ``Sipis/Instance[MaxSubsequentUnauthorizedCount]`` (Since 3.54) This attribute specifies the maximum allowed number of subsequent registration attempts resulting in "unauthorized" response from the SIP backend. When this number is reached, SIPIS will automatically turn the SIP client instance off. Default value: ``12``. ``Sipis/Instance[MaxMissedCallCount]`` (Since 4.1) This attribute specifies the maximum number of unreported missed calls SIPIS will keep track of. When this number is reached, SIPIS will start discarding records about the oldest missed calls. Default value: ``100``. ``Sipis/Instance/MaxAge[Days, Hours, Minutes, Seconds]`` These attributes specify a period of softphone's inactivity after which SIPIS will turn the corresponding SIP client instance off. Values in all specified attributes accumulate. ``Sipis/Instance/PremiumMaxAge[Days, Hours, Minutes, Seconds]`` These attributes specify a period of softphone's inactivity for premium instances after which SIPIS will turn the corresponding SIP client instance off. Values in all specified attributes accumulate. ``Sipis/Instance/NotRegisteredMaxAge[Days, Hours, Minutes, Seconds]`` These attributes specify a period after which SIPIS will turn a SIP client instance off, if the SIP client instance was unable to register successfully at least once during that period. Values in all specified attributes accumulate. Default value: 12 hours. ``Sipis/Instance/ErrorRecoveryDelay[Days, Hours, Minutes, Seconds]`` and ``Sipis/Instance/ErrorRecoveryMaxDelay[Days, Hours, Minutes, Seconds]`` (Since 3.54) These attributes specify a delay a SIP client instance will wait before attempting to register itself with the SIP backend after failed attempt. Values in all specified attributes accumulate. The actual delay value is taken randomly from the interval [(specified delay), 2 * (specified delay)]. Subsequent failed attempts will INCREASE the current delay by another random value taken from the same interval. The delay value is capped by the max delay setting, so when the cap is reached the subsequent delay values will be always chosen randomly from the interval [(specified max delay) - (specified delay), (specified max delay)]. Default values: 10 minutes and 1 hour. ``Sipis/Instance/UnauthorizedRecoveryDelay[Days, Hours, Minutes, Seconds]`` and ``Sipis/Instance/UnauthorizedRecoveryMaxDelay[Days, Hours, Minutes, Seconds]`` (Since 3.54) These attributes specify a delay a SIP client instance will wait before attempting to register itself with the SIP backend after previous attempt failed with "unauthorized" response. Values in all specified attributes accumulate. The actual delay value is taken randomly from the interval [(specified delay), 2 * (specified delay)]. Subsequent failed attempts will INCREASE the current delay by another random value taken from the same interval. The delay value is capped by the max delay setting, so when the cap is reached the subsequent delay values will be always chosen randomly from the interval [(specified max delay) - (specified delay), (specified max delay)]. Default values: 10 minutes and 1 hour. ``Sipis/Instance/AboutToExpireIn[Days, Hours, Minutes, Seconds]``, ``Sipis/Instance/AboutToExpireIn/Silent[Days, Hours, Minutes, Seconds]`` (Since 3.20) and ``Sipis/Instance/AboutToExpireIn/Intrusive[Days, Hours, Minutes, Seconds]`` (Since 3.20) These attributes specify how long in advance will SIPIS send the "About To Expire" push notification to clients. Values in all specified attributes accumulate. (Since 3.20) SIPIS sends two versions of the "About To Expire" push notification: silent and intrusive. These can be sent on independent schedule. ``Sipis/Instance/AboutToExpirePeriod[Days, Hours, Minutes, Seconds]``, ``Sipis/Instance/AboutToExpirePeriod/Silent[Days, Hours, Minutes, Seconds]`` (Since 3.20) and ``Sipis/Instance/AboutToExpirePeriod/Intrusive[Days, Hours, Minutes, Seconds]`` (Since 3.20) These attributes specify a period at which SIPIS resends the "About To Expire" push notification. Values in all specified attributes accumulate. (Since 3.20) SIPIS sends two versions of the "About To Expire" push notification: silent and intrusive. These can be sent on independent schedule. Default value: Is equal to AboutToExpireIn. I.e. by default, the "About To Expire" notification is sent just once. ``Sipis/Instance/NotifyBannedPeriod[Days, Hours, Minutes, Seconds]`` (Since 4.1) These attributes specify a period at which SIPIS resends push notifications about an instance being banned on the SIPIS server. Values in all specified attributes accumulate. Banned instance will unregister from the PBX and therefore will not be able to receive incoming calls. The ban duration is taken uniformly from the range between 3 to 4 hours. Afterwards the banned instance is unbanned automatically to see if things improved. If not, the instance will get banned again. Default value: 7 days. .. note:: The most common reason for an instance getting banned is too frequent "pings" from PBXes. ``Sipis/Instance/MaxSipClientTransactionsPerTenMinutes[Total, Ack, Bye, Cancel, Info, Invite, Message, Notify, Options, Prack, Publish, Refer, Register, Subscribe, Update]``, ``Sipis/Instance/MaxSipServerTransactionsPerTenMinutes[Total, Ack, Bye, Cancel, Info, Invite, Message, Notify, Options, Prack, Publish, Refer, Register, Subscribe, Update]`` (Since 3.51) These attributes allow the administrator to specify limits on frequency of SIP transaction. When a limit is reached, the offending instance is banned for about three hours. During the ban period the instance doesn't process any SIP transactions. ``Sipis/Instance/KeepAlivePackets`` ................................... .. code-block:: xml ``Sipis/Instance/KeepAlivePackets[Enabled]`` This attribute specifies whether or not SIP client instances running inside SIPIS will send keep alive packets. ``Sipis/Instance/KeepAlivePackets/Period[Days, Hours, Minutes, Seconds]`` These attributes specify a period between keep alive packets sent by SIP client instances running inside SIPIS. Values in all specified attributes accumulate. ``Sipis/IncomingCall`` ---------------------- .. code-block:: xml ``Sipis/IncomingCall[PostponeRingingResponseUntilDeviceIsMakingProgress]`` (Since 3.36) This attribute specifies whether SIPIS should postpone sending the "180 Ringing" provisional response until it receives a positivie signal from a device. Default value: ``No``. .. note:: When set to ``Yes``, callers may experience prolonged period of silence before they can hear the ringback tone. ``Sipis/IncomingCall/DeviceNotMakingProgressMaxAge[Days, Hours, Minutes, Seconds]`` (Since 3.50) These attributes specify a period after which SIPIS will hang up an incoming call automatically, if no user's device notifies sipis that it is about to answer the call within that period. Values in all specified attributes accumulate. Default value: 2 minutes. ``Sipis/IncomingCall/NotAnsweredMaxAge[Days, Hours, Minutes, Seconds]`` (Until 3.50) These attributes specify a period after which SIPIS will hang up an incoming call automatically, if the call is not answered within that period. Values in all specified attributes accumulate. (Since 3.50) These attributes specify a period after which SIPIS will hang up an incoming call automatically, if user's device notified sipis that it is about to answer the call but fails to do so within that period. Values in all specified attributes accumulate. Default value: 2 minutes. ``Sipis/IncomingCall/OnAlertingDevice`` (Since 3.54) This element allows the administrator to specify provisional SIP response SIPIS will send to the SIP proxy immediately after it initiates push notification about the incoming call. Setting the ``Code`` attribute to empty string disables provisional response for this event. Default value: ``180 Ringing`` with ``X-Sipis-Push-Status: Alerting-Device`` header. ``Sipis/IncomingCall/OnPushNotificationSent`` (Since 3.54) This element allows the administrator to specify provisional SIP response SIPIS will send to the SIP proxy when it receives confirmation from pnmediator that its push notification about the incoming call has been accepted by the platform specific push notification service (APNS or FCM). Setting the ``Code`` attribute to empty string disables provisional response for this event. Default value: ``180 Ringing`` with ``X-Sipis-Push-Status: Push-Notification-Sent`` header. ``Sipis/IncomingCall/OnDeviceMakingProgress`` (Since 3.54) This element allows the administrator to specify provisional SIP response SIPIS will send to the SIP proxy when it receives confirmation from some user's device that it received the push notification about the incoming call and is alerting the user. Setting the ``Code`` attribute to empty string disables provisional response for this event. Default value: ``180 Ringing`` with ``X-Sipis-Push-Status: Device-Making-Progress`` header. ``Sipis/IncomingCall/OnNoResponseFromDevice`` (Since 3.54) This element allows the administrator to specify final SIP response SIPIS will send to the SIP proxy when it doesn't receive any signal from user's device within ``DeviceNotMakingProgressMaxAge`` time period. Default value: ``480 Temporarily Unavailable`` with ``X-Sipis-Reason: No-Response-From-Device`` header. ``Sipis/IncomingCall/OnNoResponseFromUser`` (Since 3.54) This element allows the administrator to specify final SIP response SIPIS will send to the SIP proxy when it does receive confirmation from some user's device but the user doesn't answer the incoming call within ``NotAnsweredMaxAge`` time period. Default value: ``480 Temporarily Unavailable`` with ``X-Sipis-Reason: No-Response-From-User`` header. ``Sipis/IncomingCall/OnDeviceTokenNotFound`` (Since 3.54) This element allows the administrator to specify final SIP response SIPIS will send to the SIP proxy when it receives information from pnmediator that the device token used for the push notification about the incoming call is not longer valid (this usually signifies that the application has been uninstalled). Default value: ``410 Gone`` with ``X-Sipis-Reason: Device-Token-Not-Found`` header. ``Sipis/IncomingCall/OnPushNotificationFailure`` (Since 3.54) This element allows the administrator to specify final SIP response SIPIS will send to the SIP proxy when it receives information from pnmediator that it was unable to send push notification about the incoming call. Default value: ``480 Temporarily Unavailable`` with ``X-Sipis-Reason: Push-Notification-Failure`` header. ``Sipis/IncomingCall/OnDoNotDisturb`` (Since 3.59) This element allows the administrator to specify final SIP response SIPIS will send to the SIP proxy when incoming call is rejected because of Do Not Disturb policy. Default value: ``486 Busy Here`` with ``Warning: Sipis: Rejected because of Do Not Disturb policy.`` header. ``Sipis/IncomingTextMessage`` (Since 3.36) ------------------------------------------ .. code-block:: xml … ``Sipis/IncomingTextMessage/Filter`` (Since 3.36) ................................................. This element specifies sequence of tests all incoming SIP text messages pass through. These tests are performed in the same order as specified here. Each successful test overwrites a result variable with the specified action. The initial value of this variable is Accept. .. code-block:: xml … ``Sipis/IncomingTextMessage/Filter/Entry`` (Since 3.36) ``````````````````````````````````````````````````````` This element defines the condition and resulting action of the incoming SIP text message filter. The condition succeeds when all the specified attributes in all the Header elements match. .. code-block:: xml ``Sipis/IncomingTextMessage/Filter/Entry[Action]`` This attribute specifies the resulting action SIPIS should take when the condition succeeds. Possible values are ``Accept``, ``AcceptAndDrop`` or ``Reject``. ``Sipis/IncomingTextMessage/Filter/Entry[Enabled]`` This attribute specifies whether or not this rule is skipped during the filtering process. ``Sipis/IncomingTextMessage/Filter/Entry/Header[Name]`` This attribute specifies the SIP request header name whose value is to be tested. ``Sipis/IncomingTextMessage/Filter/Entry/Header[StartsWith]`` This attribute matches if the SIP request header value starts with the specified string. The matching is case insensitive. ``Sipis/IncomingTextMessage/Filter/Entry/Header[Contains]`` This attribute matches if the SIP request header value contains the specified string. The matching is case insensitive. ``Sipis/IncomingTextMessage/Filter/Entry/Header[EndsWith]`` This attribute matches if the SIP request header value ends with the specified string. The matching is case insensitive. ``Sipis/IncomingTextMessage/Filter/Entry/Header[Equal]`` This attribute matches if the SIP request header value is equal to the specified string. The matching is case insensitive. ``Sipis/IncomingTextMessage/Filter/Entry/Header[NotEqual]`` This attribute matches if the SIP request header value is not equal to the specified string. The matching is case insensitive. ``Sipis/IncomingTextMessage/Filter/Entry/Header[UintGt]`` This attribute matches if the SIP request header value is an unsigned integer and is greater than the specified value. ``Sipis/IncomingTextMessage/Filter/Entry/Header[UintGte]`` This attribute matches if the SIP request header value is an unsigned integer and is greater than or equal to the specified value. ``Sipis/IncomingTextMessage/Filter/Entry/Header[UintLt]`` This attribute matches if the SIP request header value is an unsigned integer and is less than the specified value. ``Sipis/IncomingTextMessage/Filter/Entry/Header[UintLte]`` This attribute matches if the SIP request header value is an unsigned integer and is less than or equal to the specified value. ``Sipis/IncomingTextMessage/Filter/Entry/RejectWith`` This element specifies the response SIPIS will send to the SIP proxy when it rejects the text message. ``Sipis/PushTest`` ------------------ .. code-block:: xml ``Sipis/PushTest/MinAge[Days, Hours, Minutes, Seconds]`` These attributes specify a minimal period for which a push test information will be retained in the database. Values in all specified attributes accumulate. Default value: 7 days. ``Sipis/DataProtection`` (Since 3.36) ------------------------------------- .. code-block:: xml ``Sipis/DataProtection[Algorithm]`` This attribute specifies the data protection algorithm SIPIS will use to protect user data (passwords and text messages). Possible values are ``Legacy`` or ``Argon2WithAes128AeadGcm``. Default value: ``Legacy``. ``Sipis/Restart`` (Since 3.42) ------------------------------ .. code-block:: xml ``Sipis/Restart[InstancesPerSecond]`` This attribute specifies the rate at which SIPIS initiates first instance SIP registration upon restart. Default value: ``4``. ``Sipis/Restart[RateLimitAppliesPerDomain]`` This attribute specifies whether the above rate limit applies globally or only among instances with the same SIP domain. Default value: ``Yes``. Complete XML schema ------------------- .. code-block:: xml Sample Settings File -------------------- .. code-block:: xml