Ubuntu Manpage: ocf_heartbeat_kamailio - Resource agent for Kamailio

Provided by: resource-agents-extra_4.16.0-3ubuntu1_amd64

NAME

       ocf_heartbeat_kamailio - Resource agent for Kamailio

SYNOPSIS


       kamailio [start | stop | status | monitor | meta-data | validate-all]

DESCRIPTION

       Resource agent for the Kamailio SIP proxy/registrar. Multiple instances are possible when using following
       parameter combinations:

       Parameters for Kamailio instance 1: listen_address=192.168.159.128 monitoring_ip=192.168.159.128
       proto=udptcp port=5060

       Parameters for Kamailio instance 2: listen_address=192.168.159.128 monitoring_ip=192.168.159.128
       proto=udp port=5070 conffile=/etc/kamailio/kamailio2.cfg kamctlrc=""

       Only one instance can be monitored via the command "kamctl monitor" because the kamctl tool of kamailio
       4.x is not designed for multiple instances. Therefore, the provided kamctrlrc file path needs to be empty
       for instance 2, 3 ...

       Parameters for a third Kamailio instance: listen_address=192.168.159.128 monitoring_ip=192.168.159.128
       proto=tcp port=5080 conffile=/etc/kamailio/kamailio3.cfg kamctlrc=""

SUPPORTED PARAMETERS

binary
The kamailio binary

(optional, string, default "/usr/sbin/kamailio")

conffile
The kamailio configuration file name with full path. For example, "/etc/kamailio/kamailio.cfg" ,
which is the default value. Make sure to use unique names in case of having multiple instances.

(optional, string, default "/etc/kamailio/kamailio.cfg")

pidfile
The kamailio PID file. The directory used must be writable by kamailio process user. Be sure to use
unique name for running more than one instance. Try to use absolute path names. If empty, resource
agent create a unique directory from the resource instance name for the PID file and assign it to the
process user.

(optional, string, default "/var/run/kamailio_RESOURCE_ID/kamailio.pid")

monitoring_ip
SIP IP Address of the kamailio instance used for SIP OPTIONS polling monitoring. Usually the same IP
address value as for parameter listen_address should be provided.

In order to respond with a 200 OK response to the SIP OOPTION requests, the kamailio.cfg file needs
to contain following section: Note: The following "kamailio.cfg" code snippet is part of an XML
section. Therefore it contains two & characters, which need to be replaced with two ampersand
characters within "kamailio.cfg":

if (is_method("OPTIONS") && (=~"sip:monitor@.*")) { ## ## If the method is an OPTIONS we are simply
going to respond ## with a 200 OK. # xlog("L_INFO", "Method is an OPTIONS, probably just
monitoring\n"); sl_send_reply("200", "Kamailio is alive"); exit; }

(optional, string, default "127.0.0.1")

listen_address
SIP IP address the kamailio will listen on.

(required, string, no default)

port
SIP port for the kamailio instance.

(optional, string, default "5060")

extra_options
Extra options to add to kamailio start.

(optional, string, no default)

proto
The protocol used for SIP proto = udp|tcp|udptcp|conf_udp|conf_tcp|conf_udptcp. Using the options
"conf_*" does not add any "-l" parameters to the kamailio command, the "listen" parameters from
kamailio.conf are used instead. The sipsak checks are performed depending what protocol is defined
after the underscore.

(optional, string, default "udptcp")

sipsak
The installation path of the sipsak tool, which is used for monitoring Kamailio via SIP OPTIONS
polling.

(optional, string, default "/usr/bin/sipsak")

kamctl
The installation path of the "kamctl" control tool.

(optional, string, default "/usr/bin/kamctl")

kamctlrc
The location of the "kamctlrc" file for the Kamailio instance. The file "kamctlrc" is the Kamailio
configuration file for its "kamctl" control tool.

This parameter only needs to be provided in case of using multiple Kamailio server instances on a
single cluster node:

In case that the parameter "kamctlrc" is not empty, this resource agent monitors the health state of
the Kamailio server via the command "kamctl monitor 1". This setting is recommended in case of using
a single Kamailio server instance.

In case that the parameter "kamctlrc" is empty, the resource agent does not monitor the health state
of the Kamailio server instance via the "kamctl" command.

Please note that the "kamctl" control command of Kamailio 4.x does not support running multiple
Kamailio instances on one host. Nevertheless this resource agent does allow multiple Kamailio
instances per host. The result of the "kamctl" limitation in terms of number of Kamailio server
instances is that the health check via "kamctl monitor 1" can be configured for a single Kamailio
instance only.

Please refer to the long description of this resource agent for an example of parameter combinations
in case that multiple instances are to be configured per cluster node.

(optional, string, default "/etc/kamailio/kamctlrc")

kamuser
The user account for kamailio process to run with. Uses the current user, if not specified or empty.
There is no check, if running kamailio with the specified user account is possible.

(optional, string, no default)

kamgroup
The group for kamailio process to run with. Uses the current group, if not specified or empty.

(optional, string, no default)

SUPPORTED ACTIONS

       This resource agent supports the following actions (operations):

       start
           Starts the resource. Suggested minimum timeout: 60s.

       stop
           Stops the resource. Suggested minimum timeout: 30s.

       status
           Performs a status check. Suggested minimum timeout: 30s. Suggested interval: 10s.

       monitor
           Performs a detailed status check. Suggested minimum timeout: 30s. Suggested interval: 10s.

       meta-data
           Retrieves resource agent metadata (internal use only). Suggested minimum timeout: 5s.

       validate-all
           Performs a validation of the resource configuration. Suggested minimum timeout: 5s.

       notify
           Suggested minimum timeout: 5s.

EXAMPLE CRM SHELL

       The following is an example configuration for a kamailio resource using the crm(8) shell:

           primitive p_kamailio ocf:heartbeat:kamailio \
             params \
               listen_address=string \
             op monitor timeout="30s" interval="10s"

EXAMPLE PCS

       The following is an example configuration for a kamailio resource using pcs(8)

           pcs resource create p_kamailio ocf:heartbeat:kamailio \
             listen_address=string \
             op monitor timeout="30s" interval="10s"

AUTHOR

       ClusterLabs contributors (see the resource agent source for information about individual authors)

resource-agents 4.16.0-3ubuntu                     06/25/2025                            OCF_HEARTBEAT_KAMAIL(7)

NAME

SYNOPSIS

DESCRIPTION

SUPPORTED PARAMETERS

SUPPORTED ACTIONS

EXAMPLE CRM SHELL

EXAMPLE PCS

SEE ALSO

AUTHOR