Implemented production/debug mode for snf-server.ubuntu.

Updated Makefile.am to translate SYSCONFDIR (to, for example, "/etc")
and PACKAGE_NAME when generating snf-milter startup script.  Add g to
translation commands so that all occurances of the strings are
translated (needed if there are multiple occurances on a single line).

In SNFServer.xml.sample.in, changed "path" attribute of <log> element
to be /var/log/PACKAGE_NAME (which is changed to /var/log/snf-server
during building).

Updated INSTALL with instructions to create /var/log/snf-server, and
added the section on debugging (snf-server debug-mode, etc).


git-svn-id: https://svn.microneil.com/svn/PKG-SNF-CS-NIX/trunk@37 233e721a-07f6-49eb-a7da-05e0e16828fc

SNF_CS_Developer_Package/ChangeLog

@@ -1,3 +1,21 @@
+2009-06-28  Alban Deniz  <adeniz@skidmark.localdomain>
+
+	* config_files/SNFServer.xml.sample.in: Change "path" attribute of
+	<log> element to be /var/log/PACKAGE_NAME (which is changed to
+	/var/log/snf-server during building).
+
+	* INSTALL: Added instructions to create /var/log/snf-server.
+	Added section on debugging (snf-server debug-mode, etc).
+
+	* Scripts/snf-server.ubuntu: Implement debug mode and production
+	mode (Copied from snf-milter.ubuntu in snf-milter distribution).
+
+	* Scripts/Makefile.am (snf-server): Translate SYSCONFDIR (to, for
+	example, "/etc") and PACKAGE_NAME when generating snf-milter
+	startup script.  Add g to translation commands so that all
+	occurances of the strings are translated (needed if there are
+	multiple occurances on a single line).
+
 2009-06-18  Alban Deniz  <adeniz@skidmark.localdomain>
 
 	* INSTALL (Ubuntu): Added specific directions for setting up to

SNF_CS_Developer_Package/INSTALL

@@ -237,7 +237,16 @@ To configure SNFServer, do the following:
   As you modify files in these directories, please ensure that the
   read/write permissions for snfilter is maintained.
 
-  4) Download the rulebase file:
+  6) Create the logfile directory, and ensure the snfilter user has
+  read/write access to it:
+
+    mkdir /var/log/snf-server
+
+    chown snfilter:snfilter /var/log/snf-server
+
+    chmod 755 /var/log/snf-server
+
+  7) Download the rulebase file:
 
      a) 'cd /usr/share/snf-server'.  If the workspace specified in the
      configuration file is not the default, this command should be
@@ -496,3 +505,64 @@ OS-specific issues--
 
   3) RedHat, Fedora, Centos, Suse, and Ubuntu: Restart sendmail with
   '/etc/init.d/sendmail restart'.
+
+Debugging
+---------
+
+To obtain additional information for debugging, SNFServer can be run
+in debug mode.  In debug mode, additional messages are output to a
+file, and core dumps are enabled.  Debug mode is enabled and disabled
+using the snf-server startup script.  Please see the section
+"Configuring the OS" the the location of the startup script for each
+OS.
+
+To enable debug mode, run:
+
+  snf-server debug_mode
+
+Note: Running this command creates a file
+/usr/share/snf-server/debug_mode that indicates to the snf-server
+startup script to start SNFServer in debug mode.  This file contains
+brief documentation about running in debug mode.
+
+To enable production mode (non-debug mode), run:
+
+  snf-server production_mode
+
+Note: Running this command creates a file
+/usr/share/snf-server/production_mode that indicates to the snf-server
+startup script to start SNFServer in production mode.  This file has
+the same content as /usr/share/snf-server/debug_mode.
+
+After the desired mode is enabled, you can start or restart SNFServer
+using the standard procedure.
+
+In debug mode for all OSes except OpenBSD, SNFDebugServer is run with
+strace (with the '-r -tt -v' options), and all the output is written
+to /var/log/snf-server/debug.log.  Also, any core dumps are written to
+/usr/share/snf-server.
+
+In debug mode for OpenBSD, SNFDebugServer is run with ktrace.  The
+output of SNFDebugServer is written to /var/log/snf-server/debug.log,
+and the output of strace is written to /var/log/snf-server/ktrace.out.
+
+OS-specific issues--
+
+  1) FreeBSD: You'll need to ensure that core dumps are enabled.  On
+  FreeBSD 7.0, the command to do this is:
+
+    sysctl kern.coredump=1
+
+  You'll also need to ensure that /proc is mounted.  You can mount
+  /proc with the following command:
+
+    mount -t procfs proc /proc
+
+  When running in debug mode, 'snf-server start' displays the PID of
+  the strace process instead of the SNFDebugServer process.
+  'snf-server status' displays the PID values correctly.
+
+  2) OpenBSD:  Use kdump to view the kernal trace file:
+
+
+       kdump /var/log/snf-server/ktrace.out

SNF_CS_Developer_Package/Scripts/Makefile.am

@@ -62,7 +62,7 @@ getRulebase.sample:	getRulebase.in Makefile
 	chmod +x $@
 
 snf-server:	snf-server.in Makefile
