This section describes optional configuration options, particularly for
ensuring conformance with other IMS devices such as HSSes, ENUM servers,
application servers with strict requirements on Record-Route headers,
and non-Clearwater I-CSCFs. These options should be set in the
/etc/clearwater/shared_config file (in the format name=value,
e.g. icscf=5052).
homestead_provisioning_port - the HTTP port the Homestead
provisioning interface listens on. Defaults to 8889. Not needed when
using an external HSS.
sas_server - the IP address or hostname of your Metaswitch
Service Assurance Server for call logging and troubleshooting.
Optional.
reg_max_expires - determines the maximum expires= parameter
Sprout will set on Contact headers at registrations, and therefore
the amount of time before a UE has to re-register - must be less than
2^31 ms (approximately 25 days). Default is 300 (seconds).
sub_max_expires - determines the maximum Expires header Sprout
will set in subscription responses, and therefore the amount of time
before a UE has to re-subscribe - must be less than 2^31 ms
(approximately 25 days).
upstream_hostname - the I-CSCF which Bono should pass requests
to. Defaults to icscf.<sprout_hostname>.
upstream_port - the port on the I-CSCF which Bono should pass
requests to. Defaults to 5052. If set to 0, Bono will use SRV
resolution of the upstream_hostname hostname to determine a
target for traffic.
sprout_rr_level - this determines how the Sprout S-CSCF adds
Record-Route headers. Possible values are:
pcscf - a Record-Route header is only added just after
requests come from or go to a P-CSCF - that is, at the start of
originating handling and the end of terminating handlingpcscf,icscf - a Record-Route header is added just after
requests come from or go to a P-CSCF or I-CSCF - that is, at the
start and end of originating handling and the start and end of
terminating handlingpcscf,icscf,as - a Record-Route header is added after requests
come from or go to a P-CSCF, I-CSCF or application server - that
is, at the start and end of originating handling, the start and
end of terminating handling, and between each application server
invoked
force_hss_peer - when set to an IP address or hostname, Homestead
will create a connection to the HSS using this value, but will still
use the hss_realm and hss_hostname settings for the
Destination-Host and Destination-Realm Diameter AVPs. This is useful
when your HSS’s Diameter configuration does not match the DNS
records.
hss_mar_lowercase_unknown - some Home Subscriber Servers
(particularly old releases of OpenIMSCore HSS) expect the string
‘unknown’ rather than ‘Unknown’ in Multimedia-Auth-Requests when
Clearwater cannot tell what authentication type is expected. Setting
this option to ‘Y’ will make Homestead send requests in this format.
hss_mar_force_digest - if Clearwater cannot tell what
authentication type a subscriber is trying to use, this forces it to
assume ‘SIP Digest’ and report that in the Multimedia-Auth-Request,
rather than ‘Unknown’.
hss_mar_force_aka - if Clearwater cannot tell what authentication
type a subscriber is trying to use, this forces it to assume
‘Digest-AKA-v1’ and report that in the Multimedia-Auth-Request,
rather than ‘Unknown’.
force_third_party_reg_body - if the HSS does not allow the
IncludeRegisterRequest/IncludeRegisterResponse fields (which were
added in 3GPP Rel 9) to be configured, setting
force_third_party_reg_body=Y makes Clearwater behave as though
they had been sent, allowing interop with application servers that
need them.
enforce_user_phone - by default, Clearwater will do an ENUM
lookup on any SIP URI that looks like a phone number, due to client
support for user-phone not being widespread. When this option is set
to ‘Y’, Clearwater will only do ENUM lookups for URIs which have the
user=phone parameter.
enforce_global_only_lookups - by default, Clearwater will do ENUM
lookups for SIP and Tel URIs containing global and local numbers (as
defined in RFC 3966). When this option is set to ‘Y’, Clearwater will
only do ENUM lookups for SIP and Tel URIs that contain global
numbers.
hs_listen_port - the Diameter port which Homestead listens on.
Defaults to 3868.
ralf_listen_port - the Diameter port which Ralf listens on.
Defaults to 3869 to avoid clashes when colocated with Homestead.
alias_list - this defines additional hostnames and IP addresses
which Sprout or Bono will treat as local for the purposes of SIP
routing (e.g. when removing Route headers).
default_session_expires - determines the Session-Expires value
which Sprout will add to INVITEs, to force UEs to send keepalive
messages during calls so they can be tracked for billing purposes.
This cannot be set to a value less than 90 seconds, as specified in
RFC 4028, section
4.
max_session_expires - determines the maximum
Session-Expires/Min-SE value which Sprout will accept in requests.
This cannot be set to a value less than 90 seconds, as specified in
RFC 4028, sections 4 and
5.
enum_server - a comma-separated list of DNS servers which can
handle ENUM queries.
enum_suffix - determines the DNS suffix used for ENUM requests
(after the digits of the number). Defaults to “e164.arpa”
enum_file - if set (to a file path), and if enum_server is
not set, Sprout will use this local JSON file for ENUM lookups rather
than a DNS server. An example file is on our ENUM
page.
external_icscf_uri - the SIP address of the external I-CSCF
integrated with your Sprout node (if you have one).
additional_home_domains - this option defines a set of home
domains which Sprout and Bono will regard as locally hosted (i.e.
allowing users to register, not routing calls via an external trunk).
It is a comma-separated list.
billing_realm - this sets the Destination-Realm on Diameter
messages to your external CDR. CDR connections are not based on this
but on configuration at the P-CSCF (which sets the
P-Charging-Function-Addresses header).
diameter_timeout_ms - determines the number of milliseconds
Homestead will wait for a response from the HSS before failing a
request. Defaults to 200.
max_peers - determines the maximum number of Diameter peers which
Ralf or Homestead can have open connections to at the same time.
num_http_threads (Ralf/Memento) - determines the number of
threads that will be used to process HTTP requests. For Memento this
defaults to the number of CPU cores on the system. For Ralf it
defaults to 50 times the number of CPU cores (Memento and Ralf use
different threading models, hence the different defaults). Note that
for Homestead, this can only be set in
/etc/clearwater/user_settings.
num_http_worker_threads - determines the number of threads that
will be used to process HTTP requests once they have been parsed.
Only used by Memento.
ralf_diameteridentity - determines the Origin-Host that will be
set on the Diameter messages Ralf sends. Defaults to public_hostname
(with some formatting changes if public_hostname is an IPv6
address).
hs_diameteridentity - determines the Origin-Host that will be set
on the Diameter messages Homestead sends. Defaults to
public_hostname (with some formatting changes if public_hostname is
an IPv6 address).
max_call_list_length - determines the maximum number of complete
calls a subscriber can have in the call list store. This defaults to
no limit. This is only relevant if the node includes a Memento AS.
call_list_store_ttl - determines how long each call list fragment
should be kept in the call list store. This defaults to 604800
seconds (1 week). This is only relevant if the node includes a
Memento AS.
memento_disk_limit - determines the maximum size that the call
lists database may occupy. This defaults to 20% of disk space. This
is only relevant if the node includes a Memento AS. Can be specified
in Bytes, Kilobytes, Megabytes, Gigabytes, or a percentage of the
available disk. For example:
memento_disk_limit=10240 # Bytes
memento_disk_limit=100k # Kilobytes
memento_disk_limit=100M # Megabytes
memento_disk_limit=100G # Gigabytes
memento_disk_limit=45% # Percentage of available disk
memento_threads - determines the number of threads dedicated to
adding call list fragments to the call list store. This defaults to
25 threads. This is only relevant if the node includes a Memento AS.
memento_notify_url - If set to an HTTP URL, memento will make a
POST request to this URL whenever a subscriber’s call list changes.
The body of the POST request will be a JSON document with the
subscriber’s IMPU in a field named impu. This is only relevant if
the node includes a Memento AS. If empty, no notifications will be
sent. Defaults to empty.
signaling_dns_server - a comma-separated list of DNS servers for
non-ENUM queries. Defaults to 127.0.0.1 (i.e. uses dnsmasq)
target_latency_us - Target latency (in microsecs) for requests
above which
throttling
applies. This defaults to 100000 microsecs
max_tokens - Maximum number of tokens allowed in the token bucket
(used by the throttling code). This defaults to 1000 tokens
init_token_rate - Initial token refill rate of tokens in the
token bucket (used by the throttling code). This defaults to 250
tokens per second per core
min_token_rate - Minimum token refill rate of tokens in the token
bucket (used by the throttling code). This defaults to 10.0
override_npdi - Whether the I-CSCF, S-CSCF and BGCF should check
for number portability data on requests that already have the ‘npdi’
indicator. This defaults to false
exception_max_ttl - determines the maximum time before a process
exits if it crashes. This defaults to 600 seconds
check_destination_host - determines whether the node checks the
Destination-Host on a Diameter request when deciding whether it
should process the request. This defaults to true.
astaire_cpu_limit_percentage - the maximum percentage of total
CPU that Astaire is allowed to consume when resyncing memcached data
(as part of a scale-up, scale-down, or following a memcached
failure). Note that this only limits the CPU usage of the Astaire
process, and does not affect memcached’s CPU usage. Must be an
integer. Defaults to 5.
sip_blacklist_duration - the time in seconds for which SIP peers
are blacklisted when they are unresponsive (defaults to 30 seconds).
http_blacklist_duration - the time in seconds for which HTTP
peers are blacklisted when they are unresponsive (defaults to 30
seconds).
diameter_blacklist_duration - the time in seconds for which
Diameter peers are blacklisted when they are unresponsive (defaults
to 30 seconds).
snmp_ip - the IP address to send alarms to (defaults to being
unset). If this is set then Sprout, Ralf, Homestead and Chronos will
send alarms - more details on the alarms are
here. This can be a single IP address, or a
comma-separated list of IP addresses.
impu_cache_ttl - the number of seconds for which Homestead will
cache the SIP Digest from a Multimedia-Auth-Request. Defaults to 0,
as Sprout does enough caching to ensure that it can handle an
authenticated REGISTER after a challenge, and subsequent challenges
should be rare.
sip_tcp_connect_timeout - the time in milliseconds to wait for a
SIP TCP connection to be established (defaults to 2000 milliseconds).
sip_tcp_send_timeout - the time in milliseconds to wait for sent
data to be acknowledgered at the TCP level on a SIP TCP connection
(defaults to 2000 milliseconds).
session_continued_timeout_ms - if an Application Server with
default handling of ‘continue session’ is unresponsive, this is the
time that Sprout will wait (in milliseconds) before bypassing the AS
and moving onto the next AS in the chain (defaults to 2000
milliseconds).
session_terminated_timeout_ms - if an Application Server with
default handling of ‘terminate session’ is unresponsive, this is the
time that Sprout will wait (in milliseconds) before terminating the
session (defaults to 4000 milliseconds).
sas_use_signaling_interface - When this field is set to ‘Y’, SAS
traffic is routed via the signaling network, rather than the
management network.
pbxes - a comma separated list of IP address that Bono considers
to be PBXes that are incapable of registering. Non-REGISTER requests
from these addresses are passed upstream to Sprout with a
Proxy-Authorization header. It is strongly recommended that
Sprout’s non_register_authentication option is set to
if_proxy_authorization_present so that the request will be
challenged. Bono also permits requests to these addresses from the
core to pass through it.
pbx_service_route - the SIP URI to which Bono routes originating
calls from non-registering PBXes (which are identified by the
pbxes option). This is used to route requests directly to the
S-CSCF rather than going via an I-CSCF (which could change the route
header and prevent the S-CSCF from processing the request properly).
This URI is used verbatim and should almost always include the
lr, orig, and auto-reg parameters. If this option is not
specified, the requests are routed to the address specified by the
upstream_hostname and upstream_port options.
- e.g.
sip:sprout.example.com:5054;transport=tcp;lr;orig;auto-reg
non_register_authentication - controls when Sprout will challenge
a non-REGISTER request using SIP Proxy-Authentication. Possible
values are never (meaning Sprout will never challenge) or
if_proxy_authorization_present (meaning Sprout will only
challenge requests that have a Proxy-Authorization header).
ralf_threads - used on Sprout nodes, this determines how many
worker threads should be started to do Ralf request processing
(defaults to 25).
impi_store_mode - used to control how Sprout stores
authentication challenges. The default is impi which means that
challenges are written to a single memcached database table indexed
by IMPI. There is another option, av-impi, where challenges are
also stored in an old table indexed by (IMPI, nonce). This setting
can be used to upgrade Clearwater to use the new database table
without losing registration state.
nonce_count_supported - when set to ‘Y’ Clearwater permits
authentication responses with a nonce-count greater than 1. By
default this option is not enabled. Enabling this option can expose
certain security holes if your deployment does not use an HSS (and
uses Homestead-Prov instead) and an I-CSCF. Specifically if the
option is set and a malicious UE manages to register:
- Without an HSS there is no way to force it to become deregistered.
- Without an I-CSCF there is no way to prevent it from registering
as different user accounts.