Documentation |
Documentation -> Manuals -> Manual 1.7 -> Core parametersPages for other versions: devel 3.5 3.4 Older versions: 3.3 3.2 3.1 3.0 2.4 2.3 2.2 2.1 1.11 1.10 1.9 1.8 1.7 1.6 1.5 1.4
Table of Content (hide)
This section lists the all the parameters exported by OpenSIPS core for script usage (to be used in opensips.cfg) 1. Core KeywordsKeywords specific to SIP messages which can be used mainly in 'if' expressions. 1.1 afThe address family of the received SIP message. It is INET if the message was received over IPv4 or INET6 if the message was received over IPv6. Exampe of usage: if(af==INET6) { log("Message received over IPv6 link\n"); }; 1.2 dst_ipThe IP of the local interface where the SIP message was received. When the proxy listens on many network interfaces, makes possible to detect which was the one that received the packet. Example of usage: if(dst_ip==127.0.0.1) { log("message received on loopback interface\n"); }; 1.3 dst_portThe local port where the SIP packet was received. When OpenSIPS is listening on many ports, it is useful to learn which was the one that received the SIP packet. Example of usage: if(dst_port==5061) { log("message was received on port 5061\n"); }; 1.4 from_uriThis script variable is a reference to the URI of 'From' header. It can be used to test 'From'- header URI value. Example of usage: if(is_method("INVITE") && from_uri=~".*@opensips.org") { log("the caller is from opensips.org\n"); }; 1.5 methodThe variable is a reference to the SIP method of the message. Example of usage: if(method=="REGISTER") { log("this SIP request is a REGISTER message\n"); }; 1.6 msg:lenThe variable is a reference to the size of the message. It can be used in 'if' constructs to test message's size. Example of usage: if(msg:len>2048) { sl_send_reply("413", "message too large"); exit; }; 1.7 $retcodeIt represents the value returned by last function executed (similar to $? from bash -- if you wish, you can use also $? in OpenSIPS config, both names '$retcode' and '$?' are supported). If tested after a call of a route, it is the value retuned by that route. Example of usage: route { route(1); if($retcode==1) { log("The request is an INVITE\n"); }; } route[1] { if(is_method("INVITE")) return(1); return(2); } 1.8 protoThis variable can be used to test the transport protocol of the SIP message. Example of usage: if(proto==UDP) { log("SIP message received over UDP\n"); }; 1.9 statusIf used in onreply_route, this variable is a reference to the status code of the reply. If it used in a standard route block, the variable is a reference to the status of the last reply sent out for the current request. Example of usage: if(status=="200") { log("this is a 200 OK reply\n"); }; 1.10 src_ipReference to source IP address of the SIP message. Example of usage: if(src_ip==127.0.0.1) { log("the message was sent from localhost!\n"); }; 1.11 src_portReference to source port of the SIP message (from which port the message was sent by previous hop). Example of usage: if(src_port==5061) { log("message sent from port 5061\n"); } 1.12 to_uriThis variable can be used to test the value of URI from To header. Example of usage: if(to_uri=~"sip:.+@opensips.org") { log("this is a request for opensips.org users\n"); }; 1.13 uriThis variable can be used to test the value of the request URI. Example of usage: if(uri=~"sip:.+@opensips.org") { log("this is a request for opensips.org users\n"); }; 2. Core ValuesValues that can be used in 'if' expressions to check against Core Keywords 2.1 INETThis keyword can be used to test whether the SIP packet was received over an IPv4 connection. Example of usage: if(af==INET) { log("the SIP message was received over IPv4\n"); }; 2.2 INET6This keyword can be used to test whether the SIP packet was received over an IPv6 connection. Example of usage: if(af==INET6) { log("the SIP message was received over IPv6\n"); }; 2.3 TCPThis keyword can be used to test the value of 'proto' and check whether the SIP packet was received over TCP or not. Example of usage: if(proto==TCP) { log("the SIP message was received over TCP\n"); }; 2.4 UDPThis keyword can be used to test the value of 'proto' and check whether the SIP packet was received over UDP or not. Example of usage: if(proto==UDP) { log("the SIP message was received over UDP\n"); }; 2.5 max_lenThis keyword is set to the maximum size of an UDP packet. It can be used to test message's size. Example of usage: if(msg:len>max_len) { sl_send_reply("413", "message too large to be forwarded over UDP without fragmentation"); exit; } 2.6 myselfIt is a reference to the list of local IP addresses, hostnames and aliases that has been set in OpenSIPS configuration file. This lists contain the domains served by OpenSIPS. The variable can be used to test if the host part of an URI is in the list. The usefulness of this test is to select the messages that has to be processed locally or has to be forwarded to another server. See "alias" to add hostnames,IP addresses and aliases to the list. Example of usage: if(uri==myself) { log("the request is for local processing\n"); }; 2.7 nullCan be used in assignment to reset the value of a per-script variable or to delete an avp. Example of usage: $avp(i:12) = null; $var(x) = null; 3. Core parametersGlobal 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. 3.1 advertised_addressIt can be an IP address or string and represents the address advertised in Via header and other destination lumps (e.g RR header). If empty or not set (default value) the socket address from where the request will be sent is used. WARNING: - don't set it unless you know what you are doing (e.g. nat traversal) - you can set anything here, no check is made (e.g. foo.bar will be accepted even if foo.bar doesn't exist) Example of usage: advertised_address="opensips.org" 3.2 advertised_portThe port advertised in Via header and other destination lumps (e.g. RR). If empty or not set (default value) the port from where the message will be sent is used. Same warnings as for 'advertised_address'. Example of usage: advertised_port=5080 3.3 aliasParameter to set alias hostnames for the server. It can be set many times, each value being added in a list to match the hostname when 'myself' is checked. 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 Example of usage: alias=other.domain.com:5060 alias=another.domain.com:5060 3.4 avp_aliasesContains a multiple definition of aliases for AVP names. Example of usage: avp_aliases="uuid=I:660;email=s:email_addr;fwd=i:753" 3.5 auto_aliasesThis 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 listen is a name and not IP) or of a reverse DNS lookup on the listen IP. Far backward compatibility reasons, the default value is "on". Example of usage: auto_aliases=no auto_aliases=0 3.6 check_viaCheck if the address in top most via of replies is local. Default value is 0 (check disabled). Example of usage: check_via=1 3.7 childrenNumber of children to fork for the UDP interfaces (one set for each interface - ip:port). Default value is 8. Example of usage: children=16 3.8 chrootThe value must be a valid path in the system. If set, OpenSIPS will chroot (change root directory) to its value. Example of usage: chroot=/other/fakeroot 3.9 db_version_tableThe name of the table version to be used by the DB API to check the version of the used tables. Example of usage: db_version_table="version_1_5" 3.10 db_default_urlThe default DB URL to be used by modules if no per-module URL is given. Default is NULL (not defined) Example of usage: db_default_url="mysql://opensips:opensipsrw@localhost/opensips" 3.11 debugSet the debug level. Higher values make OpenSIPS to print more debug messages. Examples of usage: debug=3 -- print only important messages (like errors or more critical situations) - recommended for running proxy as daemon debug=9 -- print a lot of debug messages - use it only when doing debugging sessions The 'debug' parameter is usually used in concordance with 'log_stderror' parameter. Value of 'debug' parameter can also be get and set dynamically using 'debug' Core MI function. For more see: http://www.voice-system.ro/docs/ser-syslog/ 3.12 disable_503_translationIf 'yes', OpenSIPS will not translate the received 503 replies into 500 replies (RFC 3261 clearly states that a proxy should never relay a 503 response, but instead it must transform it into a 500). Default value is 'no' (do translation). 3.13 disable_core_dumpCan be 'yes' or 'no'. By default core dump limits are set to unlimited or a high enough value. Set this config variable to 'yes' to disable core dump-ing (will set core limits to 0). Default value is 'no'. Example of usage: disable_core_dump=yes 3.14 disable_dns_blacklistThe DNS resolver, when configured with failover, can automatically store in a temporary blacklist the failed destinations. This will prevent (for a limited period of time) OpenSIPS to send requests to destination known as failed. So, the blacklist can be used as a memory for the DNS resolver. The temporary blacklist created by DNS resolver is named "dns" and it is by default selected for usage (no need use the use_blacklist()) function. The rules from this list have a life time of 4 minutes - you can change it at compile time, from blacklists.h . Can be 'yes' or 'no'. By default the blacklist is disabled (Default value is 'yes'). Example of usage: disable_dns_blacklist=no 3.15 disable_dns_failoverCan be 'yes' or 'no'. By default DNS-based failover is enabled. Set this config variable to 'yes' to disable the DNS-based failover. This is a global option, affecting the core and the modules also. Default value is 'no'. Example of usage: disable_dns_failover=yes 3.16 disable_stateless_fwdCan be 'yes' or 'no'. This parameter controls the handling of stateless replies: yes - drop stateless replies if stateless fwd functions (like forward) are not used in script no - forward stateless replies Default value is 'yes'. 3.17 disable_tcpGlobal parameter to disable TCP support in the SIP server. Default value is 'no'. Example of usage: disable_tcp=yes 3.18 disable_tlsGlobal parameter to disable TLS support in the SIP server. Default value is 'yes'. Example of usage: disable_tcp=no 3.19 dnsThis parameter controls if the SIP server should attempt to lookup its own domain name in DNS. If this parameter is set to yes and the domain name is not in DNS a warning is printed on syslog and a "received=" field is added to the via header. Default is no. 3.20 dns_retr_timeTime in seconds before retrying a dns request. Default value is system specific, depends also on the '/etc/resolv.conf' content (usually 5s). Example of usage: dns_retr_time=3 3.21 dns_retr_noNumber of dns retransmissions before giving up. Default value is system specific, depends also on the '/etc/resolv.conf' content (usually 4). Example of usage: dns_retr_no=3 3.22 dns_servers_noHow many dns servers from the ones defined in '/etc/resolv.conf' will be used. Default value is to use all of them. Example of usage: dns_servers_no=2 3.23 dns_try_ipv6Can be 'yes' or 'no'. If it is set to 'yes' and a DNS lookup fails, it will retry it for ipv6 (AAAA record). Default value is 'no'. Example of usage: dns_try_ipv6=yes 3.24 dns_use_search_listCan be 'yes' or 'no'. If set to 'no', the search list in '/etc/resolv.conf' will be ignored (=> fewer lookups => gives up faster). Default value is 'yes'. HINT: even if you don't have a search list defined, setting this option to 'no' will still be "faster", because an empty search list is in fact search "" (so even if the search list is empty/missing there will still be 2 dns queries, eg. foo+'.' and foo+""+'.') Example of usage: dns_use_search_list=no 3.25 dst_blacklistDefinition of a static (read-only) 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 will be to prevent sending requests to critical IPs (like GWs) due DNS or to avoid sending to destinations that are known to be unavailable (temporary or permanent). Example of usage: # filter out requests going to ips of my gws dst_blacklist = gw:{( tcp , 192.168.2.100 , 5060 , "" ),( any , 192.168.2.101 , 0 , "" )} # block requests going to "evil" networks dst_blacklist = net_filter:{ ( any , 192.168.1.100/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 , 192.168.30.0/255.255.255.0 , 0 , "" )} Each rule is defined by:
3.26 exec_dns_thresholdA number representing the maximum number of microseconds a DNS query is expected to last. Anything above the set number will trigger a warning message to the logging facility. Default value is 0 ( logging disabled ). Example of usage: exec_dns_threshold = 60000 3.27 exec_msg_thresholdA number representing the maximum number of microseconds the processing of a SIP msg is expected to last. Anything above the set number will trigger a warning message to the logging facility. Default value is 0 ( logging disabled ). Example of usage: exec_msg_threshold = 60000 3.28 forkIf set to 'yes' the proxy will fork and run in daemon mode - one process will be created for each network interface the proxy listens to and for each protocol (TCP/UDP), multiplied with the value of 'children' parameter. When set to 'no', the proxy will stay bound to the terminal and runs as single process. First interface is used for listening to. Default value is 'yes'. Example of usage: fork=no 3.29 group gidThe group id to run OpenSIPS. Example of usage: group="opensips" 3.30 listenSet the network addresses the SIP server should listen to. It can be an IP address, hostname or network interface id or combination of protocol:address:port (e.g., udp:10.10.10.10:5060). This parameter can be set multiple times in same configuration file, the server listening on all addresses specified. Example of usage: listen=10.10.10.10 listen=eth1:5062 listen=udp:10.10.10.10:5064 If you omit this directive then the SIP server will listen on all interfaces. On start the SIP server 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 you don't want this, you need to disable the TCP support completely with the core parameter disable_tcp. 3.31 log_facilityIf 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. For more see: http://www.voice-system.ro/docs/ser-syslog/ Default value is LOG_DAEMON. Example of usage: log_facility=LOG_LOCAL0 3.32 log_nameSet 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: log_name="osips-5070" 3.33 log_stderrorWith this parameter you can make OpenSIPS to write log and debug messages to standard error. Possible values are: - "yes" - write the messages to standard error - "no" - write the messages to syslog Default value is "no". For more see: http://www.voice-system.ro/docs/ser-syslog/ Example of usage: log_stderror=yes 3.34 max_while_loopsThe parameters set the value of maximum loops that can be done within a "while". Comes as a protection to avoid infinite loops in config file execution. Default is 100. Example of usage: max_while_loops=200 3.35 maxbufferThe size in bytes not to be exceeded during the auto-probing procedure of discovering the maximum buffer size for receiving UDP messages. Default value is 262144. Example of usage: maxbuffer=65536 3.36 memdump | mem_dumpLog level to print memory status information (runtime and shutdown). It has to be less than the value of 'debug' parameter if you want memory info to be logged. Default: memdump=L_DBG (4) Example of usage: memdump=2 NOTE that setting memlog (see below), will also set the memdump parameter - if you want different values for memlog and memdump, you need to first set memlog and then memdump. 3.37 memlog | mem_logLog level to print memory debug info. It has to be less than the value of 'debug' parameter if you want memory info to be logged. Default: memlog=L_DBG (4) Example of usage: memlog=2 NOTE: by setting memlog parameter, the memdump will automatically be set to the same value (see memdump docs). 3.38 mcast_loopbackIt can be 'yes' or 'no'. If set to 'yes', multicast datagram are sent over loopback. Default value is 'no'. Example of usage: mcast_loopback=yes 3.39 mcast_ttlSet the value for multicast ttl. Default value is OS specific (usually 1). Example of usage: mcast_ttl=32 3.40 mhomedSet the server to try to locate outbound interface on multihomed host. By default is not (0) - it is rather time consuming. Example of usage: mhomed=1 3.41 mpathSet the module search path. This can be used to simplify the loadmodule parameter Example of usage: mpath="/usr/local/lib/opensips/modules" loadmodule "mysql.so" loadmodule "uri.so" loadmodule "uri_db.so" loadmodule "sl.so" loadmodule "tm.so" ... 3.42 open_files_limitIf set and bigger than the current open file limit, OpenSIPS will try to increase its open file limit to this number. Note: OpenSIPS must be started as root to be able to increase a limit past the hard limit (which, for open files, is 1024 on most systems). Example of usage: open_files_limit=2048 3.43 portThe port the SIP server listens to. The default value for it is 5060. Example of usage: port=5080 3.44 reply_to_viaIf it is set to 1, any local reply is sent to the address advertised in top most Via of the request. Default value is 0 (off). Example of usage: reply_to_via=0 3.45 query_buffer_sizeIf set to a value greater than 1, inserts to DB will not be flushed one by one. Rows to be inserted will be kept in memory until until they gather up to query_buffer_size rows, and only then they will be flushed to the database. Example of usage: query_buffer_size=5 3.46 query_flush_timeIf query_buffer_size is set to a value greater than 1, a timer will trigger once every query_flush_time seconds, ensuring that no row will be kept for too long in memory. Example of usage: query_flush_time=10 3.47 rev_dnsThis parameter controls if the SIP server should attempt to lookup its own IP address in DNS. If this parameter is set to yes and the IP address is not in DNS a warning is printed on syslog and a "received=" field is added to the via header. Default is no. 3.48 server_headerThe body of Server header field generated by OpenSIPS when it sends a request as UAS. It defaults to "OpenSIPS (<version> (<arch>/<os>))". Example of usage: server_header="Server: My Company SIP Proxy" Please note that you have to add the header name "Server:", otherwise OpenSIPS will just write a header like: My Company SIP Proxy 3.49 server_signatureThis parameter controls the "Server" header in any locally generated message. Example of usage: server_signature=no If it is enabled (default=yes) a header is generated as in the following example: Server: OpenSIPS (0.9.5 (i386/linux)) 3.50 sip_warningCan be 0 or 1. If set to 1 (default value is 0) a 'Warning' header is added to each reply generated by OpenSIPS. The header contains several details that help troubleshooting using the network traffic dumps. Example of usage: sip_warning=0 3.51 tcp_childrenNumber 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. Example of usage: tcp_children=4 3.52 tcp_accept_aliases3.53 tcp_send_timeoutTime in seconds after a TCP connection will be closed if it is not available for writing in this interval (and OpenSIPS wants to send something on it). Example of usage: tcp_send_timeout=3 3.54 tcp_connect_timeoutTime in seconds before an ongoing attempt to connect will be aborted. Example of usage: tcp_connect_timeout=5 3.55 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. Example of usage: tcp_connection_lifetime=3600 3.56 tcp_max_connectionsmaximum 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 Example of usage: tcp_max_connections=4096 3.57 tcp_poll_methodpoll method used (by default the best one for the current OS is selected). For available types see io_wait.c and poll_types.h: none, poll, epoll_lt, epoll_et, sigio_rt, select, kqueue, /dev/poll Example of usage: tcp_poll_method=select 3.58 tcp_no_new_conn_bflagA 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. Example of usage: 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; } .... } 3.59 tls_ca_list3.60 tls_certificate3.61 tls_ciphers_list3.62 tls_domain3.63 tls_handshake_timeout3.64 tls_log3.65 tls_method3.66 tls_port_no3.67 tls_private_key3.68 tls_require_certificate3.69 tls_send_timeout3.70 tls_verify3.71 tosThe TOS (Type Of Service) to be used for the sent IP packages (both TCP and UDP). Example of usage: tos=IPTOS_LOWDELAY tos=0x10 tos=IPTOS_RELIABILITY 3.72 user uidThe user id to run OpenSIPS (OpenSIPS will suid to it). Example of usage: user="opensips" 3.73 user_agent_headerThe body of User-Agent header field generated by OpenSIPS when it sends a request as UAC. It defaults to "OpenSIPS (<version> (<arch>/<os>))". Example of usage: user_agent_header="User-Agent: My Company SIP Proxy" Please note that you have to include the header name "User-Agent:" as OpenSIPS does not add it and you will get an erroneous header like: My Company SIP Proxy 3.74 wdirThe working directory used by OpenSIPS at runtime. You might find it usefull when come to generating core files :) Example of usage: wdir="/usr/local/opensips" or wdir=/usr/opensips_wd |