Bugzilla Bug #529070 - rpm packaging problems (cannot reinstall correctly)

Resolved by implementing a "registry".


git-svn-id: svn+ssh://svn.fedorahosted.org/svn/pki/trunk@892 c9f7a03b-bd48-0410-a16d-cbbf54688b0b

4 files changed, 729 insertions, 252 deletions

diff --git a/pki/base/ca/LICENSE b/pki/base/ca/LICENSE
index e36f2269a..e281f4362 100644
--- a/pki/base/ca/LICENSE
+++ b/pki/base/ca/LICENSE
@@ -11,26 +11,6 @@ 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., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA.
  
-In addition, as a special exception, Red Hat, Inc. gives You the additional 
-right to link the code of this Program with code not covered under the GNU 
-General Public License ("Non-GPL Code") and to distribute linked combinations 
-including the two, subject to the limitations in this paragraph. Non-GPL 
-Code permitted under this exception must only link to the code of this 
-Program through those well defined interfaces identified in the file named 
-EXCEPTION found in the source code files (the "Approved Interfaces"). 
- 
-The files of Non-GPL Code may instantiate templates or use macros or inline
-functions from the Approved Interfaces without causing the resulting work to 
-be covered by the GNU General Public License. Only Red Hat, Inc. may make 
-changes or additions to the list of Approved Interfaces. You must obey the 
-GNU General Public License in all respects for all of the Program code and 
-other code used in conjunction with the Program except the Non-GPL Code 
-covered by this exception. If you modify this file, you may extend this 
-exception to your version of the file, but you are not obligated to do so. 
-If you do not wish to provide this exception without modification, you must 
-delete this exception statement from your version and license this file 
-solely under the GPL without exception.
-
 		    GNU GENERAL PUBLIC LICENSE
 		       Version 2, June 1991
 
diff --git a/pki/base/ca/build.xml b/pki/base/ca/build.xml
index 8795aeb6c..139e221cb 100644
--- a/pki/base/ca/build.xml
+++ b/pki/base/ca/build.xml
@@ -184,31 +184,30 @@
         <zip destfile="${dist.base.binaries}/${dist.name}.zip">
             <zipfileset dir="./build/jars"
                         filemode="755"
-                        prefix="usr/share/java/${product.prefix}/${product}">
+                        prefix="usr/share/java">
                 <include name="**"/>
             </zipfileset>
             <zipfileset dir="./setup"
-                        filemode="755"
-                        prefix="usr/share/${product.prefix}/${product}/setup">
-                <include name="postinstall"/>
-            </zipfileset>
-            <zipfileset dir="./setup"
                         filemode="644"
                         prefix="usr/share/${product.prefix}/${product}/setup">
                 <include name="config.desktop"/>
             </zipfileset>
+            <zipfileset dir="./shared/etc/init.d"
+                        filemode="755"
+                        prefix="etc/${init.d}">
+                <include name="pki-cad"/>
+            </zipfileset>
             <zipfileset dir="./shared"
                         filemode="755"
                         prefix="usr/share/${product.prefix}/${product}">
                 <include name="conf/dtomcat5"/>
-                <include name="etc/init.d/httpd"/>
             </zipfileset>
             <zipfileset dir="./shared"
                         filemode="644"
                         prefix="usr/share/${product.prefix}/${product}">
                 <include name="**"/>
                 <exclude name="conf/dtomcat5"/>
-                <exclude name="etc/init.d/httpd"/>
+                <exclude name="etc/init.d/pki-cad"/>
             </zipfileset>
             <zipfileset dir="."
                         filemode="644"
@@ -224,31 +223,30 @@
              destfile="${dist.base.binaries}/${dist.name}.tar">
             <tarfileset dir="./build/jars"
                         mode="755"
-                        prefix="${dist.name}/usr/share/java/${product.prefix}/${product}">
+                        prefix="${dist.name}/usr/share/java">
                 <include name="**"/>
             </tarfileset>
             <tarfileset dir="./setup"
-                        mode="755"
-                        prefix="${dist.name}/usr/share/${product.prefix}/${product}/setup">
-                <include name="postinstall"/>
-            </tarfileset>
-            <tarfileset dir="./setup"
                         mode="644"
                         prefix="${dist.name}/usr/share/${product.prefix}/${product}/setup">
                 <include name="config.desktop"/>
             </tarfileset>
+            <tarfileset dir="./shared/etc/init.d"
+                        mode="755"
+                        prefix="${dist.name}/etc/${init.d}">
+                <include name="pki-cad"/>                 
+            </tarfileset>
             <tarfileset dir="./shared"
                         mode="755"
                         prefix="${dist.name}/usr/share/${product.prefix}/${product}">
                 <include name="conf/dtomcat5"/>
-                <include name="etc/init.d/httpd"/>                 
             </tarfileset>
             <tarfileset dir="./shared"
                         mode="644"
                         prefix="${dist.name}/usr/share/${product.prefix}/${product}">
                 <include name="**"/>
                 <exclude name="conf/dtomcat5"/>
-                <exclude name="etc/init.d/httpd"/>
+                <exclude name="etc/init.d/pki-cad"/>
             </tarfileset>
             <tarfileset dir="."
                         mode="644"
