Added pre-reload-hook #26

This change adds a pre-reload-hook mechanism to facilitate using
auto-configuration algorithms like the one used in libre-mesh.org

Closes #26

README.rst

@@ -73,6 +73,7 @@ UCI configuration options must go in ``/etc/config/openwisp``.
 - ``connect_timeout``: value passed to curl ``--connect-timeout`` argument, defaults to ``15``; see `curl connect-timeout argument <https://curl.haxx.se/docs/manpage.html#--connect-timeout>`_
 - ``max_time``: value passed to curl ``--max-time`` argument, defaults to ``30``; see `curl connect-timeout argument <https://curl.haxx.se/docs/manpage.html#-m>`_
 - ``mac_interface``: the interface from which the MAC address is taken when performing automatic registration, defaults to ``eth0``
+- ``pre_reload_hook``: path to custom executable script, see `pre-reload-hook`_
 
 Automatic registration
 ----------------------
@@ -172,6 +173,47 @@ Disable Unmanaged Configurations
 
 To disable unmanaged configurations simply remove all the ``unmanaged`` options.
 
+Hooks
+-----
+
+Below are described the available hooks in *openwisp-config*.
+
+pre-reload-hook
+^^^^^^^^^^^^^^^
+
+This hook is called each time *openwisp-config* applies a configuration, but **before services are reloaded**,
+more precisely in these situations:
+
+* after a new remote configuration is downloaded and applied
+* after a configuration test failed (see `Configuration test`_) and a previous backup is restored
+
+You can use this hook to perform custom actions before services are reloaded, eg: to perform
+auto-configuration with `LibreMesh <http://libre-mesh.org/>`_.
+
+Example configuration::
+
+    config controller 'http'
+            ...
+            option pre_reload_hook '/usr/sbin/my-pre-reload-hook'
+            ...
+
+Complete example:
+
+.. code-block:: shell
+
+    # set hook in configuration
+    uci set openwisp.http.pre_reload_hook='/usr/sbin/my-pre-reload-hook'
+    uci commit openwisp
+    # create hook script
+    cat <<EOF > /usr/sbin/my-pre-reload-hook
+    #!/bin/sh
+    # put your custom operations here
+    EOF
+    # make script executable
+    chmod +x /usr/sbin/my-pre-reload-hook
+    # reload openwisp_config by using procd's convenient utility
+    reload_config
+
 Compiling openwisp-config
 -------------------------
 

openwisp-config/files/openwisp-nossl.config

@@ -21,3 +21,5 @@ config controller 'http'
 	#option connect_timeout '15'
 	#option max_time '30'
 	#option capath '/etc/ssl/certs'
+	# hooks
+	#option pre_reload_hook '/usr/sbin/my_pre_reload_hook'

openwisp-config/files/openwisp-ssl.config

@@ -21,3 +21,5 @@ config controller 'http'
 	#option connect_timeout '15'
 	#option max_time '30'
 	#option capath '/etc/ssl/certs'
+	# hooks
+	#option pre_reload_hook '/usr/sbin/my_pre_reload_hook'

openwisp-config/files/openwisp.agent

@@ -19,6 +19,7 @@ while [ -n "$1" ]; do
 		--max-time) export MAX_TIME="$2"; shift;;
 		--capath) export CAPATH="$2"; shift;;
 		--mac-interface) export MAC_INTERFACE="$2"; shift;;
+		--pre-reload-hook) export PRE_RELOAD_HOOK="$2"; shift;;
 		-*)
 			echo "Invalid option: $1"
 			exit 1
@@ -201,6 +202,18 @@ configuration_changed() {
 	return 0
 }
 
+# called in `apply_configuration`
+pre_reload_hook() {
+	if [ -n "$PRE_RELOAD_HOOK" ]; then
+		$PRE_RELOAD_HOOK
+		local exit_code=$?
+		logger "Called pre-reload-hook: $PRE_RELOAD_HOOK - exit code: $exit_code" \
+		       -t openwisp \
+		       -p daemon.info
+		return $exit_code
+	fi
+}
+
 # applies a specified configuration archive
 apply_configuration() {
 	local sleep_time=${2-5}
@@ -217,6 +230,8 @@ apply_configuration() {
 	fi
 	# restore unmanaged configurations
 	/usr/sbin/openwisp-restore-unmanaged
+	# call pre-reload-hook
+	pre_reload_hook
 	# reload changes and wait $sleep_time
 	/usr/sbin/openwisp-reload-config
 	sleep $sleep_time

openwisp-config/files/openwisp.init

@@ -23,6 +23,7 @@ start_service() {
 	max_time=$(config_get http max_time)
 	capath=$(config_get http capath)
 	mac_interface=$(config_get http mac_interface)
+	pre_reload_hook=$(config_get http pre_reload_hook)
 	if [ $url ]; then url="--url $url"; fi
 	if [ $interval ]; then interval="--interval $interval"; fi
 	if [ $verify_ssl ]; then verify_ssl="--verify-ssl $verify_ssl"; fi
@@ -43,6 +44,7 @@ start_service() {
 	if [ $max_time ]; then max_time="--max-time $max_time"; fi
 	if [ $capath ]; then capath="--capath $capath"; fi
 	if [ $mac_interface ]; then mac_interface="--mac-interface $mac_interface"; fi
+	if [ $pre_reload_hook ]; then pre_reload_hook="--pre-reload-hook $pre_reload_hook"; fi
 
 	if [ -z "$url" ]; then
 		logger -s "url is not set, please add it in /etc/config/openwisp" \
@@ -61,7 +63,8 @@ start_service() {
 	procd_open_instance
 	procd_set_param command $PROG $url $interval $verify_ssl $uuid $key $shared_secret \
 	                        $consistent_key $unmanaged $merge_config $test_config \
-	                        $test_script $connect_timeout $max_time $capath $mac_interface
+	                        $test_script $connect_timeout $max_time $capath $mac_interface \
+	                        $pre_reload_hook
 	procd_set_param respawn
 	procd_close_instance
 	logger -s "$PROG_NAME started" \