Skip to content

Commit

Permalink
append sems general/modules/routing sections (#147)
Browse files Browse the repository at this point in the history 
* sems: Improve documentation
  • Loading branch information
@furmur
furmur authored Dec 31, 2024
1 parent dd239ae commit d5b39a5
Showing 1 changed file with 209 additions and 38 deletions.
247 changes: 209 additions & 38 deletions en/sems/sems.rst
View file
Original file line number Diff line number Diff line change
Expand Up @@ -16,10 +16,9 @@ Section **general** contains some global daemon parameters:

.. code-block:: c
:caption: general section example
general {
node_id = 8
daemon = yes
stderr = no
syslog_loglevel = 2
syslog_facility = LOCAL0
Expand All @@ -37,7 +36,7 @@ Section **general** contains some global daemon parameters:
sip_udp_server_threads = 1
sip_tcp_server_threads = 1
dead_rtp_time=30
dead_rtp_time=300
max_shutdown_time = 10
max_forwards = 70
Expand All @@ -49,55 +48,182 @@ Section **general** contains some global daemon parameters:
}
enable_srtp = yes
enable_zrtp = yes
enable_zrtp = yes
}
node_id
node_id (default: 0)
Unique node identifier. Value should be unique across cluster.

daemon
To daemonize SEMS or not

stderr
Enable logging to stderr. Usable for debug purposes.

syslog_loglevel
Logs level for syslog log destination.

syslog_facility
Syslog **facility** value

log_dump_path (default: /var/spool/sems/logdump)
Directory to save **di_log** module dumps on *core.request.log.dump* jsonrpc method call

rsr_path (default: /var/spool/sems/rsr)
Directory to save Raw SEMS Record files

pcap_upload_queue (default: empty)
destination name in the **http_client** module to automatically upload PCAP files

max_shutdown_time (default: 10)
max time in seconds to wait for sessions to cleanly end on shutdown

logging
^^^^^^^

syslog_loglevel (default: info)
Min log level for syslog log destination. allowed values: 0-5, error, warn, info, debug, debug2, debug3

syslog_facility (default: DAEMON)
Syslog **facility** value. allowed values: DAEMON, USER, LOCAL[0-7]

stderr (default: false)
Enable logging to stderr. Usable for debug purposes. Could be enabled by opt **-E**

stderr_loglevel (default: info)
Min log level for stderr log destination. allowed values: 0-5, error, warn, info, debug, debug2, debug3. Could be overridden by opt **-D <level>**

log_parsed_messages (default: true)
Whether to log parsed SIP requests in SipCtrlInterface at the DBG1 level

log_raw_messages (default: debug)
How to log raw SIP messages on send/recv. allowed values: error, warn, info, debug, debug2, debug3, no

unhandled_reply_loglevel (default: error)
How to log unhandled SIP provisional and success replies. allowed values: error, warn, info, debug, debug2, debug3, no

log_events (default: false)
Log events processing stages at the debug level

log_sessions (default: false)
Log new UAC/UAS sessions at the info level

signalling/media
^^^^^^^^^^^^^^^^

force_outbound_if (default: false)
Force interface index for outgoing SIP and RTP packets. Uses IPPROTO_IP/IP_PKTINFO.ipi_ifindex, IPPROTO_IPV6/IPV6_PKTINFO.ipi6_ifindex for sendmsg

use_raw_sockets (default: false)
Global switch to use SOCK_RAW for outgoing SIP/UDP and RTP packets

ssl_key_log_file (default: empty)
Write TLS and SRTP secrets to the specified file in SSLKEYLOG format. Useful to decrypt signalling and media in the traces collected by the external tools.

signalling
^^^^^^^^^^

session_processor_threads (default: 10)
Session processor threads count. Session processor threads handle events from the sessions events queues

sip_udp_server_threads (default: 4)
SIP UDP transport workers threads count. UDP transport workers receive UDP signalling traffic

sip_tcp_server_threads (default: 4)
SIP TCP transport workers threads count. TCP transport workers handle TCP/TLS/WS/WSS signalling traffic

sip_nat_handling (default: false)
Force SIP dialog Next Hop to be remote ip/port/trsp on requests with single Via header

proxy_sticky_auth (default: false)
Force **uac_auth** plugin to always send SIP request to the same endoint that sent auth challenge (avoid DNS and DNS SRV balancing/failover)

ignore_notify_lower_cseq (default: false)
Ignore lower CSeq value for NOTIFY requests. fixes subscription dialog usage for implementations which follow 3265 instead of 5057

accept_forked_dialogs (default: false)
Use Via-branch to match dialogs in addition to the callid+remote_tag. By default requests with different Via-branch will be matched with the same dialog.

shutdown_mode
Subsection to define behavior in shutdown mode

shutdown_mode->code
shutdown_mode.code (default: 503)
SIP error code for new initial INVITES in shutdown mode
shutdown_mode->reason

shutdown_mode.reason (default: Server shutting down)
SIP error reason for new initial INVITES in shutdown mode
shutdown_mode->allow_uac

shutdown_mode.allow_uac (default: false)
Allow new LegB creation in shutdown mode.

pcap_upload_queue
TODO

media_processor_threads
TODO
max_forwards (default: 70)
default value for the Max-Forwards header in the outgoing requests. allowed values: 1-70