diff --git a/pki/base/ca/setup/postinstall b/pki/base/ca/setup/postinstall
deleted file mode 100755
index 055a6568a..000000000
--- a/pki/base/ca/setup/postinstall
+++ /dev/null
@@ -1,68 +0,0 @@
-#!/bin/bash
-#
-# --- BEGIN COPYRIGHT BLOCK ---
-# This program 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; version 2 of the License.
-#
-# This program 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.
-#
-# Copyright (C) 2007 Red Hat, Inc.
-# All rights reserved.
-# --- END COPYRIGHT BLOCK ---
-#
-
-###############################################################################
-##  (1)  Check command line arguments to see how many were passed in.        ##
-###############################################################################
-                                                                                
-if [ $# -eq 4 ]
-then
-	PKI_PRODUCT_NAME=$1
-	PKI_SUBSYSTEM_NAME=$2
-	VERSION=$3
-	RELEASE=$4
-else
-	echo
-	echo "Usage:  $0 PKI_product_name PKI_subsystem_name version release"
-	echo
-
-	exit 255
-fi
-
-
-###############################################################################
-##  (2)  Specify variables used by this script.                              ##
-###############################################################################
-
-PKI_INSTANCE_NAME="${PKI_PRODUCT_NAME}-${PKI_SUBSYSTEM_NAME}"
-AGENT_SECURE_PORT=9443
-EE_SECURE_PORT=9444
-ADMIN_SECURE_PORT=9445
-UNSECURE_PORT=9180
-TOMCAT_SERVER_PORT=9701
-
-
-###############################################################################
-##  (3)  Create the first instance of a Certificate Authority (CA).          ##
-###############################################################################
-
-if [ ! -e "/var/lib/${PKI_INSTANCE_NAME}" ]
-then
-	/usr/bin/pkicreate -pki_instance_root=/var/lib -pki_instance_name=${PKI_INSTANCE_NAME} -subsystem_type=${PKI_SUBSYSTEM_NAME} -agent_secure_port=${AGENT_SECURE_PORT} -ee_secure_port=${EE_SECURE_PORT} -admin_secure_port=${ADMIN_SECURE_PORT} -unsecure_port=${UNSECURE_PORT} -tomcat_server_port=${TOMCAT_SERVER_PORT} -redirect conf=/etc/${PKI_INSTANCE_NAME} -redirect logs=/var/log/${PKI_INSTANCE_NAME}
-fi
-
-
-###############################################################################
-##  (4)  Successfully exit from this postinstallation script.                ##
-###############################################################################
-
-exit 0
-
diff --git a/pki/base/ca/shared/etc/init.d/httpd b/pki/base/ca/shared/etc/init.d/pki-cad
index 6183fe792..be68eed2e 100755
--- a/pki/base/ca/shared/etc/init.d/httpd
+++ b/pki/base/ca/shared/etc/init.d/pki-cad
@@ -18,14 +18,14 @@
 # All rights reserved.
 # --- END COPYRIGHT BLOCK ### ---
 #
-# [PKI_INSTANCE_ID]    Startup script for Tomcat 5.0, the Apache Servlet Engine
+# pki-cad    Startup script for Tomcat 5.0 pki-ca, the Apache Servlet Engine
 #
 # chkconfig:    - 81 19
 # description:  Certificate Authority \
 #               (Tomcat 5.0)
-# processname:  [PKI_INSTANCE_ID]
-# pidfile:      /var/run/[PKI_INSTANCE_ID].pid
-# config:       [PKI_INSTANCE_PATH]/conf/tomcat5.conf
+# processname:  pki-cad
+# piddir:       /var/run/pki/ca
+# config:       ${PKI_INSTANCE_PATH}/conf/tomcat5.conf
 #
 # Gomez Henri <hgomez@users.sourceforge.net>
 # Keith Irwin <keith_irwin@non.hp.com>
@@ -60,23 +60,70 @@
 # version 1.20tc5rh - Changed TOMCAT_USER from tomcat4 to tomcat
 #
 
+PKI_INIT_SCRIPT=""
+PKI_PATH="/usr/share/pki/ca"
+PKI_PIDDIR="/var/run/pki/ca"
+PKI_PROCESS="pki-cad"
+PKI_REGISTRY="/etc/sysconfig/pki/ca"
+PKI_TYPE="pki-ca"
+
+# PKI subsystem-level directory and file values for locks
+lockfile="/var/lock/subsys/pki-cad"
+
 # Disallow 'others' the ability to 'write' to new files
 umask 00002
 
+default_error=0
+command="$1"
+pki_instance="$2"
+case "${command}" in
+	start|stop|restart|condrestart|force-restart|try-restart)
+		# * 1 generic or unspecified error (current practice)
+		default_error=1
+		;;
+	reload)
+		default_error=3
+		;;
+	status)
+		# * 4 program or service status is unknown
+		default_error=4
+		;;
+	*)
+		# * 2 invalid argument(s)
+		default_error=2
+		;;
+esac
+
 # Check to insure that this script's original invocation directory
 # has not been deleted!
 CWD=`/bin/pwd > /dev/null 2>&1`
 if [ $? -ne 0 ] ; then
 	echo "Cannot invoke '$0' from non-existent directory!"
-	exit 255
+	exit ${default_error}
 fi
 
 # Check to insure that this script's associated PKI
 # subsystem currently resides on this system.
-PKI_SUBSYSTEM_TYPE=[PKI_SUBSYSTEM_TYPE]
-if [ ! -d /usr/share/pki/${PKI_SUBSYSTEM_TYPE} ] ; then
-	echo "This machine is missing the '${PKI_SUBSYSTEM_TYPE}' subsystem!"
-	exit 255
+if [ ! -d ${PKI_PATH} ] ; then
+	echo "This machine is missing the '${PKI_TYPE}' subsystem!"
+	if [ "${command}" != "status" ]; then
+		# * 5 program is not installed
+		exit 5
+	else
+		exit ${default_error}
+	fi
+fi
+
+# Check to insure that this script's associated PKI
+# subsystem instance registry currently resides on this system.
+if [ ! -d ${PKI_REGISTRY} ] ; then
+	echo "This machine contains no registered '${PKI_TYPE}' subsystem instances!"
+	if [ "${command}" != "status" ]; then
+		# * 5 program is not installed
+		exit 5
+	else
+		exit ${default_error}
+	fi
 fi
 
 # Obtain the operating system upon which this script is being executed
@@ -86,15 +133,29 @@ ARCHITECTURE=""
 # This script must be run as root!
 RV=0
 if [ ${OS} = "Linux" ] ; then
+	PKI_INIT_SCRIPT="/sbin/service ${PKI_PROCESS}"
 	if [ `id -u` -ne 0 ] ; then
 		echo "Must be 'root' to execute '$0'!"
-		exit 1
+		if [ "${command}" != "status" ]; then
+			# * 4 user had insufficient privilege
+			exit 4
+		else
+			# * 4 program or service status is unknown
+			exit 4
+		fi
 	fi
 	ARCHITECTURE=`uname -i`
 elif [ ${OS} = "SunOS" ] ; then
+	PKI_INIT_SCRIPT="/etc/init.d/${PKI_PROCESS}"
 	if [ `/usr/xpg4/bin/id -u` -ne 0 ] ; then
 		echo "Must be 'root' to execute '$0'!"
