OCF_HEARTBEAT_KAMAIL(7)

📦
version 4.18.0 · 14 versions
, in fedora 43, fedora 44

✨ ocf_heartbeat_kamailio(7) ✨

okay bestie, welcome to the Kamailio resource agent manual — the page header up top literally reads OCF_HEARTBEAT_KAMAIL(7), and it's from the OCF resource agents crew. Let's get into it 💖

🌸 NAME 🌸

ocf_heartbeat_kamailio — the resource agent for Kamailio. that's it, that's the name. slay.

🎀 SYNOPSIS 🎀

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

🦋 DESCRIPTION 🦋

It's a resource agent for the Kamailio SIP proxy/registrar. and here's the tea: you can run multiple instances as long as you set the parameters up right. the combos look like this 👇

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=""

ngl this next part matters: only one instance can be monitored via the command kamctl monitor, because the kamctl tool of kamailio 4.x was simply not designed for multiple instances. so the kamctlrc file path needs to be empty for instance 2, 3, … — no exceptions, periodt.

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 itself. (optional, string, default "/usr/sbin/kamailio")
  • conffile — the kamailio configuration file name, with the full path. for example "/etc/kamailio/kamailio.cfg", which is also the default value. if you're running multiple instances, make sure those names are unique or it's gonna be chaos. (optional, string, default "/etc/kamailio/kamailio.cfg")
  • pidfile — the kamailio PID file. the directory you point at has to be writable by the kamailio process user, okay? and if you're running more than one instance, use a unique name. try to use absolute path names. if it's empty, the resource agent creates a unique directory from the resource instance name for the PID file and assigns it to the process user. (optional, string, default "/var/run/kamailio_RESOURCE_ID/kamailio.pid")
  • monitoring_ip — the SIP IP address of the kamailio instance, used for SIP OPTIONS polling monitoring. usually you should give the same IP address value as the listen_address parameter. (optional, string, default "127.0.0.1")

to respond with a 200 OK response to the SIP OOPTION requests, the kamailio.cfg file needs to contain the following section. note: the following "kamailio.cfg" code snippet is part of an XML section, so 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; }
  • listen_address — the SIP IP address the kamailio will listen on. (required, string, no default) 👑 this one's required, bestie, no default, no skipping.
  • port — the 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 "conf_*" options 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 on 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 kamctlrc file is the Kamailio configuration file for its "kamctl" control tool. (optional, string, default "/etc/kamailio/kamctlrc")

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

  • in case the "kamctlrc" parameter 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 the "kamctlrc" parameter 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 multiple instances are to be configured per cluster node.

  • kamuser — the user account for the kamailio process to run with. uses the current user if not specified or empty. there is no check whether running kamailio with the specified user account is actually possible. 🙈 (optional, string, no default)
  • kamgroup — the group for the 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):

  1. start — starts the resource. suggested minimum timeout: 60s.
  2. stop — stops the resource. suggested minimum timeout: 30s.
  3. status — performs a status check. suggested minimum timeout: 30s. suggested interval: 10s.
  4. monitor — performs a detailed status check. suggested minimum timeout: 30s. suggested interval: 10s.
  5. meta-data — retrieves resource agent metadata (internal use only). suggested minimum timeout: 5s.
  6. validate-all — performs a validation of the resource configuration. suggested minimum timeout: 5s.
  7. notify — suggested minimum timeout: 5s.

🫶 EXAMPLE CRM SHELL 🫶

here's an example config 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 🍓

and here's the same vibe but using pcs(8):

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

💜 SEE ALSO 💜

⭐ AUTHOR ⭐

ClusterLabs contributors (see the resource agent source for information about individual authors) — love them, they ate 💅

and that's the whole page, bestie! this little icon was brought to you by resource-agents, version UNKNOWN, dated 04/08/2026. iykyk 🎀✨
📦 where this page comes from