-	cat @top_srcdir@/Scripts/snf-server.in | sed -e s+PREFIX+@prefix@+ -e s+CONFFILE+@sysconfdir@/@PACKAGE_NAME@/SNFServer.xml+ > $@
+	cat @top_srcdir@/Scripts/snf-server.in | sed -e s+PREFIX+@prefix@+g -e s+CONFFILE+@sysconfdir@/@PACKAGE_NAME@/SNFServer.xml+g -e s+SYSCONFDIR+@sysconfdir@+g -e s+PACKAGE_NAME+@PACKAGE_NAME@+g > $@
 	chmod +x $@
 
 snfSniffer.sample:	snfSniffer.in Makefile

SNF_CS_Developer_Package/Scripts/snf-server.ubuntu

@@ -1,7 +1,6 @@
 #! /bin/sh
 #
-# snfServer.  This shell script takes care of starting and stopping
-# the ARM Research SNFServer daemon for Ubuntu systems.
+# snf-server	Starts and stops the SNFServer daemon (Ubuntu).
 #
 # Author: Alban Deniz
 #
@@ -21,6 +20,22 @@
 #	blacklist IP addresses, etc.
 ### END INIT INFO
 
+# Directory to run in.
+runDir=PREFIX/share/PACKAGE_NAME
+
+# Define mode files.
+debugModeFile=$runDir/debug_mode
+productionModeFile=$runDir/production_mode
+
+# Set debug mode flag.
+if [ -f $debugModeFile ]
+then
+    debugMode=true
+fi
+
+# Debug output file.
+debugOutputFile=/var/log/PACKAGE_NAME/debug.log
+
 # Location of installation.
 installedDir="PREFIX"
 
@@ -31,7 +46,8 @@ dir="$installedDir/sbin"
 configFile="CONFFILE"
 
 # Name of daemon.
-prog="SNFServer"
+debugProg="SNFDebugServer"
+productionProg="SNFServer"
 
 # Name of client.
 clientProg="SNFClient"
@@ -39,27 +55,32 @@ clientProg="SNFClient"
 # Name of user to run as.
 userName="snfilter"
 
+# Name of group.
+groupName=$userName
+
 # Name of lockfile.
-lockFile="/var/lock/subsys/$prog"
+lockFile="/var/lock/subsys/$productionProg"
 
 # Name of client.
 clientProg="SNFClient"
 
-# Start command.
-snfStartCmd="$dir/$prog $configFile > /dev/null 2>&1 &"
-
 # Do NOT "set -e"
 
 # PATH should only include /usr/* if it runs after the mountnfs.sh script
 PATH=/usr/sbin:/usr/bin:/sbin:/bin
 DESC="SNFServer providing email filtering"
-NAME="snfServer"
-DAEMON=$dir/$prog
-DAEMON_ARGS="$configFile"
+NAME="snf-server"
+
+DEBUG_DAEMON="/usr/bin/strace"
+DEBUG_DAEMON_ARGS="-r -tt -v $dir/$debugProg $configFile"
+
+PRODUCTION_DAEMON=$dir/$productionProg
+PRODUCTION_DAEMON_ARGS="$configFile"
+
 SCRIPTNAME=/etc/init.d/$NAME
 
 # Exit if the package is not installed
-[ -x "$DAEMON" ] || exit 0
+[ -x "$PRODUCTION_DAEMON" ] || exit 0
 
 # Read configuration variable file if it is present
 [ -r /etc/default/$NAME ] && . /etc/default/$NAME
@@ -71,6 +92,43 @@ SCRIPTNAME=/etc/init.d/$NAME
 # Depend on lsb-base (>= 3.0-6) to ensure that this file is present.
 . /lib/lsb/init-functions
 
+#
+# Function to create the mode file.
+#
+createModeFile()
+{
+    fileName=$1
+
+    # Remove any existing mode files.
+    rm -f $productionModeFile $debugModeFile $fileName
+    (
+	echo "PACKAGE_NAME mode file"
+	echo
+	echo "This file specifies whether PACKAGE_NAME is configured to run in"
+	echo "production mode or debug mode.  If the name of this file is"
+        echo "'production_mode', then PACKAGE_NAME is configured to run in"
+        echo "production mode.  If the name is 'debug_mode', then PACKAGE_NAME is"
+        echo "configured to run in debug mode."
+	echo
+	echo "To run in debug mode:"
+	echo
+	echo "    1) Run 'PACKAGE_NAME debug_mode'"
+	echo
+	echo "    2) Run 'PACKAGE_NAME restart' (if PACKAGE_NAME is already running),"
+	echo "       or 'PACKAGE_NAME start' (to start PACKAGE_NAME)"
+	echo
+	echo "To run in production mode:"
+	echo
+	echo "    1) Run 'PACKAGE_NAME production_mode'"
+	echo
+	echo "    2) Run 'PACKAGE_NAME restart' (if PACKAGE_NAME is already running),"
+	echo "       or 'PACKAGE_NAME start' (to start PACKAGE_NAME)"
+	echo
+	echo "By default, PACKAGE_NAME is configured to run in production mode."
+	) > $fileName
+
+}
+
 #
 # Function that starts the daemon/service
 #