-		exit 1
+		if [ "${command}" != "status" ]; then
+			# * 4 user had insufficient privilege
+			exit 4
+		else
+			# * 4 program or service status is unknown
+			exit 4
+		fi
 	fi
 	ARCHITECTURE=`uname -p`
 	if	[ "${ARCHITECTURE}" = "sparc" ] &&
@@ -103,7 +164,7 @@ elif [ ${OS} = "SunOS" ] ; then
 	fi
 else
 	echo "Unsupported OS '${OS}'!"
-	exit 1
+	exit ${default_error}
 fi
 
 # Source function library.
@@ -120,25 +181,32 @@ else
 		for i in $* ; do
 			ps -p $i > /dev/null 2>&1 ;
 			if [ $? -ne 0 ] ; then
-				rv=`expr $rv + 1`
+				rv=`expr ${rv} + 1`
 			else
-				rv=`expr $rv + 0`
+				rv=`expr ${rv} + 0`
 			fi
 		done
-		# echo "rv=$rv"
-		return $rv
+		# echo "rv=${rv}"
+		return ${rv}
 	}
 
 	# Create the following directories on platforms
 	# where they do not exist (e. g. - Solaris) . . .
-	if [ ! -d /var/lock/subsys ] ; then
+	if [ ! -d "/var/lock" ] ; then
+		mkdir -p /var/lock
+		chown root:sys /var/lock
+		chmod 00755 /var/lock
+	fi
+	if [ ! -d "/var/lock/subsys" ] ; then
 		mkdir -p /var/lock/subsys
+		chown root:root /var/lock/subsys
+		chmod 00755 /var/lock/subsys
 	fi
 
 	#######################################################################
 	## NOTE:  The following code needs to eventually be moved into the   ##
 	##        template used to create the                                ##
-	##        "[PKI_INSTANCE_PATH]/conf/tomcat5.conf" file!              ##
+	##        "${PKI_INSTANCE_PATH}/conf/tomcat5.conf" file!             ##
 	#######################################################################
 
 	if [ ${OS} = "SunOS" ] ; then
@@ -162,53 +230,129 @@ else
 			echo -n "at \"${DEFAULT_SOLARIS_JAVA_HOME}\"!"
 			echo
 			echo
-			exit 255
+			exit ${default_error}
 		fi
 	fi
 fi
 
-#Use CATALINA_BASE
-
-CATALINA_BASE=[PKI_INSTANCE_PATH]
-export CATALINA_BASE
+PKI_REGISTRY_ENTRIES=""
+TOTAL_PKI_REGISTRY_ENTRIES=0
+TOTAL_UNCONFIGURED_PKI_ENTRIES=0
 
-# Get Tomcat config
+# Gather ALL registered instances of this PKI subsystem type
+for FILE in `/bin/ls -1 ${PKI_REGISTRY}/* 2>/dev/null`; do
+	if [ -f "$FILE" ] ; then
+		inst=`echo "$FILE"`
+		PKI_REGISTRY_ENTRIES="${PKI_REGISTRY_ENTRIES} $inst"
+		TOTAL_PKI_REGISTRY_ENTRIES=`expr ${TOTAL_PKI_REGISTRY_ENTRIES} + 1`
+	fi
+done
 
-TOMCAT_CFG="[PKI_INSTANCE_PATH]/conf/tomcat5.conf"
+if [ -n "${pki_instance}" ]; then
+	for I in ${PKI_REGISTRY_ENTRIES}; do
+		if [ "${PKI_REGISTRY}/${pki_instance}" = "$I" ]; then
+			PKI_REGISTRY_ENTRIES="${PKI_REGISTRY}/${pki_instance}"
+			TOTAL_PKI_REGISTRY_ENTRIES=1
+			break
+		fi
+	done
+fi
 
-[ -r "$TOMCAT_CFG" ] && . "${TOMCAT_CFG}"
+usage()
+{
+	echo -n "Usage: ${PKI_INIT_SCRIPT} "
+	echo -n "{start"
+	echo -n "|stop"
+	echo -n "|restart"
+	echo -n "|condrestart"
+	echo -n "|force-restart"
+	echo -n "|try-restart"
+	echo -n "|reload"
+	echo -n "|status} "
+	echo -n "[instance-name]"
+	echo
+	echo
+}
 
-# Path to the tomcat launch script (direct don't use wrapper)
-TOMCAT_SCRIPT=/usr/bin/dtomcat5-[PKI_INSTANCE_ID]
+list_instances()
+{
+	echo
+	for FILE in `/bin/ls -1 ${PKI_REGISTRY}/* 2>/dev/null`; do
+		echo "    ${FILE}"
+	done
+	echo
+}
 
