[3939] Addressed review comments

doc/devel/qa.dox
    Added description of KEA_PIDFILE_DIR

doc/guide/keactrl.xml
    Added discusion of PID files to section 6

src/bin/keactrl/keactrl.in
    start_server()
        Revised wording of already-running log message

doc/devel/qa.dox

@@ -48,14 +48,6 @@ make check
 
 The following environment variable can affect unit-tests:
 
-- KEA_SOCKET_TEST_DIR - if set, it specifies the directory where Unix
-  sockets are created. There's OS limitation on how long a Unix socket
-  path can be. It is typcially slightly over 100 characters. If you
-  happen to build and run unit-tests in deeply nested directories, this
-  may become a problem. KEA_SOCKET_TEST_DIR can be specified to instruct
-  unit-test to use a different directory. Must not end with slash (e.g.
-  /tmp).
-
 - KEA_LOCKFILE_DIR - Specifies a directory where the logging system should
   create its lock file. If not specified, it is prefix/var/run/kea, where prefix
   defaults to /usr/local. This variable must not end with a slash. There is one
@@ -68,4 +60,17 @@ The following environment variable can affect unit-tests:
   stdout, stderr and syslog. Any other value is interpreted as a filename.
   Also see Kea User's Guide, section 15.3.
 
+- KEA_PIDFILE_DIR - Specifies the directory which should be used for PID files
+  as used by dhcp::Daemon or its derivatives. If not specified, the default is
+  prefix/var/run/kea, where prefix defaults to /usr/local. This variable must
+  not end with a slash.
+
+- KEA_SOCKET_TEST_DIR - if set, it specifies the directory where Unix
+  sockets are created. There's OS limitation on how long a Unix socket
+  path can be. It is typcially slightly over 100 characters. If you
+  happen to build and run unit-tests in deeply nested directories, this
+  may become a problem. KEA_SOCKET_TEST_DIR can be specified to instruct
+  unit-test to use a different directory. Must not end with slash (e.g.
+  /tmp).
+
  */

doc/guide/keactrl.xml

@@ -157,21 +157,48 @@ kea_verbose=no
       the servers looks similar to the following:
 <screen>
 <userinput>$ keactrl start</userinput>
-INFO/keactrl: Starting kea-dhcp4 -c /usr/local/etc/kea/kea.conf
-INFO/keactrl: Starting kea-dhcp6 -c /usr/local/etc/kea/kea.conf
-INFO/keactrl: Starting kea-dhcp-ddns -c /usr/local/etc/kea/kea.conf
+INFO/keactrl: Starting kea-dhcp4 -c /usr/local/etc/kea/kea.conf -d
+INFO/keactrl: Starting kea-dhcp6 -c /usr/local/etc/kea/kea.conf -d
+INFO/keactrl: Starting kea-dhcp-ddns -c /usr/local/etc/kea/kea.conf -d
 </screen>
       </para>
 
+      <para>Kea's servers create PID files upon startup. These files are used
+      by keactrl to deteremine whether or not a given server is running.  If
+      one or more servers are running when the start command is issued, the
+      output will look similiar to the following:
+<screen>
+<userinput>$ keactrl start</userinput>
+INFO/keactrl: kea-dhcp4 appears to be running, see: PID 10918, PID file: /usr/local/var/kea/kea.kea-dhcp4.pid.
+INFO/keactrl: kea-dhcp6 appears to be running, see: PID 10924, PID file: /usr/local/var/kea/kea.kea-dhcp6.pid.
+INFO/keactrl: kea-dhcp-ddns appears to be running, see: PID 10930, PID file: /usr/local/var/kea/kea.kea-dhcp-ddns.pid.
+</screen>
+      During normal shutdowns these PID files are deleted. They may, however,
+      be left over as remnants following a system crash.  It is possible,
+      though highly unlikely, that upon system restart the PIDs they contain
+      actually refer to processes unrelated to Kea.  This condition will cause
+      keactrl to decide that the servers are running, when in fact they are
+      not.  In such a case the PID files as listed in the keactrl output
+      must be manually deleted.
+      </para>
+
       <para>The following command stops all servers:
 <screen>
 <userinput>$ keactrl stop</userinput>
-INFO/keactrl: Skip sending signal 15 to process kea-dhcp6: process is not running
+INFO/keactrl: Stopping kea-dhcp4...
+INFO/keactrl: Stopping kea-dhcp6...
+INFO/keactrl: Stopping kea-dhcp-ddns...
 </screen>
       Note that the <command>stop</command> will attempt to stop all servers
       regardless of whether they are "enabled" in the <filename>keactrl.conf</filename>.
-      If any of the servers is not running, an informational message
-      is displayed as in the <command>stop</command> command output above.
+      If any of the servers are not running, an informational message
+      is displayed as in the <command>stop</command> command output below.
+<screen>
+<userinput>$ keactrl stop</userinput>
+INFO/keactrl: kea-dhcp4 isn't running.
+INFO/keactrl: kea-dhcp6 isn't running.
+INFO/keactrl: kea-dhcp-ddns isn't running.
+</screen>
       </para>
 
       <para>
@@ -184,6 +211,17 @@ INFO/keactrl: Skip sending signal 15 to process kea-dhcp6: process is not runnin
         valid, uses the new configuration. A reload is executed as follows:
 <screen>
 <userinput>$ keactrl reload</userinput>
+INFO/keactrl: Reloading kea-dhcp4...
+INFO/keactrl: Reloading kea-dhcp6...
+INFO/keactrl: Reloading kea-dhcp-ddns...
+</screen>
+      If any of the servers are not running, an informational message
+      is displayed as in the <command>reload</command> command output below.
+<screen>
+<userinput>$ keactrl stop</userinput>
+INFO/keactrl: kea-dhcp4 isn't running.
+INFO/keactrl: kea-dhcp6 isn't running.
+INFO/keactrl: kea-dhcp-ddns isn't running.
 </screen>
       </para>
 

src/bin/keactrl/keactrl.in

@@ -148,7 +148,7 @@ start_server() {
     check_running ${binary_name}
     # If process is running, don't start another one. Just log a message.
     if [ ${_running} -ne 0 ]; then
-        log_info "${binary_name} is already running as: \
+        log_info "${binary_name} appears to be running, see: \
 PID ${_pid}, PID file: ${_pid_file}."
     else
         log_info "Starting ${binary_name} ${args}"