@@ -81,11 +139,34 @@ do_start()
 	#   1 if daemon was already running
 	#   2 if daemon could not be started
 	start-stop-daemon --chuid $userName --start --quiet \
-	    --exec $DAEMON --test > /dev/null 2>&1 \
-		|| return 1
-	start-stop-daemon --chuid $userName --start --quiet \
-	    --background --exec $DAEMON -- $DAEMON_ARGS > /dev/null 2>&1 \
-	    || return 2
+	    --exec $PRODUCTION_DAEMON --test > /dev/null 2>&1 \
+	    || return 1
+
+	if [ $debugMode ]
+	then
+
+	    # Enable core dumps.
+	    ulimit -c unlimited
+
+	    # Add date to the debug file.
+	    echo "Starting $DEBUG_DAEMON $DEBUG_DAEMON_ARGS on " $(date) >> \
+		$debugOutputFile
+            chown $userName:$groupName $debugOutputFile
+
+	    # Start with output redirected.
+	    start-stop-daemon --chuid $userName --start --quiet \
+		--chdir $runDir \
+		--exec $DEBUG_DAEMON -- $DEBUG_DAEMON_ARGS >> \
+		$debugOutputFile 2>&1 \
+		|| return 2 &
+	else
+
+	    start-stop-daemon --chuid $userName --start --quiet \
+		--chdir $runDir \
+		--background --exec $PRODUCTION_DAEMON -- \
+		$PRODUCTION_DAEMON_ARGS > /dev/null 2>&1 || return 2
+	fi
+
 	# Check that process started.
 	$dir/$clientProg -status.second > /dev/null 2>&1
 	RETVAL=$?
@@ -107,7 +188,7 @@ do_stop()
 	#   other if a failure occurred
         # Check whether SNFServer is running.
 	start-stop-daemon --chuid $userName --start --quiet \
-	    --exec $DAEMON --test > /dev/null
+	    --exec $PRODUCTION_DAEMON --test > /dev/null
 	RETVAL=$?
 
 	if [ $RETVAL -ne 1 ]; then
@@ -120,12 +201,12 @@ do_stop()
 
         # Check again whether SNFServer is running.
 	start-stop-daemon --chuid $userName --start --quiet \
-	    --exec $DAEMON --test > /dev/null
+	    --exec $PRODUCTION_DAEMON --test > /dev/null
 	RETVAL=$?
 
 	if [ $RETVAL -eq 1 ] ; then
 	    # Send TERM signal to stop SNFServer.
-	    start-stop-daemon --stop --quiet --retry=TERM/5 --exec $DAEMON
+	    start-stop-daemon --stop --quiet --retry=TERM/5 --exec $PRODUCTION_DAEMON
 	    RETVAL="$?"
 	    [ "$RETVAL" = 2 ] && return 2
 	    return "$RETVAL"
@@ -155,14 +236,14 @@ case "$1" in
 	;;
   status)
 	start-stop-daemon --chuid $userName --start --quiet \
-	    --exec $DAEMON --test > /dev/null
+	    --exec $PRODUCTION_DAEMON --test > /dev/null
 	RETVAL=$?
 	if [ $RETVAL -eq 0 ]; then
 	    # Stopped
-	    echo "$prog is stopped"
+	    echo "$productionProg is stopped"
 	else
 	    # Running
-	    echo "$prog (pid $(pidof $dir/$prog)) is running"
+	    echo "$productionProg (pid $(pidof $PRODUCTION_DAEMON)) is running"
 	fi
 	;;
   restart|force-reload)
@@ -187,8 +268,22 @@ case "$1" in
 		;;
 	esac
 	;;
+  debug_mode)
+	#
+	# Remove any mode flags, and create the debug_mode file.
+	#
+	log_daemon_msg "Switching to debug mode $DESC" "$NAME"
+	createModeFile $debugModeFile
+	;;
+  production_mode)
+	#
+	# Remove any mode flags, and create the production_mode file.
+	#
+	log_daemon_msg "Switching to production mode $DESC" "$NAME"
+	createModeFile $productionModeFile
+	;;
   *)
-	echo "Usage: $SCRIPTNAME {start|stop|status|restart|force-reload}" >&2
+	echo "Usage: $SCRIPTNAME {start|stop|status|restart|force-reload|production_mode|debug_mode}" >&2
 	exit 3
 	;;
 esac

SNF_CS_Developer_Package/config_files/SNFServer.xml.sample.in

@@ -5,7 +5,7 @@
     <node identity='SYSCONFDIR/PACKAGE_NAME/identity.xml'>
 
         <paths>
-            <log path='PREFIX/share/PACKAGE_NAME/'/>
+            <log path='/var/log/PACKAGE_NAME/'/>
             <rulebase path='PREFIX/share/PACKAGE_NAME/'/>
             <workspace path='PREFIX/share/PACKAGE_NAME/'/>
         </paths>