Default value: 2 (L_NOTICE)

Default level for printing the logs generated by xlog core function, when the log_level parameter is omitted.

         t_relay("no-auto-477 ");

tcp_no_new_conn_rplflag 🔗

A message flag, similar to tcp_no_new_conn_bflag, for preventing OpenSIPS to try to open a new TCP connection (if none available) when sending back a reply for the current request.

Example of usage:

     tcp_no_new_conn_msgflag = TCP_NO_RPL_CONNECT
     ...
     route {
         ...
         # if source is detected as NAT'ed, prevent opening back
         # TCP conns for replying
         if (isflagset(SRC_NATED) && $socket_in(proto) == "TCP")
             setbflag(TCP_NO_RPL_CONNECT);
         ...
         # this may fail at transport layer if no
         # TCP conn exists
         t_reply(302,"Redirected");         
     }

log_event_enabled 🔗

@]

log_event_level_filter 🔗

Extra log level filtering for the E_CORE_LOG event. This parameter may be useful when different levels of verbosity are desired between syslog/standard error logs and the logs delivered through the E_CORE_LOG event.

The log_event_level_filter should be used in concordance with the log_level parameter, i.e. a level lower than log_level.

Default value is 0 (no filtering).

Example of usage:

[@

    log_event_level_filter = 3

log_event_enabled (Unstable) 🔗

Enables the triggering of the E_CORE_LOG event for every log message generated by opensips. By default this is disabled.

WARNING! Subscribing to the E_CORE_LOG event might lead to unstable behavior for some event backends. When using the event_route module for example, having any xlog functions in the event_route will lead to an infinite spiral of triggering events that will block OpenSIPS. Also, other modules might not be fully tested for this feature.

Example of usage:

    log_event_enabled = yes

Size of the buffer used for printing the JSON document corresponding to a log message. This parameter makes sense when the json or json_cee log formats are used. If the buffer is too small, the log message will be truncated.

Size of the buffer used for printing the log message's payload. This is used for printing the "message" field from a JSON document, when the json or json_cee log formats are used or when the E_CORE_LOG event is raised, if enabled. If the buffer is too small, the log message will be truncated.

log_json_buf_size 🔗

Default value: 6144

Size of the buffer used for printing the JSON document when the json or json_cee log formats are used. If the buffer is too small, the log message will be truncated.

Usage example:

    log_json_buf_size = 8192 #given in bytes

log_msg_buf_size 🔗

Default value: 4096

Size of the buffer used for printing the log's actual message field from a JSON document, when the json or json_cee log formats are used. If the buffer is too small, the log message will be truncated.

Usage example:

    log_msg_buf_size = 8192 #given in bytes

The stderror_level_filter should be used in concordance with the log_level parameter, i.e. a level lower than log_level.

syslog_level_filter 🔗

The stderror_level_filter should be used in concordance with the log_level parameter, i.e. a level lower than log_level.

listen (Replaced in OpenSIPS 3.1) 🔗

log_name (Replaced in OpenSIPS 3.4) 🔗

stderror_level_filter 🔗

Extra log level filtering for the messages written to the standard error. This parameter may be useful when different levels of verbosity are desired for syslog and standard error logging.

Default value is 0 (no filtering).

    stderror_level_filter = 2

syslog_enabled 🔗

Enables writing log messages to syslog. Default value is no/disabled.

    syslog_enabled = yes

stderror_log_format 🔗

Format of the log messages printed to standard error. Possible values are:

• plain_text (default) - standard, plain text log message;
• json - basic JSON document
• json_cee - JSON document following the CEE(Common Event Expression) schema.

Default value is plain_text.

Example of usage:

    stderror_log_format = "json"

syslog_facility 🔗

If OpenSIPS logs to syslog, you can control the facility for logging. Very useful when you want to divert all OpenSIPS logs to a different log file. See the man page syslog(3) for more details.

Default value is LOG_DAEMON.

Example of usage:

    syslog_facility=LOG_LOCAL0

ssyslog_level_filter 🔗

Extra log level filtering for the messages sent to syslog. This parameter may be useful when different levels of verbosity are desired for syslog and standard error logging.

Default value is 0 (no filtering).

Example of usage:

    syslog_level_filter = 1

syslog_log_format 🔗

Format of the log messages sent to syslog. Possible values are:

• plain_text (default) - standard, plain text log message;
• json - basic JSON document
• json_cee - JSON document following the CEE(Common Event Expression) schema.

Default value is plain_text.

Example of usage:

    syslog_log_format = "json"

listen (Replaced in OpenSIPS 3.4) 🔗

log_facility (Replaced in OpenSIPS 3.4) 🔗

This parameter was replaced by the syslog_facility parameter, preserving exactly the same format and behavior.

log_name (Replaced in OpenSIPS 3.1) 🔗

This parameter was replaced by the syslog_name parameter, preserving exactly the same format and behavior.

log_stderror (Deprecated in OpenSIPS 3.4) 🔗

This parameter is deprecated and it's behavior starting with OpenSIPS 3.4 is equivalent to setting the stderror_enabled and syslog_enabled parameters, as following:

- "no" - stderror_enabled=no, syslog_enabled=yes

- "yes" (default) - stderror_enabled=yes, syslog_enabled=no

stderror_enabled 🔗

Enables writing log messages to standard error. Default value is yes/1.

Example of usage:

    stderror_enabled = no

syslog_enabled 🔗

Enables writing log messages to syslog. Default value is no/disabled.

Example of usage:

    syslog_enabled = yes

syslog_facility 🔗

If OpenSIPS logs to syslog, you can control the facility for logging. Very useful when you want to divert all OpenSIPS logs to a different log file. See the man page syslog(3) for more details.

Default value is LOG_DAEMON.

Example of usage:

    syslog_facility=LOG_LOCAL0

syslog_name 🔗

Set the id to be printed in syslog. The value must be a string and has effect only when OpenSIPS runs in daemon mode (fork=yes), after daemonize. Default value is argv[0].

Example of usage:

    syslog_name="osips-5070"

Configures the maximum number of shm operations to keep in the in-memory history. A separate memory block, dedicated for this shm debug info will be allocated. As such, OpenSIPS will actually take up more system memory than the configured shm pool (-m command line option). For example, for a shm_memlog_size=1000000, approximately 750 MB more will be used. This option is intended for debugging purposes and is disabled by default, i.e. shm_memlog_size=0.

shm_memlog_size 🔗

Configures the maximum number of shm operations to keep in the in-memory history. A separate memory block, dedicated for this shm debug info will be allocated. As such, OpenSIPS will actually take up more system memory than the configured shm pool (-m command line option). For example, for a shm_memlog_size=1000000, approximately 750 MB more will be used. By default, this memory logging is disabled, i.e. shm_memlog_size=0.

• "REUSE_PORT" - for TCP-based sockets only ; it allows outgoing TCP connections to reuse the listening port (of the socket) as the source port (rather than getting an emphemerous port).

Definition of a IP/destination blacklist. These lists can be selected from script (at runtime) to filter the outgoing requests, based on IP, protocol, port, etc.

Its primary purposes is be to prevent sending requests to critical IPs (like GWs), due bad DNS entries or to avoid sending to destinations that are known to be unavailable (temporary or permanent).

The grammar to specify a list is as it follows:

  "dst_blacklist" = id [/bl_flags] [: bl_rules] 

• id is a unique identifier of the blacklist
• bl_flags contains a set of optional modifiers:

  bl_flags = bl_flag [, bl_flag]*
  bl_flag = "expire" | "default" | "readonly"

• bl_rules contains one or more blacklists rules

  bl_rules = [!] ipnet | { bl_rule [, bl_rule]* }
  bl_rule = [!] ( [bl_proto, ] ipnet [, port [, bl_pattern]] )

The blacklist modifiers meanings are as follows:

• "expire": the blacklist may contain entries that expire
• "default": the blacklist is used by default when sending requests, without having to explicitly set it (using the use_blacklist function)
• "readonly": the blacklist is statically defined in script and cannot change at runtime

When dst_flags are missing, the "readonly" flag is explicitly set.

A rule is defined of the following properties:

• if "!" is at the beginning of the rule, it negates the entire rule
• bl_proto : any supported protocol, or "any" for any protocol; if missing, default is "any"
• ipnet: IP or IP/MASK that should match the rule
• port : number or 0 for any
• bl_pattern - is a filename like matching (see "man 3 fnmatch") applied on the outgoing request buffer (first_line+hdrs+body)

Example of usage:

   # filter out requests going to ips of my gws
   dst_blacklist = gw:{( tcp , 192.168.3.400 , 5060 , "" ),( any , 192.168.3.401 , 0 , "" )}
   # block requests going to "evil" networks
   dst_blacklist = net_filter:{ ( any , 192.168.1.120/255.255.255.0 , 0 , "" )}
   # block message requests with nasty words
   dst_blacklist = msg_filter:{ ( any , 192.168.20.0/255.255.255.0 , 0 , "MESSAGE*ugly_word" )}
   # block requests not going to a specific subnet
   dst_blacklist = net_filter2:{ !( any , 193.468.30.0/255.255.255.0 , 0 , "" )}
   # define a dynamic list that is built at runtime and has expire entries
   dst_blacklist = net_dynamic/expire

Far backward compatibility reasons, the default value is "off"/0.

• "FRAG" - indicates that the socket should not use PMTU (Path MTU) discovery to determine whether fragmentation should be done, but always allow fragmentation (i.e. do not force DF bit to 1 in UDP packets).

tcp_parallel_read_on_workers 🔗

This option will allow a TCP conn to perform read operations from different processes, not only from one. So far, upon creation, a TCP conn was assigned to a TCP workers which was doing all the reading for that TCP conn. This may become a bootleneck. With "tcp_parallel_read_on_workers", after a read is completed, the TCP conn is passed back to the TCP Main processes, which will perform a re-balancing for the next read operations, passing the TCP conn potentially to another worker. NOTE: at TCP conn level, the read ops are still performed in serial way, one at a time (even if from different processes)

@]

