keepalive: new module to monitor remote destinations

src/modules/keepalive/Makefile

@@ -0,0 +1,18 @@
+#
+# example module makefile
+#
+# 
+# WARNING: do not run this directly, it should be run by the master Makefile
+
+include ../../Makefile.defs
+
+auto_gen=
+NAME=keepalive.so
+
+LIBS=
+
+DEFS+=-DKAMAILIO_MOD_INTERFACE
+
+SERLIBPATH=../../lib
+SER_LIBS+=$(SERLIBPATH)/srdb1/srdb1
+include ../../Makefile.modules

src/modules/keepalive/api.h

@@ -0,0 +1,74 @@
+/**
+ * keepalive module - remote destinations probing
+ *
+ * Copyright (C) 2017 Guillaume Bour <guillaume@bour.cc>
+ *
+ * This file is part of Kamailio, a free SIP server.
+ *
+ * Kamailio is free software; you can redistribute it and/or modify
+ * it under the terms of the GNU General Public License as published by
+ * the Free Software Foundation; either version 2 of the License, or
+ * (at your option) any later version
+ *
+ * Kamailio is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+ * GNU General Public License for more details.
+ *
+ * You should have received a copy of the GNU General Public License
+ * along with this program; if not, write to the Free Software
+ * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA  02110-1301  USA
+ */
+
+/*! \file
+ * \ingroup keepalive
+ * \brief Keepalive :: Send keepalives
+ */
+
+#ifndef __KEEPALIVE_API_H_
+#define __KEEPALIVE_API_H_
+
+#include "../../core/sr_module.h"
+
+typedef int ka_state;
+
+#define KA_STATE_UNKNOWN    0
+#define KA_STATE_UP         1
+#define KA_STATE_DOWN       2
+
+typedef void (*ka_statechanged_f)(str uri, int state, void *user_attr);
+typedef int  (*ka_add_dest_f)(str uri, str owner, int flags, ka_statechanged_f callback,
+                              void *user_attr);
+typedef ka_state (*ka_dest_state_f)(str uri);
+
+typedef struct keepalive_api {
+	ka_add_dest_f	  add_destination;
+	ka_dest_state_f   destination_state;
+} keepalive_api_t;
+
+typedef int (*bind_keepalive_f)(keepalive_api_t* api);
+int bind_keepalive(keepalive_api_t* api);
+
+/**
+ * @brief Load the dispatcher API
+ */
+static inline int keepalive_load_api(keepalive_api_t *api)
+{
+	bind_keepalive_f bindkeepalive;
+
+	bindkeepalive = (bind_keepalive_f)find_export("bind_keepalive", 0, 0);
+	if(bindkeepalive == 0) {
+		LM_ERR("cannot find bind_keepalive\n");
+		return -1;
+	}
+
+	if(bindkeepalive(api) < 0)
+	{
+		LM_ERR("cannot bind keepalive api\n");
+		return -1;
+	}
+	return 0;
+}
+
+#endif /* __KEEPALIVE_API_H__ */
+

src/modules/keepalive/doc/Makefile

@@ -0,0 +1,4 @@
+docs = keepalive.xml
+
+docbook_dir = ../../../../doc/docbook
+include $(docbook_dir)/Makefile.module

src/modules/keepalive/doc/keepalive.xml

@@ -0,0 +1,38 @@
+<?xml version="1.0" encoding='ISO-8859-1'?>
+<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.4//EN"
+"http://www.oasis-open.org/docbook/xml/4.4/docbookx.dtd" [
+
+<!-- Include general documentation entities -->
+<!ENTITY % docentities SYSTEM "../../../../doc/docbook/entities.xml">
+%docentities;
+
+]>
+
+<book xmlns:xi="http://www.w3.org/2001/XInclude">
+    <bookinfo>
+	<title>KeepAlive Module</title>
+	<productname class="trade">kamailio.org</productname>
+	<authorgroup>
+	    <author>
+		<firstname>Guillaume</firstname>
+		<surname>Bour</surname>
+		<email>guillaume@bour.cc</email>
+	    </author>
+
+		<editor>
+		<firstname>Guillaume</firstname>
+		<surname>Bour</surname>
+		<email>guillaume@bour.cc</email>
+	    </editor>
+	</authorgroup>
+	<copyright>
+	    <year>2017</year>
+	    <holder>Guillaume Bour</holder>
+	</copyright>
+    </bookinfo>
+    <toc></toc>
+
+    <xi:include href="keepalive_admin.xml"/>
+
+
+</book>

src/modules/keepalive/doc/keepalive_admin.xml