session_limit.limit (default: 0)
limit active sessions count. reject incoming initial INVITES with **session_limit.code** (default: 503) **session_limit.reason** (default: Server overload). will increase **sems_sessions_limit_rejects** metric on rejects.

session_processor_threads
TODO
options_session_limit.limit (default: 0)
Reply with **options_session_limit.code** (default: 503) **options_session_limit.reason** (default: Server overload) for OPTIONS requests if active sessions count is greater than specified limit

sip_udp_server_threads
TODO

sip_tcp_server_threads
TODO
cps_limit.limit (default: 0)
limit CPS. reject incoming initial INVITES with **cps_limit.code** (default: 503) **cps_limit.reason** (default: Server overload)

dead_rtp_time
TODO
sip_timer_{name}
Override SIP timer default value in milliseconds. supported timers: A,B,D,E,F,K,G,H,I,J,L,M,C,BL

outbound_proxy (default: empty)
Use outbound proxy for all outgoing SIP requests

force_outbound_proxy (default: false)
Whether to appply **outbound_proxy** for in-dialog requests. will put outbound proxy URI at the top of the existent Route Set

force_cancel_route_set (default: false)
Add SIP dialog Route Set to CANCEL requests if true

next_hop (default: empty)
Force endpoint for SIP outgoing requests. Overrides message Next Hop lookup rules

next_hop_1st_req (default: false)
Apply **next_hop** for the first SIP request in the dialog

udp_rcvbuf (default: -1)
Set SIP/UDP socket recv buffer size (SO_RCVBUF)

100rel (default: supported)
Set rel100 behavior. allowed values: disabled, supported, require

media processing
^^^^^^^^^^^^^^^^

media_processor_threads (default: 1)
Media processor threads count. Media processor threads handle audio in the transcoding mode

rtp_receiver_threads (default: 1)
RTP receiver threads count. RTP receiver threads handle incoming RTP packets

dead_rtp_time (default: 300)
RTP timeout value in seconds. 0 means no timeout. will terminate session if no RTP packets received within **dead_rtp_time** interval

enable_srtp (default: false)
Global switch to enable SRTP processing. required for SRTP-SDES, SRTP-DTLS, SRTP-ZRTP

enable_zrtp (default: true)
Global switch to enable ZRTP processing.

enable_ice (default: true)
Enable ICE support. will reject SDP with ICE candidates otherwise

symmetric_rtp_mode (default: packets)
Symmetric RTP endpoint learning mode. allowed values: packets, delay

symmetric_rtp_packets (default: 0)
Minimal RTP packets count to leave passive mode in the 'packets' symmetric RTP endpoint learning mode

symmetric_rtp_delay (default: 250)
Minimal timeout in milliseconds to leave passive mode in the 'delay' symmetric RTP endpoint learning mode

force_symmetric_rtp (default: false)
Always create RTP streams in passive mode. By the default we use passive mode only if remote SDP contains 'direction' or 'setup' media aline with the 'active' value

force_symmetric_candidate (default: false)
Enable symmetric RTP for ICE candidates

detect_inband_dtmf (default: false)
Enable inband DTMF detection

dtmf_offer_multirate (default: false)
Add all supported rates for **telephone-event** payload in SDP offer

dtmf_default_volume (default: 20)
Volume level field value for **telephone-event** packets

Section **signaling-interfaces**
--------------------------------
Expand Down Expand Up @@ -323,9 +449,20 @@ Section modules describles which modules should be loaded. Module can optionally
/* Module2 configuration */
}
}
SEMS will lookup modules(.so binary libraries) at ``/usr/lib/sems/plug-in/`` directory.

path (default: /usr/lib/sems/plug-in/)
Path to lookup for modules \*.so files

config_path (default: /etc/sems/etc/)
Path prefix for modules to lookup for the additional module-specific config files

module "mod_name" { /\*cfg\*/ }
Load **mod_name** module with the specified configuration

global-module "mod_name" { /\*cfg\*/ }
Similar to **module** but loads \*.so with RTLD_NOW | RTLD_GLOBAL flags. needed for some plug-ins which should export symbols globally

Section **routing**
-------------------
Expand All @@ -339,4 +476,38 @@ SEMS is application server so it is possible to load multiple application at sam
application = yeti
}
application (default: empty)
Specifies applications to handle initial SIP INVITE requests.

Format is the list of mappings separated by ``|``. Session factory will iterate mappings in order they were specified until one of them returned destination application

Each mapping can be one of:

* ``app_name``: explicit application name
* ``$(ruri.user)``: get application name from the INVITE RURI-user
* ``$(ruri.param)``: get application name from the INVITE RURI header ``app``
* ``$(apphdr)``: get application name from the INVITE ``P-App-Name`` header
* ``$(mapping)``: use regex mapping from the ``/etc/sems/etc/app_mapping.conf``

.. code-block:: bash
# sems application mapping
#
# the application mapping defined here is used,
# if application=$(mapping) is set in sems.conf.
#
# the first regular expression which matches on the
# request URI sets the application that is executed.
#
# format:
# regexp=>application
# lines starting with '#' and empty lines are ignored
^sip:100=>echo
.*=>yeti
register_application (default: empty)
Override application for REGISTER requests

options_application (default: empty)
Override application for OPTIONS requests

0 comments on commit d5b39a5

Please sign in to comment.