-# Path to the script that will refresh jar symlinks on startup
-if [ ${OS} = "Linux" ] ; then
-	TOMCAT_RELINK_SCRIPT="/usr/share/tomcat5/bin/relink"
+# Check arguments
+if [ $# -lt 1 ] ; then
+	# * 3 unimplemented feature (for example, "reload")
+	#     [insufficient arguments]
+	echo "$0:  Insufficient arguments!"
+	echo
+	usage
+	echo "where valid instance names include:"
+	list_instances
+	exit 3
+elif [ ${default_error} -eq 2 ] ; then
+	# * 2 invalid argument
+	echo "$0:  Invalid arguments!"
+	echo
+	usage
+	echo "where valid instance names include:"
+	list_instances
+	exit 2
+elif [ $# -gt 2 ] ; then
+	echo "$0:  Excess arguments!"
+	echo
+	usage
+	echo "where valid instance names include:"
+	list_instances
+	if [ "${command}" != "status" ]; then
+		# * 2 excess arguments
+		exit 2
+	else
+		# * 4 program or service status is unknown
+		exit 4
+	fi
 fi
 
-# Tomcat name :)
-TOMCAT_PROG=[PKI_INSTANCE_ID]
-
-# if TOMCAT_USER is not set, use tomcat5 like Apache HTTP server
-if [ -z "$TOMCAT_USER" ]; then
-	TOMCAT_USER="[PKI_USER]"
+# If an "instance" was supplied, check that it is a "valid" instance
+if [ -n "${pki_instance}" ]; then
+	if [ "${PKI_REGISTRY}/${pki_instance}" != "${PKI_REGISTRY_ENTRIES}" ]; then
+		echo -n "${pki_instance} is an invalid '${PKI_TYPE}' instance"
+		echo_failure
+		echo
+		if [ "${command}" != "status" ]; then
+			# * 5 program is not installed
+			exit 5
+		else
+			# * 4 program or service status is unknown
+			exit 4
+		fi
+	fi
 fi
 
-# if TOMCAT_GROUP is not set, use tomcat5 like Apache HTTP server
-if [ -z "$TOMCAT_GROUP" ]; then
-	TOMCAT_GROUP="[PKI_GROUP]"
-fi
+# On Solaris /var/run is in tmpfs and gets wiped out upon reboot
+# we have to recreate the ${PKI_PIDDIR} directory and make sure that
+# the directory is writable by the ${PKI_TYPE} server process.
+#
+# IMPORTANT:  ALL PKI subsystems installed on this machine MUST utilize
+#             the SAME values for ${PKI_GROUP} and ${PKI_USER}, since the
+#             "${PKI_PIDDIR}" will end up with the ownership permissions
+#             of the first instance that executes this function!
+#
+fix_pid_dir_ownership()
+{
+	if [ ! -d ${PKI_PIDDIR} ] ; then
+		mkdir -p ${PKI_PIDDIR}
 
-# Since the daemon function will sandbox $tomcat
-# no environment stuff should be defined here anymore.
-# Please use the [PKI_INSTANCE_PATH]/conf/tomcat5.conf
-# file instead ; it will be read by the $tomcat script
+		chown root:root /var/run/pki
+		chmod 00755 /var/run/pki
 
-pidfile=${PIDFILE:-/var/run/[PKI_INSTANCE_ID].pid}
-lockfile=${LOCKFILE:-/var/lock/subsys/[PKI_INSTANCE_ID]}
-pki_instance_configuration_file=[PKI_INSTANCE_PATH]/conf/CS.cfg
-RESTART_SERVER=[PKI_INSTANCE_PATH]/conf/restart_server_after_configuration
-RETVAL=0
+		chown root:root ${PKI_PIDDIR}
+		chmod 00755 ${PKI_PIDDIR}
+	fi
+}
 
 check_pki_configuration_status()
 {
@@ -219,11 +363,27 @@ check_pki_configuration_status()
 	rv=`expr ${rv} + 0`
 
 	if [ ${rv} -ne 0 ] ; then
-		echo "    '[PKI_INSTANCE_ID]' must still be CONFIGURED!"
-		echo "    (see /var/log/[PKI_INSTANCE_ID]-install.log)"
+		echo "    '${PKI_INSTANCE_ID}' must still be CONFIGURED!"
+		echo "    (see /var/log/${PKI_INSTANCE_ID}-install.log)"
+		if [ "${command}" != "status" ]; then
+			# * 6 program is not configured
+			rv=6
+		else
+			# * 4 program or service status is unknown
+			rv=4
+		fi
+		TOTAL_UNCONFIGURED_PKI_ENTRIES=`expr ${TOTAL_UNCONFIGURED_PKI_ENTRIES} + 1`
 	elif [ -f ${RESTART_SERVER} ] ; then
-		echo "    Although '[PKI_INSTANCE_ID]' has been CONFIGURED, it must still be RESTARTED!"
-		rv=255
+		echo -n "    Although '${PKI_INSTANCE_ID}' has been CONFIGURED, "
+		echo -n "it must still be RESTARTED!"
+		echo
+		if [ "${command}" != "status" ]; then
+			# * 1 generic or unspecified error (current practice)
+			rv=1
+		else
+			# * 4 program or service status is unknown
+			rv=4
+		fi
 	fi
 
 	return ${rv}
@@ -246,14 +406,14 @@ get_pki_status_definitions()
 	pki_status_comment_found=0
 
 	# first check to see that an instance-specific "server.xml" file exists
-	if [ ! -f [PKI_SERVER_XML_CONF] ] ; then
-		echo "File '[PKI_SERVER_XML_CONF]' does not exist!"
-		exit 255
+	if [ ! -f ${PKI_SERVER_XML_CONF} ] ; then
+		echo "File '${PKI_SERVER_XML_CONF}' does not exist!"
+		exit ${default_error}
 	fi
 
 	# read this instance-specific "server.xml" file line-by-line
 	# to obtain the current PKI Status Definitions
-	exec < [PKI_SERVER_XML_CONF]
+	exec < ${PKI_SERVER_XML_CONF}
 	while read line; do
 		# first look for the well-known end PKI Status comment
 		# (to turn off processing)
@@ -283,12 +443,12 @@ get_pki_status_definitions()
 				total_ports=`expr ${total_ports} + 1`
 			fi
 		fi
-    done
+	done
 
 	if [ ${total_ports} -eq 6 ] ; then
 		return 0
 	else
-		return 255
+		return ${default_error}
 	fi
 }
 
@@ -305,14 +465,14 @@ get_pki_configuration_definitions()
 			[ "${pki_subsystem}" != "RA"   ]  &&
 			[ "${pki_subsystem}" != "TPS"  ]
 		then
-			return 255
+			return ${default_error}
 		fi
 		if	[ "${pki_subsystem}" == "KRA"   ] ; then
 			# Rename "KRA" to "DRM"
 			pki_subsystem="DRM"
 		fi
 	else
-		return 255
+		return ${default_error}
 	fi
 
 	# If "${pki_subsystem}" is a CA, DRM, OCSP, or TKS,
@@ -331,7 +491,7 @@ get_pki_configuration_definitions()
 				pki_clone=""
 			fi
 		else
-			return 255
+			return ${default_error}
 		fi
 	fi
 
@@ -345,7 +505,7 @@ get_pki_configuration_definitions()
 		if [ "${line}" != "" ] ; then
 			pki_hierarchy=`echo "${line}" | cut -b18-`
 		else
-			return 255
+			return ${default_error}
 		fi
 	fi
 
@@ -364,7 +524,7 @@ get_pki_configuration_definitions()
 				pki_security_domain=""
 			fi
 		else
-			return 255
+			return ${default_error}
 		fi
 	fi
 
@@ -378,25 +538,25 @@ get_pki_configuration_definitions()
 	if [ "${line}" != "" ] ; then
 		pki_security_domain_name=`echo "${line}" | cut -b21-`
 	else
-		return 255
+		return ${default_error}
 	fi
 
 	line=`grep ^securitydomain.host= ${pki_instance_configuration_file}`
 	if [ "${line}" != "" ] ; then
 		pki_security_domain_hostname=`echo "${line}" | cut -b21-`
 	else
-		return 255
+		return ${default_error}
 	fi
 
 	line=`grep ^securitydomain.httpsadminport= ${pki_instance_configuration_file}`
 	if [ "${line}" != "" ] ; then
 		pki_security_domain_https_admin_port=`echo "${line}" | cut -b31-`
 	else
-		return 255
+		return ${default_error}
 	fi
 
 	# Compose the "PKI Instance Name" Status Line
-	pki_instance_name="PKI Instance Name:   [PKI_INSTANCE_ID]"
+	pki_instance_name="PKI Instance Name:   ${PKI_INSTANCE_ID}"
 
 	# Compose the "PKI Subsystem Type" Status Line
 	header="PKI Subsystem Type: "
@@ -456,7 +616,7 @@ get_pki_configuration_definitions()
 	then
 		data="https://${pki_security_domain_hostname}:${pki_security_domain_https_admin_port}"
 	else
-		return 255
+		return ${default_error}
 	fi
 	registered_pki_security_domain_url="${header} ${data}"
 
@@ -490,14 +650,14 @@ get_pki_secure_port()
 	ssl_comment_found=0
 
 	# first check to see that an instance-specific "server.xml" file exists
-	if [ ! -f [PKI_SERVER_XML_CONF] ] ; then
-		echo "File '[PKI_SERVER_XML_CONF]' does not exist!"
-		exit 255
+	if [ ! -f ${PKI_SERVER_XML_CONF} ] ; then
+		echo "File '${PKI_SERVER_XML_CONF}' does not exist!"
+		exit ${default_error}
 	fi
 
 	# read this instance-specific "server.xml" file line-by-line
 	# to obtain the current value of the PKI secure port
-	exec < [PKI_SERVER_XML_CONF]
+	exec < ${PKI_SERVER_XML_CONF}
 	while read line; do
 		# first look for the well-known end SSL comment
 		# (to turn off processing)
@@ -530,48 +690,177 @@ get_pki_secure_port()
 				fi
 			fi
 		fi
-    done
+	done
 
-	return 255
+	return ${default_error}
 }
 
-start()
+display_instance_status()
+{
+	rv=0
+
+	if [ -f ${pidfile} ] ; then
+		pid=`cat ${pidfile}`
+		if [ "${pid}" == "" ] ; then
+			echo "${PKI_INSTANCE_ID} pid file exists but is empty"
+			if [ "${command}" != "status" ]; then
+				# * 1 generic or unspecified error (current practice)
+				rv=1
+			else
+				# * 4 program or service status is unknown
+				rv=4
+			fi
+		elif kill -0 ${pid} > /dev/null 2>&1 ; then
+			echo "${PKI_INSTANCE_ID} (pid ${pid}) is running ..."
+			echo
+			check_pki_configuration_status
+			rv=$?
+			if [ ${rv} -eq 0 ] ; then
+				get_pki_status_definitions
+				rv=$?
+				if [ ${rv} -ne 0 ] ; then
+					echo
+					echo "${PKI_INSTANCE_ID} Status Definitions not found"
+				else
+					get_pki_configuration_definitions
+					rv=$?
+					if [ ${rv} -ne 0 ] ; then
+						echo
+						echo "${PKI_INSTANCE_ID} Configuration Definitions not found"
+					fi
+				fi
+			else
+				# From the PKI point of view for a "non-status" action,
+				# a returned error code of "6" implies that the program
+				# is not "configured".  Similarly, an error code of "1"
+				# implies that the program was "configured" but must
+				# still be restarted.
+				#
+				# Similarly, from the PKI point of view for a "status"
+				# action, a returned error code of "4" implies that either
+				# the program is not "configured", or that the program
+				# was "configured" but must still be restarted.
+				#
+				# Regardless, it must still be considered that the instance
+				# is "running" from the viewpoint of other OS programs such
+				# as 'chkconfig'.
+				#
+				# For this reason, when returning from
+				# 'display_instance_status()', ignore non-zero return codes
+				# returned from 'check_pki_configuration_status()'.
+				#
+				if [ "${command}" != "status" ]; then
+					# * 0 action was successful
+					rv=0
+				else
+					# * 0 program is running or service is OK
+					rv=0
+				fi
+			fi
+			echo
+		else
+			echo "${PKI_INSTANCE_ID} is dead but pid file exists"
+			if [ "${command}" != "status" ]; then
+				# * 1 generic or unspecified error (current practice)
+				rv=1
+			else
+				# * 1 program is dead and /var/run pid file exists
+				rv=1
+			fi
+		fi
+	else
+		echo "${PKI_INSTANCE_ID} is stopped"
+		if [ "${command}" != "status" ]; then
+			# * 7 program is not running
+			rv=7
+		else
+			# * 3 program is not running
+			rv=3
+		fi
+	fi
+
+	return ${rv}
+}
+
+start_instance()
 {
+	rv=0
+
 	echo -n "Starting $TOMCAT_PROG: "
 
 	if [ -f ${RESTART_SERVER} ] ; then
 		rm -f ${RESTART_SERVER}
 	fi
 
-	if [ -f ${lockfile} ] ; then
+	if [ -f ${PKI_LOCKFILE} ] ; then
 		if [ -f ${pidfile} ]; then
 			read kpid < ${pidfile}
 			if checkpid $kpid 2>&1; then
 				echo
-				echo "process already running"
-				return 255
+				echo "${PKI_INSTANCE_ID} (pid ${kpid}) is already running ..."
+				echo
+				check_pki_configuration_status
+				rv=$?
+				if [ ${rv} != 0 ]; then
+					# From the PKI point of view for a "non-status" action,
+					# a returned error code of "6" implies that the program
+					# is not "configured".  Similarly, an error code of "1"
+					# implies that the program was "configured" but must
+					# still be restarted.
+					#
+					# Regardless, it must still be considered that the instance
+					# is "running" from the viewpoint of other OS programs such
+					# as 'chkconfig'.
+					#
+					# For "non-status" actions, ignore return codes of "1"
+					# from 'check_pki_configuration_status()'.
+					#
+					# However, for "non-status" actions that have a return
+					# code of "6", return this value unchanged to
+					# the calling routine so that the total number of
+					# configuration errors may be counted.
+					#
+
+					echo
+					if [ ${rv} = 1 ] ; then
+						# * 0 action was successful
+						return 0
+					elif [ ${rv} = 6 ] ; then
+						# * 6 program is not configured
+						return 6
+					else
+						# should never be reached
+						return ${rv}
+					fi
+				else
+					return 0
+				fi
 			else
 				echo
 				echo -n "lock file found but no process "
 				echo -n "running for pid $kpid, continuing"
 				echo
 				echo
+				rm -f ${PKI_LOCKFILE}
 			fi
 		fi
 	fi
 
+	fix_pid_dir_ownership
+
 	CATALINA_PID=${pidfile}
 	export CATALINA_PID
 	touch $CATALINA_PID
 	chown $TOMCAT_USER:$TOMCAT_GROUP $CATALINA_PID
-  	[ -x /sbin/restorecon ] && /sbin/restorecon  $CATALINA_PID
+	chmod 00600 $CATALINA_PID
+	[ -x /sbin/restorecon ] && /sbin/restorecon  $CATALINA_PID
 
-        # restore context for ncipher hsm
-        [ -x /sbin/restorecon ] && [ -d /dev/nfast ] && /sbin/restorecon -R /dev/nfast
+	# restore context for ncipher hsm
+	[ -x /sbin/restorecon ] && [ -d /dev/nfast ] && /sbin/restorecon -R /dev/nfast
 
 	# Always initialize CLASSPATH to start looking
 	# in the local PKI classes directory . . .
-	CLASSPATH=/usr/share/[PKI_FLAVOR]/classes
+	CLASSPATH=/usr/share/pki/classes
 
 	if [ ${OS} = "Linux" ] ; then
 		$TOMCAT_RELINK_SCRIPT
@@ -790,7 +1079,7 @@ start()
 		if [ ! -e /var/lib/tomcat5/common/lib/\[javamail\]pop3\-1.3.1.jar ]; then
 			ln -s /usr/share/java/javamail/pop3-1.3.1.jar [javamail]pop3-1.3.1.jar
 		fi
-			if [ ! -e /var/lib/tomcat5/common/lib/\[javamail\]pop3.jar ]; then
+		if [ ! -e /var/lib/tomcat5/common/lib/\[javamail\]pop3.jar ]; then
 			ln -s /usr/share/java/javamail/pop3.jar [javamail]pop3.jar
 		fi
 		if [ ! -e /var/lib/tomcat5/common/lib/\[javamail\]providers\-1.3.1.jar ]; then
@@ -1053,17 +1342,21 @@ start()
 		cd /var/lib/tomcat5/shared/lib
 	fi
 
-	# daemon --user $TOMCAT_USER $TOMCAT_SCRIPT start 
+	# daemon --user $TOMCAT_USER $TOMCAT_SCRIPT start
 	if [ ${OS} = "SunOS" ] ; then
 		su  $TOMCAT_USER -c "$TOMCAT_SCRIPT start" > /dev/null
-        else
+	else
 		runuser -s /bin/bash $TOMCAT_USER -c "$TOMCAT_SCRIPT start" > /dev/null
 	fi
 
-	RETVAL=$?
-	[ $RETVAL = 0 ] && touch ${lockfile}
+	rv=$?
+	if [ ${rv} = 0 ] ; then
+		touch ${PKI_LOCKFILE}
+		chown $TOMCAT_USER:$TOMCAT_GROUP $PKI_LOCKFILE
+		chmod 00600 $PKI_LOCKFILE
+	fi
 
-	if [ $RETVAL = 0 ] ; then
+	if [ ${rv} = 0 ] ; then
 		count=0;
 
 		let swait=$STARTUP_WAIT
@@ -1090,12 +1383,13 @@ start()
 			PKI_SECURE_PORT="<Port Undefined>"
 		fi
 
+		# ignore "status" return codes
 		echo
-		status
+		display_instance_status
 	else
 		if [ -f /etc/init.d/functions ]; then
 			if [ "$CONSOLETYPE" = "serial" ]; then
-				echo -n "         "
+				$0	echo -n "         "
 			fi
 			echo_failure
 			echo
@@ -1105,27 +1399,29 @@ start()
 	fi
 
 	sleep 5
-	return $RETVAL
+	return ${rv}
 }
 
-stop()
+stop_instance()
 {
+	rv=0
+
 	echo -n "Stopping $TOMCAT_PROG: "
 
-	if [ -f ${lockfile} ] ; then
+	if [ -f ${PKI_LOCKFILE} ] ; then
 		CATALINA_PID=${pidfile}
 		export CATALINA_PID
 
 		# daemon --user $TOMCAT_USER $TOMCAT_SCRIPT stop
 		if [ ${OS} = "SunOS" ] ; then
 			su  $TOMCAT_USER -c "$TOMCAT_SCRIPT stop" > /dev/null
-        	else
+		else
 			runuser -s /bin/bash $TOMCAT_USER -c "$TOMCAT_SCRIPT stop" > /dev/null
 		fi
 
-		RETVAL=$?
+		rv=$?
 
-		if [ $RETVAL = 0 ]; then
+		if [ ${rv} = 0 ]; then
 			count=0;
 
 			if [ -f ${pidfile} ]; then
@@ -1145,7 +1441,7 @@ stop()
 				fi
 			fi
 
-			rm -f ${lockfile}
+			rm -f ${PKI_LOCKFILE}
 			rm -f ${pidfile}
 
 			if [ -f /etc/init.d/functions ]; then
@@ -1167,75 +1463,346 @@ stop()
 			else
 				echo "         [  FAILED  ]"
 			fi
+			rv=${default_error}
 		fi
 	else
 		echo
 		echo "process already stopped"
+		rv=0
 	fi
+
+	return ${rv}
 }
 
-status()
+start()
 {
-	if [ -f ${pidfile} ] ; then
-		pid=`cat ${pidfile}`
-		if [ "${pid}" == "" ] ; then
-			echo "[PKI_INSTANCE_ID] pid file exists but is empty"
-		elif kill -0 ${pid} > /dev/null 2>&1 ; then
-			echo "[PKI_INSTANCE_ID] (pid ${pid}) is running ..."
+	# From "http://fedoraproject.org/wiki/FCNewInit/Initscripts":
+	#
+	#     * 0 action was successful
+	#     * 1 generic or unspecified error (current practice)
+	#     * 2 invalid or excess argument(s)
+	#     * 3 unimplemented feature (for example, "reload")
+	#     * 4 user had insufficient privilege
+	#     * 5 program is not installed
+	#     * 6 program is not configured
+	#     * 7 program is not running
+	#     * 8-99 reserved for future LSB use
+	#     * 100-149 reserved for distribution use
+	#     * 150-199 reserved for application use
+	#     * 200-254 reserved
+	#
+
+	error_rv=0
+	rv=0
+
+	if [ -n "${PKI_REGISTRY_ENTRIES}" ]; then
+		config_errors=0
+		errors=0
+
+		if [ ${TOTAL_PKI_REGISTRY_ENTRIES} -gt 1 ] ; then
+			echo "BEGIN STARTING '${PKI_TYPE}' INSTANCE(S):"
+		fi
+
+		# Start every PKI instance of this type that isn't already running
+		for PKI_REGISTRY_ENTRY in ${PKI_REGISTRY_ENTRIES}; do
+			# Source values associated with this particular PKI instance
+			[ -f ${PKI_REGISTRY_ENTRY} ] &&
+			. ${PKI_REGISTRY_ENTRY}
+
+			pidfile=${PKI_PIDDIR}/${PKI_PIDFILE}
+
+			[ ${TOTAL_PKI_REGISTRY_ENTRIES} -gt 1 ] && echo
+
+			start_instance
+
+			rv=$?
+			if [ ${rv} = 6 ] ; then
+				# Since at least ONE configuration error exists, then there
+				# is at least ONE unconfigured instance from the PKI point
+				# of view.
+				#
+				# However, it must still be considered that the
+				# instance is "running" from the point of view of other
+				# OS programs such as 'chkconfig'.
+				#
+				# Therefore, ignore non-zero return codes resulting
+				# from configuration errors.
+				#
+
+				config_errors=`expr $config_errors + 1`
+				rv=0
+			elif [ ${rv} != 0 ] ; then
+				errors=`expr $errors + 1`
+				error_rv=${rv}
+			fi
+		done
+
+		if [ ${TOTAL_PKI_REGISTRY_ENTRIES} -gt ${errors} ] ; then
+			touch ${lockfile}
+			chmod 00600 ${lockfile}
+		fi
+
+		# ONLY print a "WARNING" message if multiple
+		# instances are being examined
+		if [ ${TOTAL_PKI_REGISTRY_ENTRIES} -gt 1 ] ; then
+			# NOTE:  "bad" return code(s) OVERRIDE configuration errors!
+			if [ ${errors} -eq 1 ]; then
+				# Since only ONE error exists, return that "bad" error code.
+				rv=${error_rv}
+			elif [ ${errors} -gt 1 ]; then
+				# Since MORE than ONE error exists, return an OVERALL status
+				# of "1 generic or unspecified error (current practice)"
+				rv=1
+			fi
+
+			if [ ${errors} -ge 1 ]; then
+				echo
+				echo -n "WARNING:  "
+				echo -n "${errors} of ${TOTAL_PKI_REGISTRY_ENTRIES} "
+				echo -n "'${PKI_TYPE}' instances failed to start!"
+				echo
+			fi
+
+			if [ ${TOTAL_UNCONFIGURED_PKI_ENTRIES} -ge 1 ]; then
+				echo
+				echo -n "WARNING:  "
+				echo -n "${TOTAL_UNCONFIGURED_PKI_ENTRIES} "
+				echo -n "of ${TOTAL_PKI_REGISTRY_ENTRIES} "
+				echo -n "'${PKI_TYPE}' instances MUST be configured!"
+				echo
+			fi
+
 			echo
-			check_pki_configuration_status
-			if [ $? -eq 0 ] ; then
-				get_pki_status_definitions
-				if [ $? -ne 0 ] ; then
-					echo
-					echo "[PKI_INSTANCE_ID] Status Definitions not found"
-				fi
-				get_pki_configuration_definitions
-				if [ $? -ne 0 ] ; then
-					echo
-					echo "[PKI_INSTANCE_ID] Configuration Definitions not found"
-				fi
+			echo "FINISHED STARTING '${PKI_TYPE}' INSTANCE(S)."
+		fi
+	else
+		echo
+		echo "ERROR:  No '${PKI_TYPE}' instances installed!"
+		rv=5
+	fi
+
+	return ${rv}
+}
+
+stop()
+{
+	# From "http://fedoraproject.org/wiki/FCNewInit/Initscripts":
+	#
+	#     * 0 action was successful
+	#     * 1 generic or unspecified error (current practice)
+	#     * 2 invalid or excess argument(s)
+	#     * 3 unimplemented feature (for example, "reload")
+	#     * 4 user had insufficient privilege
+	#     * 5 program is not installed
+	#     * 6 program is not configured
+	#     * 7 program is not running
+	#     * 8-99 reserved for future LSB use
+	#     * 100-149 reserved for distribution use
+	#     * 150-199 reserved for application use
+	#     * 200-254 reserved
+	#
+
+	error_rv=0
+	rv=0
+
+	if [ -n "${PKI_REGISTRY_ENTRIES}" ]; then
+		errors=0
+
+		if [ ${TOTAL_PKI_REGISTRY_ENTRIES} -gt 1 ] ; then
+			echo "BEGIN SHUTTING DOWN '${PKI_TYPE}' INSTANCE(S):"
+		fi
+
+		# Shutdown every PKI instance of this type that is running
+		for PKI_REGISTRY_ENTRY in ${PKI_REGISTRY_ENTRIES}; do
+			# Source values associated with this particular PKI instance
+			[ -f ${PKI_REGISTRY_ENTRY} ] &&
+			. ${PKI_REGISTRY_ENTRY}
+
+			pidfile=${PKI_PIDDIR}/${PKI_PIDFILE}
+
+			[ ${TOTAL_PKI_REGISTRY_ENTRIES} -gt 1 ] && echo
+
+			stop_instance
+
+			rv=$?
+			if [ ${rv} != 0 ] ; then
+				errors=`expr $errors + 1`
+				error_rv=${rv}
+			fi
+		done
+
+		if [ ${errors} -eq 0 ] ; then
+			rm -f ${lockfile}
+		fi
+
+		# ONLY print a "WARNING" message if multiple
+		# instances are being examined
+		if [ ${TOTAL_PKI_REGISTRY_ENTRIES} -gt 1 ] ; then
+			if [ ${errors} -eq 1 ]; then
+				# Since only ONE error exists, return that "bad" error code.
+				rv=${error_rv}
+			elif [ ${errors} -gt 1 ]; then
+				# Since MORE than ONE error exists, return an OVERALL status
+				# of "1 generic or unspecified error (current practice)"
+				rv=1
+			fi
+
+			if [ ${errors} -ge 1 ]; then
+				echo
+				echo -n "WARNING:  "
+				echo -n "${errors} of ${TOTAL_PKI_REGISTRY_ENTRIES} "
+				echo -n "'${PKI_TYPE}' instances were "
+				echo -n "unsuccessfully stopped!"
+				echo
 			fi
+
 			echo
-		else
-			echo "[PKI_INSTANCE_ID] is dead but pid file exists"
+			echo "FINISHED SHUTTING DOWN '${PKI_TYPE}' INSTANCE(S)."
 		fi
 	else
-		echo "[PKI_INSTANCE_ID] is stopped"
+		echo
+		echo "ERROR:  No '${PKI_TYPE}' instances installed!"
+		rv=5
 	fi
+
+	return ${rv}
 }
 
-# See how we were called.
-case "$1" in
-	start)
-		start
-		;;
-	stop)
-		stop
-		;;
-	restart)
-		stop
-		sleep 2	
-		start
-		;;
-	condrestart)
-		if [ -f ${pidfile} ] ; then
-			stop
-			sleep 2	
-			start
-		else
-			echo -n "Unable to restart process since "
-			echo -n "'${pidfile}' does not exist!"
+restart()
+{
+	# From "http://fedoraproject.org/wiki/FCNewInit/Initscripts":
+	#
+	#     * 0 action was successful
+	#     * 1 generic or unspecified error (current practice)
+	#     * 2 invalid or excess argument(s)
+	#     * 3 unimplemented feature (for example, "reload")
+	#     * 4 user had insufficient privilege
+	#     * 5 program is not installed
+	#     * 6 program is not configured
+	#     * 7 program is not running
+	#     * 8-99 reserved for future LSB use
+	#     * 100-149 reserved for distribution use
+	#     * 150-199 reserved for application use
+	#     * 200-254 reserved
+	#
+
+	stop
+	sleep 2
+	echo
+	echo "============================================================"
+	echo
+	start
+
+	return $?
+}
+
+status()
+{
+	# From "http://fedoraproject.org/wiki/FCNewInit/Initscripts":
+	#
+	#     * 0 program is running or service is OK
+	#     * 1 program is dead and /var/run pid file exists
+	#     * 2 program is dead and /var/lock lock file exists
+	#     * 3 program is not running
+	#     * 4 program or service status is unknown
+	#     * 5-99 reserved for future LSB use
+	#     * 100-149 reserved for distribution use
+	#     * 150-199 reserved for application use
+	#     * 200-254 reserved
+	#
+
+	error_rv=0
+	rv=0
+
+	if [ -n "${PKI_REGISTRY_ENTRIES}" ]; then
+		errors=0
+
+		if [ ${TOTAL_PKI_REGISTRY_ENTRIES} -gt 1 ] ; then
+			echo "REPORT STATUS OF '${PKI_TYPE}' INSTANCE(S):"
+		fi
+
+		# Obtain status of every PKI instance of this type
+		for PKI_REGISTRY_ENTRY in ${PKI_REGISTRY_ENTRIES}; do
+			# Source values associated with this particular PKI instance
+			[ -f ${PKI_REGISTRY_ENTRY} ] &&
+			. ${PKI_REGISTRY_ENTRY}
+
+			pidfile=${PKI_PIDDIR}/${PKI_PIDFILE}
+
+			[ ${TOTAL_PKI_REGISTRY_ENTRIES} -gt 1 ] && echo
+
+			display_instance_status
+
+			rv=$?
+			if [ ${rv} -ne 0 ] ; then
+				errors=`expr $errors + 1`
+				error_rv=${rv}
+			fi
+		done
+
+		# ONLY print a "WARNING" message if multiple
+		# instances are being examined
+		if [ ${TOTAL_PKI_REGISTRY_ENTRIES} -gt 1 ] ; then
+			if [ ${errors} -eq 1 ]; then
+				# Since only ONE error exists, return that "bad" error code.
+				rv=${error_rv}
+			elif [ ${errors} -gt 1 ]; then
+				# Since MORE than ONE error exists, return an OVERALL status
+				# of "4 - program or service status is unknown"
+				rv=4
+			fi
+
+			if [ ${errors} -ge 1 ]; then
+				echo
+				echo -n "WARNING:  "
+				echo -n "${errors} of ${TOTAL_PKI_REGISTRY_ENTRIES} "
+				echo -n "'${PKI_TYPE}' instances reported status failures!"
+				echo
+			fi
+
+			if [ ${TOTAL_UNCONFIGURED_PKI_ENTRIES} -ge 1 ]; then
+				echo
+				echo -n "WARNING:  "
+				echo -n "${TOTAL_UNCONFIGURED_PKI_ENTRIES} "
+				echo -n "of ${TOTAL_PKI_REGISTRY_ENTRIES} "
+				echo -n "'${PKI_TYPE}' instances MUST be configured!"
+				echo
+			fi
+
 			echo
+			echo "FINISHED REPORTING STATUS OF '${PKI_TYPE}' INSTANCE(S)."
 		fi
+	else
+		echo
+		echo "ERROR:  No '${PKI_TYPE}' instances installed!"
+		rv=4
+	fi
+
+	return ${rv}
+}
+
+# See how we were called.
+case "${command}" in
+	start|stop|restart|status)
+		${command}
+		exit $?
 		;;
-	status)
-		status
+	condrestart|force-restart|try-restart)
+		[ ! -f ${lockfile} ] || restart
+		exit $?
+		;;
+	reload)
+		echo "The 'reload' action is an unimplemented feature."
+		exit ${default_error}
 		;;
 	*)
-		echo "Usage: $TOMCAT_PROG {start|stop|restart|condrestart|status}"
-		exit 1
+		# * 3 unimplemented feature (for example, "reload")
+		#     [invalid command - should never be reached]
+		echo
+		usage
+		echo "where valid instance names include:"
+		list_instances
+		exit 3
+		;;
 esac
 
-exit $RETVAL
-