@@ -0,0 +1,120 @@
+<?xml version="1.0" encoding='ISO-8859-1'?>
+<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.4//EN"
+"http://www.oasis-open.org/docbook/xml/4.4/docbookx.dtd" [
+
+<!-- Include general documentation entities -->
+<!ENTITY % docentities SYSTEM "../../../../doc/docbook/entities.xml">
+%docentities;
+
+]>
+<!-- Module User's Guide -->
+
+<chapter>
+
+	<title>&adminguide;</title>
+
+	<section>
+		<title>Overview</title>
+		<para>
+		This module performs destinations monitoring either for itself, or on the behalf of other modules
+		</para>
+	</section>
+
+	<section>
+		<title>Dependencies</title>
+		<section>
+			<title>&kamailio; Modules</title>
+			<para>
+				The following modules must be loaded before this module:
+				<itemizedlist>
+				<listitem>
+				<para>
+					<emphasis>tm</emphasis> - Transaction module
+				</para>
+				</listitem>
+				</itemizedlist>
+			</para>
+		</section>
+		<section>
+			<title>External Libraries or Applications</title>
+			<para>
+				The following libraries or applications must be installed before running
+				&kamailio; with this module loaded:
+				<itemizedlist>
+				<listitem>
+	            <para>
+					<emphasis>none</emphasis>
+				</para>
+				</listitem>
+				</itemizedlist>
+			</para>
+		</section>
+		<section>
+			<title>Parameters</title>
+			<section>
+				<title><varname>ping_interval</varname> (integer)</title>
+				<para>
+					Interval requests are sent to destinations (in seconds)
+				</para>
+				<para>
+				<emphasis>
+					Default value is 30 seconds.
+				</emphasis>
+				</para>
+				<example>
+					<title>Set <varname>ping_interval</varname> parameter</title>
+					<programlisting format="linespecific">
+...
+modparam("keepalive", "ping_interval", 10)
+...
+					</programlisting>
+				</example>
+			</section>
+			<section>
+				<title><varname>destination</varname> (string)</title>
+				<para>
+					Allows to specify statically destinations you want to monitor
+				</para>
+				<example>
+					<title>Set <varname>destination</varname> parameter</title>
+					<programlisting format="linespecific">
+...
+modparam("keepalive", "destination", "192.168.10.20")
+modparam("keepalive", "destination", "sip.provider.com")
+...
+					</programlisting>
+				</example>
+			</section>
+		</section>
+
+		<section>
+			<title>Functions</title>
+			<section id="keepalive.is_alive">
+			    <title>
+					<function moreinfo="none">is_alive(destination)</function>
+			    </title>
+				<para>
+					Get destination status
+				</para>
+		        <para>
+					Parameter <quote>destination</quote> is destination you want to check status
+		        </para>
+        		<para>
+		            Return value: 1 if destination is up, 2 if destination is down, -1 on error.
+        		</para>
+		        <para>
+				    This function can be used from ANY_ROUTE.
+		        </para>
+				<example>
+					<title><function>is_alive()</function> usage</title>
+					<programlisting format="linespecific">
+...
+is_alive("192.168.10.20");
+...
+			        </programlisting>
+			    </example>
+			</section>
+		</section>
+	</section>
+</chapter>
+

src/modules/keepalive/keepalive.h

@@ -0,0 +1,85 @@
+/**
+ * keepalive module - remote destinations probing
+ * 
+ * Copyright (C) 2017 Guillaume Bour <guillaume@bour.cc>
+ *
+ * This file is part of Kamailio, a free SIP server.
+ *
+ * Kamailio is free software; you can redistribute it and/or modify
+ * it under the terms of the GNU General Public License as published by
+ * the Free Software Foundation; either version 2 of the License, or
+ * (at your option) any later version
+ *
+ * Kamailio is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+ * GNU General Public License for more details.
+ *
+ * You should have received a copy of the GNU General Public License 
+ * along with this program; if not, write to the Free Software 
+ * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA  02110-1301  USA
+ */
+
+/*! \file
+ * \ingroup keepalive
+ * \brief Keepalive :: Keepalive
+ */
+
+#ifndef _KEEPALIVE_H_
+#define _KEEPALIVE_H_
+
+#include <time.h>
+#include "../../core/sr_module.h"
+
+
+#define KA_INACTIVE_DST		1  /*!< inactive destination */
+#define KA_TRYING_DST		2  /*!< temporary trying destination */
+#define KA_DISABLED_DST		4  /*!< admin disabled destination */
+#define KA_PROBING_DST		8  /*!< checking destination */
+#define KA_STATES_ALL		15  /*!< all bits for the states of destination */
+
+#define ds_skip_dst(flags)	((flags) & (KA_INACTIVE_DST|KA_DISABLED_DST))
+
+#define KA_PROBE_NONE			0
+#define KA_PROBE_ALL			1
+#define KA_PROBE_INACTIVE		2
+#define KA_PROBE_ONLYFLAGGED	3
+
+typedef void (*ka_statechanged_f)(str uri, int state, void *user_attr);
+
+typedef struct _ka_dest
+{
+	str uri;
+	str owner;                  // name of destination "owner"
+                                // (module asking to monitor this destination
+	int flags;
+	int state;
+	time_t last_checked,
+		   last_up,
+		   last_down;
+	//ds_attrs_t attrs;
+
+	void *user_attr;
+	ka_statechanged_f statechanged_clb;
+
+	struct socket_info * sock;
+	struct ip_addr ip_address; 	/*!< IP-Address of the entry */
+	unsigned short int port; 	/*!< Port of the URI */
+	unsigned short int proto; 	/*!< Protocol of the URI */
+	//int message_count;
+	struct _ka_dest *next;
+} ka_dest_t;
+
+typedef struct _ka_destinations_list
+{
+	ka_dest_t *first;
+} ka_destinations_list_t;
+
+extern ka_destinations_list_t *ka_destinations_list;
+
+int ka_add_dest(str uri, str owner, int flags, ka_statechanged_f callback, void *user_attr);
+int ka_destination_state(str uri);
+int ka_str_copy(str src, str *dest, char *prefix);
+
+#endif
+