log_prefix 🔗

A string prefix which will be prepended to all logs produced by OpenSIPS (from both C code and script xlog() statements). Default: ""

Example of usage:

[@

    log_prefix = "opensips-backup"

abort_on_assert 🔗

advertised_address 🔗

advertised_port 🔗

alias 🔗

auto_aliases 🔗

auto_scaling_cycle 🔗

auto_scaling_profile 🔗

check_via 🔗

chroot 🔗

debug_mode 🔗

db_version_table 🔗

db_default_url 🔗

db_max_async_connections 🔗

disable_503_translation 🔗

disable_core_dump 🔗

disable_dns_blacklist 🔗

disable_dns_failover 🔗

disable_stateless_fwd 🔗

dns 🔗

dns_retr_time 🔗

dns_retr_no 🔗

dns_servers_no 🔗

dns_try_ipv6 🔗

dns_try_naptr 🔗

dns_use_search_list 🔗

dst_blacklist 🔗

enable_asserts 🔗

event_pkg_threshold 🔗

event_shm_threshold 🔗

exec_dns_threshold 🔗

exec_msg_threshold 🔗

include_file 🔗

import_file 🔗

listen (Replaced in OpenSIPS 3.1) 🔗

log_facility 🔗

log_level 🔗

log_name 🔗

log_stdout 🔗

log_stderror 🔗

max_while_loops 🔗

maxbuffer 🔗

mem-group 🔗

mem_warming 🔗

mem_warming_percentage 🔗

mem_warming_pattern_file 🔗

memdump | mem_dump mem_dump|🔗

memlog | mem_log mem_log|🔗

mcast_loopback 🔗

mcast_ttl 🔗

mhomed 🔗

mpath 🔗

open_files_limit 🔗

poll_method 🔗

port 🔗

pv_print_buf_size 🔗

query_buffer_size 🔗

query_flush_time 🔗

restart_persistency_cache_file 🔗

restart_persistency_size 🔗

rev_dns 🔗

server_header 🔗

server_signature 🔗

shm_hash_split_percentage 🔗

shm_secondary_hash_size 🔗

sip_warning 🔗

socket 🔗

tcp_workers 🔗

tcp_accept_aliases 🔗

tcp_connect_timeout 🔗

tcp_connection_lifetime 🔗

tcp_max_connections 🔗

tcp_max_msg_time 🔗

tcp_no_new_conn_bflag 🔗

tcp_socket_backlog 🔗

tcp_threshold 🔗

tcp_keepalive 🔗

tcp_keepcount 🔗

tcp_keepidle 🔗

tcp_keepinterval 🔗

timer_workers 🔗

tos 🔗

udp_workers 🔗

user_agent_header 🔗

wdir 🔗

xlog_buf_size 🔗

xlog_force_color 🔗

xlog_level 🔗

xlog_print_level 🔗

(:toc-back:)

listen (Replaced in OpenSIPS 3.1)

tcp_listen_backlog (Replaced in OpenSIPS 3.1)

log_stdout

Although all OpenSIPS logs are done via standard error, enabling this parameter may be still be useful when trying to extract logs from 3rd party libraries.

- "no" (default) - drop all standard output logs

- "yes" - let all standard output logs pass through

Example of usage:

    log_stdout = yes

    log_stderror = yes

Set the logging level (how verbose OpenSIPS should be). Higher values make OpenSIPS print more messages.

• 2 (default) - Notice level

The log_level parameter is usually used in concordance with the log_stderror parameter.

The value of the log_level parameter can also be get and set dynamically using the log_level Core MI function or $log_level script variable.

With this parameter you can make OpenSIPS write log messages to standard error. Possible values are:

- "no" (default) - write the messages to syslog

         if (isflagset(DST_NATED) && $socket_in(proto) == "TCP")

[@

@]

This parameter was replaced by the tcp_socket_backlog parameter, preserving exactly the same format and behavior.

• port: optional, the port used by the listening socket - if absent, the default port exported by the transport module is used.

tcp_listen_backlog (Replaced in OpenSIPS 3.4)

This parameter was replaced by the [#tcp_socket_backlog|tcp_socket_backlog]] parameter, preserving exactly the same format and behavior.

tcp_socket_backlog

The backlog argument defines the maximum length to which the queue of pending connections for the TCP listening sockets may grow. If a connection request arrives when the queue is full, the client may receive an error with an indication of ECONNREFUSED or, if the underlying protocol supports retransmission, the request may be ignored so that a later reattempt at connection succeeds.

Default configured value is 10.

NOTE: Aside this global approach, you can also define an advertise IP and port in a per-interface manner (see the socket parameter). When advertise values are defined per interface, they will be used only for traffic leaving that interface only.

NOTE: Aside this global approach, you can also define an advertise IP and port in a per-interface manner (see the socket parameter). When advertise values are defined per interface, they will be used only for traffic leaving that interface only.

It is necessary to include the port (the port value used in the "socket=" definitions) in the alias definition otherwise the loose_route() function will not work as expected for local forwards!

This parameter controls if aliases should be automatically discovered and added during fixing listening sockets. The auto discovered aliases are result of the DNS lookup (if the 'socket' definition has a name and not IP) or of a reverse DNS lookup on the socket IP.

Defines the behavior of the auto-scaling support, in terms of how many processes should be allowed and when to terminate or create new processes. These profiles may be used for the UDP processes (see udp_workers or socket options) , TCP processes (see tcp_workers option) or TIMER processes (see timer_workers option).\\

listen (Replaced in OpenSIPS 3.4)

This parameter was replaced by the [#socket|socket]] parameter, preserving exactly the same format and behavior.

socket

Set the network addresses/sockets the OpenSIPS server should listen on. Its syntax is protocol:address[:port], where:

• protocol: should be one of the transport modules loaded in the config file (e.g., udp, tcp, tls, bin, hep)
• address: can be an IP address, a hostname, a network interface id, or the * wildcard which makes OpenSIPS listen on all possible interfaces for that protocol
• port: optional, the port used by the listener - if absent, the default port exported by the transport module is used.

This parameter can be set multiple times in same configuration file, the server listening on all specified sockets.

The socket definition may accept several optional parameters:

• "AS ip:port" - to configure an advertised IP and port only for an interface. Example "AS 11.23.43.44:5060"
• "USE_WORKERS n" - to set a different number of workers for this socket only (for UDP, SCTP and HEP_UDP interfaces only). This will override the global "udp_worker" parameter. Example "use_workers 5"
• "ANYCAST" - to marke the socket as an anycast IP
• "USE_AUTO_SCALING_PROFILE" - to enforce a certain governing policy on how many UDP workers you have at runtime. Dynamically, UDP processes my be created or terminated, depending on the load/traffic. This parameter may be used ONLY for UDP sockets. Note that the per-socket defined auto-scaling profile will override this global UDP auto-scaling profile.
• "TAG" - this is a non SIP name/tag of the socket to be used when replicating the socket identify across an OpenSIPS cluster, with other OpenSIPS nodes. By using same TAG value, you can correlate/link listening sockets with different IPs on different OpenSIPS nodes. This is useful when replicating dialogs between OpenSIPS instances with different IPs.

Remember that the above parameters only affect the sockets they are configured for; if they are not defined for a given socket, the global values will be used instead.

Examples of usage:

    socket = udp:*
    socket = udp:eth1
    socket = tcp:eth1:5062
    socket = tls:localhost:5061
    socket = hep_udp:10.10.10.10:5064
    socket = ws:127.0.0.1:5060 use_workers 5
    socket = sctp:127.0.0.1:5060 as 99.88.44.33:5060 use_workers 3
    socket = udp:10.10.10.10:5060 anycast
    socket = udp:10.10.10.10:5060 use_workers 4 use_auto_scaling_profile PROFILE_SIP

On startup, OpenSIPS reports all the sockets that it is listening on.

Far backward compatibility reasons, the default value is "off"/1.

    auto_aliases=yes
    auto_aliases=1

Can be called from outside route blocks to load additional routes/blocks or from inside them to simply perform more functions. The file path can be relative or absolute. If it is a relative path, first attempt to locate it is relative to the directory from which OpenSIPS is started. If that fails, second try is relative to directory of the file that includes it. Will throw an error if file is not found.

Can be called from outside route blocks to load additional routes/blocks or from inside them to simply perform more functions. The file path can be relative or absolute. If it is a relative path, first attempt is to locate it is relative to the directory from which OpenSIPS is started. If that fails, second try is relative to directory of the file that includes it. Will throw an error if file is not found.

Same as include_file.

pv_print_buf_size

The maximum size of an expanded formatted string containing variables and/or pseudo-variables. Default: 20,000 bytes.

Example of usage:

    pv_print_buf_size = 60000

• "USE_AUTO_SCALING_PROFILE" - to enforce a certain governing policy on how many UDP workers you have at runtime. Dynamically, UDP processes my be created or terminated, depending on the load/traffic. This parameter may be used ONLY for UDP listeners. Note that the per-interface defined auto-scaling profile will override this global UDP auto-scaling profile.

Optionally, you can define a auto-scaling profile to govern in a dynamic way the number of UDP workers (by creating or terminating processes, depending on load). Note that the per-interface defined auto-scaling profile will override this global UDP auto-scaling profile. See auto_scaling_profile parameter for more.

auto_scaling_cycle

The number of seconds defining a auto-scaling cycle - the auto-scaling engine, at each cycle, is evaluating the internal load of the groups and decided if more processes needs to be created or if existing processes need to be terminated. Also see auto_scaling_profile for more details on how the auto-scaling works.
The default value is 1 second. Example of usage:

    auto_scaling_cycle=3  # do auto-scaling checks once every 3 seconds

auto_scaling_profile

auto_scaling_profile

Defines the behavior of the auto-scaling support, in terms of how many processes should be allowed and when to terminate or create new processes. These profiles may be used for the UDP processes (see udp_workers or listen options) , TCP processes (see tcp_workers option) or TIMER processes (see timer_workers option).
For more, see this external description of auto-scaling.

Example of usage:

    auto_scaling_profile = PROFILE_SIP
     scale up to 6 on 70% for 4 cycles within 5   
     scale down to 2 on 18% for 10 cycles

This profile will allow the group to fork up to 6 processes. A new process will be forked when the overall load of the group will be higher than 70% for more than 4 cycles during a 5 cycles monitoring window. A cycle is a time unit used for monitoring (like 2 seconds).
Also the profile will allow the group to scale down to a minimum of 2 processes. A process will be terminated when the overall load of the group will be lower than 20% during 10 cycles. The down scaling part of the profile is optional. If not defined, OpenSIPS will never down scale, but only up scale.

• "USE_AUTO_SCALING_PROFILE" - to enforce a certain governing policy on how many UDP workers you have at runtime. Dynamically, UDP processes my be created or terminated, depending on the load/traffic. This parameter may be used ONLY for UDP listeners.
• "TAG" - this is a non SIP name/tag of the interface to be used when replicating the interface identify across an OpenSIPS cluster, with other OpenSIPS nodes. By using same TAG value, you can correlate/link interfaces with different IPs on different OpenSIPS nodes. This is useful when replicating dialogs between OpenSIPS instances with different IPs.

    listen = udp:10.10.10.10:5060 use_workers 4 use_auto_scaling_profile PROFILE_SIP

Optionally, you can define a auto-scaling profile to govern in a dynamic way the number of TCP workers (by creating or terminating processes, depending on load). See auto_scaling_profile parameter for more.

    tcp_workers= 4
    tcp_workers= 3 use_auto_scaling_profile PROFILE_SIP

timer_workers

The number of worker processes to be created exclusively for timer related tasks/processing. The default and minimum number is '1'. Optionally, you can define a auto-scaling profile to govern in a dynamic way the number of timer workers (by creating or terminating processes, depending on load). See auto_scaling_profile parameter for more.

    timer_workers = 3
    timer_workers = 3 use_auto_scaling_profile PROFILE_TIMER

tos

The TOS (Type Of Service) to be used for the sent IP packages (both TCP and UDP).

    tos=IPTOS_LOWDELAY
    tos=0x10
    tos=IPTOS_RELIABILITY

@]

udp_workers

Number of worker processes to be created for each UDP or SCTP interface you have defined. Default value is 8. Optionally, you can define a auto-scaling profile to govern in a dynamic way the number of UDP workers (by creating or terminating processes, depending on load). See auto_scaling_profile parameter for more.

Example of usage: [@

    udp_workers=16
    udp_workers=4 use_auto_scaling_profile PROFILE_SIP 

restart_persistency_cache_file

This parameter controls the name of the cache file that is used to store restart persistence memory.

Default value is ".restart_persistency.cache".

restart_persistency_size

This parameter controls the size of the cache file. If this parameter is not specified, it defaults to the size of the shared memory.

Default value is the value of the shared memory, 32MB.

xlog_level

Similar to log_level this parameter independently controls (from the rest of the OpenSIPS code) the verbosity of the xlog() functions. This give you the possibility to separately control the verbosity level for logs from code versus logs from xlog().

Default value is 2 / L_NOTICE

Usage example:

    xlog_level = 3 #L_DBG

xlog_default_level (Replaced in OpenSIPS 3.4)

This was replaced by xlog_print_level.

xlog_print_level

Default value: -1 (L_ERR)

Default level for printing the logs generated by xlog core function, when the log_level parameter is omitted.

    xlog_print_level = 2 #L_NOTICE

Maximum number of active TCP accepted connections (i.e. initiated by remote endpoints). Once the limit is reached, any new incoming TCP connections will be rejected. The default is 2048. For outgoing TCP connections (initiated by OpenSIPS), there is currently no limit.

Maximum number of active TCP accepted connections (i.e. initiated by remote endpoints). If the number is exceeded, any new incoming TCP connections will be rejected. The default is 2048. For outgoing TCP connections (initiated by OpenSIPS), there is currently no limit.

NOTE that enabling this option will override all the other individual parameters like foreground mode, log level, udp_workers, tcp_workers, etc.

• "USE_WORKERS n" - to set a different number of workers for this interface only (for UDP, SCTP and HEP_UDP interfaces only). This will override the global "udp_worker" parameter. Example "use_workers 5"

    listen = ws:127.0.0.1:5060 use_workers 5
    listen = sctp:127.0.0.1:5060 as 99.88.44.33:5060 use_workers 3

Number of worker processes to be created for reading from TCP connections. These workers are responsible for handling any traffic over any TCP based protocol, like SIP-TCP, SIP-TLS, SIP-WS, SIP-WSS, BIN or HEP.

    tcp_workers=4

NOTE: Aside this global approach, you can also define an advertise IP and port in a per-interface manner (see the listen parameter). When advertise values are defined per interface, they will be used only for traffic leaving that interface only.

NOTE: Aside this global approach, you can also define an advertise IP and port in a per-interface manner (see the listen parameter). When advertise values are defined per interface, they will be used only for traffic leaving that interface only.

children (Obsolete in OpenSIPS 3.4)

The listen definition may accept several optional parameters:

• "AS ip:port" - to configure an advertised IP and port only for an interface. Example "AS 11.23.43.44:5060"
• "USE_WORKERS n" - to set a different number of workers for this interface only (for UDP, SCTP and HEP_UDP interfaces only). This will override the global "udp_worker" parameter. Example "use_children 5"
• "ANYCAST" - to marke the interface as an anycast IP

tcp_children (Obsolete in OpenSIPS 3.4)

children (obsolete)

This parameter is obsolete and replaced by the udp_workers new parameter.

chroot

The value must be a valid path in the system. If set, OpenSIPS will chroot (change root directory) to its value.

tcp_children (obsolete)

This parameter is obsolete and replaced by the tcp_workers new parameter.

tcp_workers

Number of children processes to be created for reading from TCP connections. These workers are responsible for handling any traffic over any TCP based protocol, like SIP-TCP, SIP-TLS, SIP-WS, SIP-WSS, BIN or HEP. If no value is explicitly set, 8 TCP workers will be created.

udp_workers

Number of worker processes to be created for each UDP or SCTP interface you have defined. Default value is 8.

Example of usage:

    udp_workers=16

NOTE: this global value (applicable for all UDP/SCTP interfaces) can be override if you set a different number of workers in the definition of a specific interface - so actually you can define a different number of workers for each interface (see the listen parameter for syntax).

         } else if ($var(retcode) < 0) {

     tcp_no_new_conn_bflag = TCP_NO_CONNECT

     ...

     route {
         ...

         if (isflagset(DST_NATED) && $proto == "TCP")
             setbflag(TCP_NO_CONNECT);

         ...

         if ($var(retcode) == -6) {

             send_reply("404", "Not Found");

         } else if ($var(retcode) <0 ) {

• marking the interface as an anycast IP, using the "anycast" token.

    listen = udp:10.10.10.10:5060 anycast

The poll method to be used by the I/O internal reactor - by default the best one for the current OS is selected. The available types are: poll, epoll, sigio_rt, select, kqueue, /dev/poll.

Set the network addresses the SIP server should listen to. Its syntax is protocol:address[:port], where:

• address: can be an IP address, a hostname, a network interface id, or the * wildcard which makes OpenSIPS listen on all possible interfaces for that protocol

It is necessary to include the port (the port value used in the "listen=" definitions) in the alias definition otherwise the loose_route() function will not work as expected for local forwards!

Set the network addresses the SIP server should listen to. Its syntax is 'protocol:address[:port]', where:

• protocol: should be one of the transport modules loaded in the config file (e.g., udp, tcp, tls)
• address: can be an IP address, a hostname, a network interface id, or the * which makes OpenSIPS listen on all possible interfaces for that protocol
• port: optional, the port used by the listener - if absent, the default port exported by the transport module is used.

This parameter can be set multiple times in same configuration file, the server listening on all addresses specified.

    listen = udp:*

(:toc-float Table of Contents:) This section lists the all the parameters exported by OpenSIPS core for script usage (to be used in opensips.cfg).

All the core keywords along with their accepted core values available in previous versions were eliminated in v3.4 and the use of core variables and core functions is recommended instead. For detailed information about what you can use in place of the deprecated keywords, check the migration page keywords section.

Core parameters

Global parameters that can be set in configuration file. Accepted values are, depending on the actual parameters strings, numbers and yes/ no. If you need to specify either "yes" or "no" as part of a string, wrap this in double quotes.

abort_on_assert

Default value: false

Only relevant if asserts are enabled. Set to true in order to make OpenSIPS shut down immediately in case a script assert fails.

Number of keepalives to send before closing the connection (Linux only). Default value is Operating System dependent and can be found using cat /proc/sys/net/ipv4/tcp_keepalive_probes. Common value is 9.

Setting tcp_keepcount to any value will enable tcp_keepalive.

Amount of time before OpenSIPS will start to send keepalives if the connection is idle (Linux only). Default value is Operating System dependent and can be found using cat /proc/sys/net/ipv4/tcp_keepalive_time. Common value is 7200 seconds.

Setting tcp_keepidle to any value will enable tcp_keepalive.

Interval between keepalive probes, if the previous one failed (Linux only). Default value is Operating System dependent and can be found using cat /proc/sys/net/ipv4/tcp_keepalive_intvl. Common value is 75 seconds.

Setting tcp_keepinterval to any value will enable tcp_keepalive.

Only relevant when the HP_MALLOC compile flag is enabled. If set to "on", on each startup, OpenSIPS will attempt to restore the memory fragmentation pattern it had before the stop/restart. If no pattern_file from a previous run is found, memory warming is skipped, and the memory allocator simply starts with a big chunk of memory, like all other allocators.

Only relevant if mem_warming is enabled. It contains the memory fragmentation pattern of a previous OpenSIPS run. This file is overwritten during each OpenSIPS shutdown, and is used during startup in order to restore the service behavior as soon as possible.

mem-group

In order for the feature to work you have to run "make generate-mem-stats" and complile with the variable SHM_EXTRA_STATS defined.

Usage example:

    mem-group = "interest": "core" "tm"
    mem-group = "runtime": "dialog" "usrloc" "tm"

For the above example the generated statistics will be named: shmem_group_interest:fragments, shmem_group_interest:memory_used, shmem_group_interest:real_used.

Multiple groups can be defined, but they must not have the same name.

If you want to generate the statistics for the default group (all the other modules not included in a group) you have to complile with the variable SHM_SHOW_DEFAULT_GROUP defined.

On startup, OpenSIPS reports all the interfaces that it is listening on. The TCP engine processes will be created regardless if you specify only UDP interfaces here.

Remember that the above parameters only affect the interface they are configured for; if they are not defined for a given interface, the global values will be used instead.

The listen definition may accept several optional parameters for:

• configuring an advertised IP and port only for an interface. Syntax "AS 11.23.43.44:5060"
• setting a different number of children for this interface only (for UDP, SCTP and HEP_UDP interfaces only). This will override the global "children" parameter. Syntax "use_children 5"

Remember that the above parameters only affect the interface they are configured for; if they are not defined for each interface, the global values will be used instead.

Examples of usage:

    listen = udp:eth1
    listen = tcp:eth1:5062
    listen = tls:localhost:5061
    listen = hep_udp:10.10.10.10:5064
    listen = ws:127.0.0.1:5060 use_children 5
    listen = sctp:127.0.0.1:5060 as 99.88.44.33:5060 use_children 3

If you omit this directive then the SIP server will listen on all interfaces. On startup, OpenSIPS reports all the interfaces that it is listening on. Even if you specify only UDP interfaces here, the server will start the TCP engine too.

If the ":port" part is omitted, all ports of the given "hostname" will be considered an alias (similar behavior to port 0).

If the ":port" part is omitted, all ports will be considered an alias (similar behavior to port 0).

It is necessary to include the port (the port value used in the "port=" or "listen=" definitions) in the alias definition otherwise the loose_route() function will not work as expected for local forwards!

tcp_connection_lifetime

Default value 0 (disabled). If enabled, OpenSIPS will enforce RFC 5923 behaviour when detecting an ";alias" Via header field parameter and will reuse any TCP (or TLS, WS, WSS) connection opened for such SIP requests (source IP + Via port + proto) when sending other SIP requests backwards, towards the same (source IP + Via port + proto) pair. The final purpose of RFC 5923, after all, is to minimize the number of TLS connections a SIP proxy must open, due to the large CPU overhead of the connection setup phase.

On top of RFC 5923's connection reusage (aliasing) mechanism, TCP connections in OpenSIPS are also persistent across multiple SIP dialogs. This can be controlled with the tcp_connection_lifetime global parameter.

WARNING! Enabling the global tcp_accept_aliases parameter (RFC 5923) for end-user initiated connections (who are most likely grouped by one or more public IPs) is an open vector for call hijacking! In such platforms, we recommend using the force_tcp_alias() core function, in order to employ RFC 5923 behaviour only in conjunction with adjacent SIP proxies.

(:toc-back:)

    alias=udp:other.domain.com:5060
    alias=tcp:another.domain.com:5060

memgroup

Defines a group of modules (by name) to get separate memory statistics. OpenSIPS will provide per-group memory information - the number of allocated fragments, the amount of used memory and the amount of real used memory (with memory manager overhead). This is useful if you want to monitor the memory usage of a certain module (or group of modules).

Example of usage:

    memgroup = groupname: moduleA moduleB
    memgroup = runtime: dialog usrloc tm
    memgroup = routing: drouting

cfg_file

Returns the name of the corresponding OpenSIPS config file (useful when multiple config files are included).

cfg_line

Returns the corresponding line inside the OpenSIPS config file.

bin_listen (Removed in OpenSIPS 3.4)

Replaced by the bin_port module parameter from proto_bin module (as a result of migrating the BIN implementation from core into a separate module).

bin_children (Removed in OpenSIPS 3.4)

Obsolete, simply removed.

group gid (Removed in OpenSIPS 3.4)

Use the -u command line parameter instead.

user uid (Removed in OpenSIPS 3.4)

Use the -u command line parameter instead.

This parameter was introduced as a replacement for the old fork options.

debug_mode

Enabling the debug_mode option is a fast way to debug your OpenSIPS. This option will automatically force:

• staying in foreground (do not detach from console)
• set logging level to 4 (debug)
• set logging to standard error
• enable core dumping
• set UDP worker processes to 2
• set TCP worker processes to 2

Default value is false/0 (disabled).

NOTE that enabling this option will override all the other individual parameters like foreground mode, log level, children, etc. This parameter was introduced as a replacement for the old debug options.

#debug

#fork

#group gid

mem_dump

mem_log

#tcp_connection_lifetime!!!!

#user uid

(:toc-back:)

Number of worker processes (children) to be created for each UDP or SCTP interface you have defined. Default value is 8.

fork (Removed in OpenSIPS 3.4)

Replaced by debug_mode parameter.

Value of 'log_level' parameter can also be get and set dynamically using log_level Core MI function or $log_level script variable.

Value of 'log_level' parameter can also be get and set dynamically using log_level Core MI function or log_level scripting function

Replaced by log_level parameter.

debug (Removed in OpenSIPS 3.4)

Replaced by [[#log_level|log_level] parameter.

log_level?

log_level

Set the logging level (how verbose OpenSIPS should be). Higher values make OpenSIPS to print more messages.

Examples of usage:

    log_level=1 -- print only important messages (like errors or more critical situations) 
    - recommended for running proxy as daemon

    log_level=4 -- print a lot of debug messages - use it only when doing debugging sessions

Actual values are:

• -3 - Alert level
• -2 - Critical level
• -1 - Error level
• 1 - Warning level
• 2 - Notice level
• 3 - Info level
• 4 - Debug level

The 'log_level' parameter is usually used in concordance with 'log_stderror' parameter.

Value of 'log_level' parameter can also be get and set dynamically using log_level Core MI function or scipting function

With this parameter you can make OpenSIPS to write log messages to standard error. Possible values are:

Log level to print memory status information (runtime and shutdown). It has to be less than the value of 'log_level' parameter if you want memory info to be logged. Default: memdump=L_DBG (4)

Log level to print memory debug info. It has to be less than the value of 'log_level' parameter if you want memory info to be logged. Default: memlog=L_DBG (4)

    mem-group = "interest" : "core" "tm"

Default value: 0 (not set). Setting tcp_keepidle to any value will enable tcp_keepalive.

Default value: 0 (not set). Setting tcp_keepinterval to any value will enable tcp_keepalive.

Default value: 0 (not set). Setting tcp_keepcount to any value will enable tcp_keepalive.

''Default value: 0 (not set). Setting tcp_keepidle to any value will enable tcp_keepalive.

''Default value: 0 (not set). Setting tcp_keepinterval to any value will enable tcp_keepalive.

''Default value: 0 (not set). Setting tcp_keepidle to any value will enable tcp_keepalive.

''Default value: 0 (not set). Setting tcp_keepinterval to any value will enable tcp_keepalive.

Enable or disable TCP keepalive (OS level).

[@

@]

Enable or disable TCP keepalive.

Enabled by default.

Default value: 0 (not set). Setting tcp_keepcount to any value will enable tcp_keepalive.

''Default value: 0 (disabled). Setting tcp_keepidle to any value will enable tcp_keepalive.

''Default value: 0 (disabled). Setting tcp_keepinterval to any value will enable tcp_keepalive.

Default value: 0 (disabled). Setting tcp_keepcount to any value will enable tcp_keepalive?.

''Default value: 0 (disabled). Setting tcp_keepcount to any value will enable tcp_keepalive?.

Enable or disable TCP keepalive. Enabled by default.

[@

@]

Number of keepalives to send before closing the connection (Linux only).

''Default value: 0 (disabled). Setting tcp_keepcount? to any value will enable tcp_keepalive?.

[@

@]

Amount of time before OpenSIPS will start to send keepalives if the connection is idle (Linux only).

''Default value: 0 (disabled). Setting tcp_keepidle? to any value will enable tcp_keepalive?.

[@

@]

Interval between keepalive probes, if the previous one failed (Linux only).

''Default value: 0 (disabled). Setting tcp_keepinterval? to any value will enable tcp_keepalive?.

The maximum number of seconds that a SIP message is expected to arrive via TCP. If a single SIP packet is still not fully received after this number of seconds, the connection is dropped ( either the connection is very overloaded and this leads to high fragmentation - or we are the victim of an ongoing attack where the attacker is sending the traffic very fragmented in order to decrease our performance ). Default value is 4

   dst_blacklist = gw:{( tcp , 192.168.3.400 , 5060 , "" ),( any , 192.168.3.401 , 0 , "" )}

   dst_blacklist = net_filter:{ ( any , 192.168.1.120/255.255.255.0 , 0 , "" )}

   dst_blacklist = msg_filter:{ ( any , 192.168.20.0/255.255.255.0 , 0 , "MESSAGE*ugly_word" )}

mem-group

Define a group of modules for which statistics will be generated regarding their shared memory usage. In order for the feature to work you have to run "make generate-mem-stats" and complile with the variable SHM_EXTRA_STATS defined.

Usage example:

    mem-group = "interest" : "core", "tm"

For the above example the generated statistics will be named: shmem_group_interest:fragments, shmem_group_interest:memory_used, shmem_group_interest:real_used.

Multiple groups can be defined, they must not have the same name.

If you want to generate the statistics for the default group (all the other modules not included in a group) you have to complile with the variable SHM_SHOW_DEFAULT_GROUP defined.

Only relevant when xlog is set to true. Enables the use of the color escape sequences, otherwise they will have no effect.

@]

xlog_default_level

Default value: -1

Default value for the logging level of the xlog core function, when the log_level parameter is omitted.

Usage example: [@

    xlog_default_level = 2 #L_NOTICE

Time in milliseconds before an ongoing blocking attempt to connect will be aborted. Default value is 100ms.

    tcp_connect_timeout = 5

    tcp_connection_lifetime = 3600

    tcp_max_connections = 4096

    tcp_max_msg_time = 8

abort_on_assert

Default value: false

Only relevant if asserts are enabled. Set to true in order to make OpenSIPS shut down immediately in case a script assert fails.

Example of usage:

    abort_on_assert = true

enable_asserts

Default value: false

Set to true in order to enable the assert script statement.

Example of usage:

    enable_asserts = true

tcp_children

Number of children processes to be created for reading from TCP connections. If no value is explicitly set, the same number of TCP children as UDP children (see "children" parameter) will be used.

    tcp_children=4

tcp_accept_aliases

tcp_listen_backlog

The backlog argument defines the maximum length to which the queue of pending connections for the TCP listeners may grow. If a connection request arrives when the queue is full, the client may receive an error with an indication of ECONNREFUSED or, if the underlying protocol supports retransmission, the request may be ignored so that a later reattempt at connection succeeds.

Default configured value is 10.

tcp_connect_timeout

Time in seconds before an ongoing blocking attempt to connect will be aborted.

    tcp_connect_timeout=5

tcp_connection_lifetime!!!!

Lifetime in seconds for TCP sessions. TCP sessions which are inactive for >tcp_connection_lifetime will be closed by OpenSIPS. Default value is defined in tcp_conn.h: #define DEFAULT_TCP_CONNECTION_LIFETIME 120. Setting this value to 0 will close the TCP connection pretty quick ;-). You can also set the TCP lifetime to the expire value of the REGISTER by using the tcp_persistent_flag parameter of the registrar module.

    tcp_connection_lifetime=3600

tcp_max_connections

maximum number of tcp connections (if the number is exceeded no new tcp connections will be accepted). Default is defined in tcp_conn.h: #define DEFAULT_TCP_MAX_CONNECTIONS 2048

    tcp_max_connections=4096

tcp_max_msg_time

The maximum number of seconds that a SIP message is expected to arrive via TCP. If a single SIP packet is still not fully received after this number of seconds, the connection is dropped ( either the connection is very overloaded and this leads to high fragmentation - or we are the victim of an ongoing attack where the attacker is sending the traffic very fragmented in order to decrease our performance ). Default value is is 4

    tcp_max_msg_time=8

tcp_no_new_conn_bflag

A branch flag to be used as marker to instruct OpenSIPS not to attempt to open a new TCP connection when delivering a request, but only to reuse an existing one (if available). If no existing conn, a generic send error will be returned.

This is intended to be used in NAT scenarios, where makes no sense to open a TCP connection towards a destination behind a NAT (like TCP connection created during registration was lost, so there is no way to contact the device until it re-REGISTER). Also this can be used to detect when a NATed registered user lost his TCP connection, so that opensips can disable his registration as useless.

     tcp_no_new_conn_bflag = 6
     ....
     route{
         ....
         if( destination_behin_nat && proto==TCP )
            setbflag(6);
         ....
         t_relay("0x02"); # no auto error reply
         $var(retcode) = $rc;
         if ($var(retcode)==-6) {
             #send error
             xlog("unable to send request to destination");
             send_reply("404","Not found");
             exit;
         } else if ($var(retcode)<0) {
             sl_reply_error();
             exit;
         }
         ....
     }

tcp_threshold

A number representing the maximum number of microseconds sending of a TCP request is expected to last. Anything above the set number will trigger a warning message to the logging facility.

Default value is 0 ( logging disabled ).

    tcp_threshold = 60000

tcp_keepalive

Enable / disable TCP keepalive

    tcp_keepalive = 1

tcp_keepcount

Number of keepalives to send before closing the connection (Linux only)

    tcp_keepcount = 5

tcp_keepidle

Amount of time before OpenSIPS will start to send keepalives if the connection is idle (Linux only)

    tcp_keepidle = 30

tcp_keepinterval

Interval between keepalive probes, if the previous one failed (Linux only)

Memory warming is useful when dealing with high volumes of traffic (thousands of cps on multi-core machines - the more cores, the more useful), because processes must mutually exclude themselves when chopping up the initial big memory chunk. By performing fragmentation on startup, OpenSIPS will also behave optimally in the first minute(s) after a restart. Fragmentation usually lasts a few seconds (e.g. ~5 seconds on an 8GB shm pool and 3.4Ghz CPU) - traffic will not be processed at all during this period.

Memory warming is useful when dealing with high volumes of traffic (thousands of cps on multi-core machines - the more cores, the more useful), because processes must mutually exclude themselves when chopping up the initial big memory chunk. By performing fragmentation on startup, OpenSIPS will also behave optimally in the first minute(s) after a restart. Fragmentation usually lasts a few seconds (e.g. ~5 seconds on an 8GB shm pool and 3.4Ghz processor) - traffic will not be processed at all during this period.

Only relevant when the HP_MALLOC compile flag is enabled. If set to "on", on each startup, OpenSIPS will attempt to restore the memory fragmentation pattern it had before the stop/restart. If no pattern_file from a previous run is found, memory warning is skipped, and the memory allocator simply starts with a big chunk of memory, like all other allocators.

Default value: "CFG_DIR/mem_warming_pattern"

Only relevant when the HP_MALLOC compile flag is enabled. If set to "on", on each startup, OpenSIPS will attempt to restore the memory fragmentation pattern it had before the stop/restart. If no pattern_file from a previous run is found, memory warning is skipped, and the memory allocator simply starts with a big chunk of memory.

mem_warming_percentage

Default value: 75

How much of OpenSIPS's memory should be fragmented with the pattern of the previous run, upon a restart. Used at startup, if mem_warming is enabled.

    mem_warming_percentage = 50

mem_warming_pattern_file

Default value: CFG_DIR/mem_warming_pattern

The memory fragmentation pattern of a previous OpenSIPS run. Used at startup, if mem_warming is enabled.

    mem_warming_pattern_file = "/var/tmp/my_memory_pattern"

    mem_warming = on

    mem_warming_pattern_file = "/var/tmp/my_memory_pattern"

@]

mem_warming_percentage

Default value: 75

How much of OpenSIPS's memory should be fragmented with the pattern of the previous run, upon a restart. Used at startup, if mem_warming ? is enabled.

Example of usage: [@

    mem_warming_percentage = 50

Memory warming is useful when dealing with high volumes of traffic (thousands of cps on multi-core machines - the more cores, the more useful), because processes must mutually exclude themselves when chopping up the initial big memory chunk. By performing fragmentation on startup, OpenSIPS will also behave optimally in the first minute(s) after a restart. Fragmentation usually lasts a few seconds - OpenSIPS will not process traffic during this period.

@]

mem_warming_pattern_file

Default value: CFG_DIR/mem_warming_pattern

The memory fragmentation pattern of a previous OpenSIPS run. Used at startup, if mem_warming ? is enabled.

Example of usage:

    mem_warming_pattern_file="/var/tmp/my_memory_pattern"

mem_warming_pattern_file

Default value: CFG_DIR/mem_warming_pattern

The memory fragmentation pattern of a previous OpenSIPS run. Used at startup, if mem_warming ? is enabled.

Example of usage: [@

    mem_warming_pattern_file="/var/tmp/my_memory_pattern"

Memory warming is useful when dealing with high volumes of traffic, because processes must mutually exclude themselves when chopping up the initial big memory chunk. By performing fragmentation on startup, OpenSIPS will also behave optimally in the first minute(s) after a restart.

Memory warming is useful when dealing with high volumes of traffic, because fragmenting the big chunk of memory is a "critical region" from locking point of view. The initial fragmentation allows the HP allocator to behave optimally in the first minute(s) after a restart.

mem_warming

Default value: off

Only relevant when the HP_MALLOC compile flag is enabled. If set to "on", on each startup, OpenSIPS will attempt to restore the memory fragmentation pattern it had before the stop/restart. If no pattern_file ? from a previous run is found, memory warning is skipped, and the memory allocator simply starts with a big chunk of memory.

Example of usage:

    mem_warming=on

mem_warming

Default value: off

Only relevant when the HP_MALLOC compile flag is enabled. If set to "on", on each startup, OpenSIPS will attempt to restore the memory fragmentation pattern it had before the stop/restart. If no pattern_file ? from a previous run is found, memory warning is skipped, and the memory allocator simply starts with a big chunk of memory.

Example of usage:

    mem_warming=on

Only relevant when log_stderror is set to true. Enables the use of the color escape sequences, otherwise they will have no effect.

Default value: 4096

@]

xlog_force_color

Default value: false

Only relevant when is set to true. Enables the use of the , otherwise they will have no effect.

Usage example: [@

    xlog_force_color = true

@]

xlog_buf_size

Size of the buffer used to print a single line on the chosen logging facility of OpenSIPS. If the buffer is too small, an overflow error will be printed, and the concerned line will be skipped.

Usage example: [@

    xlog_buf_size = 8388608 #given in bytes

The poll method to be used by the I/O internal reactor - by default the best one for the current OS is selected. The available types are: poll, epoll_lt, epoll_et, sigio_rt, select, kqueue, /dev/poll .

poll_method

The poll method to be used by the I/O internal reactor - by default the best one for the current OS is selected. The available types are: poll, epoll_lt, epoll_et, sigio_rt, select, kqueue, /dev/poll

    poll_method=select

port

The port the SIP server listens to. The default value for it is 5060.

Example of usage:

[@

@]

db_max_async_connections

Maximum number of TCP connections opened from a single OpenSIPS worker to each individual SQL backend. Default value is 10.

Individual backends are determined from DB URLs as follows:

        [ scheme, user, pass, host, port, database ]

Example of usage:

    db_max_async_connections=220

tcp_crlf_pingpong

Send CRLF pong (\r\n) to incoming CRLFCRLF ping. By default it is enabled (1).

Example of usage:

    tcp_crlf_pingpong = 0

tcp_crlf_drop

Drop CRLF (\r\n) ping messages. By default it is disabled (0).

Example of usage:

    tcp_crlf_drop = 1