[jarrpa/prequel.git] / src / daemon / PrequelD.c

/* ========================================================================== **
 *                                 PrequelD.c
 *
 * Copyright:
 *  Copyright (C) 2012 by Christopher R. Hertel
 *
 * Email: crh@ubiqx.mn.org
 *
 * $Id: PrequelD.c; 2014-09-22 17:14:11 -0500; Christopher R. Hertel$
 *
 * -------------------------------------------------------------------------- **
 *
 * Description:
 *  PeerDist protocol server daemon.
 *
 * -------------------------------------------------------------------------- **
 *
 * License:
 *
 *  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, either version 3 of the License, or
 *  (at your option) any later version.
 *
 *  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, see <http://www.gnu.org/licenses/>.
 *
 * -------------------------------------------------------------------------- **
 *               This code was developed in participation with
 *                the Protocol Freedom Information Foundation.
 *         See http://www.protocolfreedom.org/ for more information.
 * -------------------------------------------------------------------------- **
 *
 * Notes:
 *
 *  The Prequel Project website is http://www.ubiqx.org/proj/Prequel/
 *
 *  Terminology:
 *
 *    PeerDist  - The protocol and/or encoding format used by Microsoft's
 *                BranchCacheTM distributed caching system.
 *
 *    Prequel   - The name of an Open Source project aimed at implementing
 *                PeerDist for use with Linux, *BSD, and other Unix-like
 *                OSes.
 *
 *  References:
 *    [BCOVIEW]:    MS W2K8R2 BranchCache Overview
 *                  http://technet.microsoft.com/en-us/library/dd637832.aspx
 *
 *    [MS-CCRSOD]:  Content Caching and Retrieval System Overview
 *                  http://msdn.microsoft.com/en-us/library/ff632262.aspx
 *
 *    [MS-PCCRC]:   Peer Content Caching and Retrieval: Content Identification
 *                  http://msdn.microsoft.com/en-us/library/dd303704.aspx
 *
 *  To Compile:
 *    cc -I.. -D_FILE_OFFSET_BITS=64 -o PrequelD PrequelD.c \
 *      PD_peerdist1.c PD_read_config.c PD_sha2_oSSL.c PD_utils.c Gstr.c \
 *      ../ubi_sLinkList.c -lcrypto -lpthread
 *
 *  ToDo:
 *    + Add support for Unicode pathnames.
 *
 *    + The background thread should traverse source directories and generate
 *      hash caches for any file that meets criteria and does not have an
 *      up-to-date hash cache file.
 *
 *    + The background thread should traverse cache directories and delete
 *      any cache files that are out-of-date or which map back to a source
 *      file that no longer exists (or has been truncated to a size that is
 *      smaller than the minimum).
 *
 *    + Add PeerDist v2 support.
 *
 *    + Add signal handling:
 *      - HUP:  Lock the mutex and re-read the config file.  Update directory
 *              traversal state.
 *      - TERM: Exit cleanly.
 *
 *    + Long-term:  Collect interesting statistics and log them on SIGHUP,
 *                  SIGTERM, or SIGUSR1.
 *
 *    + Add a -s <socket> option to override the socket path in the config
 *      file.
 *
 *    + More consideration should be given to the handling of the "Server
 *      Secret", which is used to sign the "Segment Hash of Data" to create
 *      the "Segment Secret".  At present, we just read the "Server Secret"
 *      from a file.  See the <ReadKeys()> function, below.
 *
 *      Two ideas on this:
 *      - Each sourcedir *may* have its own keyfile.  One of the options for
 *        the keyfile (possibly the default?) would be to generate a Server
 *        Secret on the fly.  In that case, the Server Secret would be
 *        different every time PrequelD is run (which wouldn't be all bad,
 *        assuming PrequelD is really stable).  It would mean that caches
 *        would be invalidated every time PrequelD restarts, and that the
 *        key could not be shared by multiple servers.  Providing this option
 *        would further require that we allow for an empty keyfile value in
 *        the config file (which might change the syntax).
 *      - Server Secrets could be stored AES encrypted, to match the format
 *        of Server Secrets extracted from Windows servers.  The problem
 *        with this option is that PrequelD would still need to have access
 *        to the passphrase used to decrypt the AES-encrypted secrets, so
 *        we would still have an exposed password.
 *
 * FIX:
 *
 *  + The 'exclude' configuration command doesn't yet work.
 *
 *  + Need to detect whether we are running already or not.  We can run
 *    multiple daemons at once, as long as their src directories don't
 *    overlap and they are using different sockets.  Add a PID file path
 *    to the configuration, default to /var/run/prequel.pid
 *
 *  + We implement a QUERY command over the Unix domain socket.  Its purpose
 *    is to return the pathname of a cache file given the pathname of the
 *    source file.  Cool.
 *
 *    Problem is, the current implementation of the QUERY does not include
 *    the PeerDist major/minor numbers, so we can only return the least
 *    common denominator (1.0).  The QUERY command needs to be changed to
 *    pass version numbers, or to *optionally* pass version numbers when
 *    the least common denominator is not being requested.
 *
 * ========================================================================== **
 */

#include <time.h>           /* For nanosleep(2).                        */
#include <stdlib.h>         /* Standard Library.                        */
#include <stdbool.h>        /* Standard boolean type.                   */
#include <stdint.h>         /* Standard extended integer types.         */
#include <unistd.h>         /* For getopt(3), close(2), unlink(2), etc. */
#include <string.h>         /* For strerror(3), strchr(3).              */
#include <stdarg.h>         /* Standard variable argument lists.        */
#include <ctype.h>          /* For isspace(3) and iscntrl(3).           */
#include <sys/types.h>      /* For the pid_t and DIR* types.            */
#include <dirent.h>         /* For reading directory entries.           */
#include <pthread.h>        /* For POSIX Threads.                       */
#include <poll.h>           /* For ppoll(2) and struct pollfd.          */
#include <sys/socket.h>     /* Socket(7) interface header.              */
#include <sys/un.h>         /* Unix(7) domain sockets.                  */
#include <sys/time.h>       /* The timeval struct and gettimeofday(2).  */

#include "PD_peerdist1.h"   /* PeerDist v1 protocol support.  */
#include "PD_read_config.h" /* Read the configuration file.   */
#include "PD_utils.h"       /* General PrequelD utilities.    */
#include "ubi_sLinkList.h"  /* Linked List module.            */
#include "Gstr.h"           /* Growable string buffers.       */


/* -------------------------------------------------------------------------- **
 * Defined Constants:
 *
 *  DEFAULT_CONFIG_FILE - Default pathname of the configuration file to read
 *                        on startup.  This value can be overridden at
 *                        compile time.
 *
 *  SYSLOG_NAME         - The name used to identify this program in Syslog
 *                        logs.
 *
 *  RECV_TIMEOUT        - Number of seconds and microseconds to listen on
 *                        an input socket while receiving data.  Formated
 *                        as an initialization pair: { <sec>, <usec> }.
 *                        1usec = 1/1000000sec (10^-6, or 1/1000msec)
 *
 *  POLL_TIMEOUT        - Number of milliseconds to wait when poll(2)ing
 *                        an input socket.  1msec = 1/1000sec == 1000usec.
 *
 *  bSIZE               - A buffer size used to allocate the read buffer
 *                        included in the <RecvBufr> structure.
 */

#ifndef DEFAULT_CONFIG_FILE
#define DEFAULT_CONFIG_FILE "/etc/prequeld/pd.conf"
#endif

#define SYSLOG_NAME "prequeld"

#define RECV_TIMEOUT { 2, 0 }     /*  2 seconds.  */
#define POLL_TIMEOUT 30000        /* 30 seconds.  */

#define bSIZE 1024


/* -------------------------------------------------------------------------- **
 * Macros:
 *
 *  forEach( V, L ) - A macro for traversing a linked list of <pd_ConfigRec>
 *                    records. This is just a simplified way of expressing a
 *                    linked-list traversal using a "for" loop.  Think of it
 *                    as "for each <V> in <L>".
 *                    V - The variable that will point to each node in the
 *                        list.  <V> must be substituted with a pointer to a
 *                        <pd_ConfigRec> structure.
 *                    L - The list to be traversed.
 *
 */

#define forEach( V, L ) \
        for( (V) = (pd_ConfigRec *)ubi_slFirst( (L) ); \
             NULL != (V); \
             (V) = (pd_ConfigRec *)ubi_slNext( (V) ) )


/* -------------------------------------------------------------------------- **
 * Typedefs:
 *
 *  RangeVal  - Used to read and interpret the value of the Range: option,
 *              which may be sent by the client.  If <given> is false, the
 *              we know that the client did not provide a value.  If <given>
 *              is true, then the client did provide a value and that value
 *              is stored in the <val> field.
 *
 *  WorkItem  - A queue entry and a string pointer pointing to the pathname
 *              of a source file that is in need of hashing.
 *
 */

typedef struct
  {
  bool      given;        /* Was a value given. */
  uint64_t  val;          /* The given value.   */
  } RangeVal;

typedef struct
  {
  ubi_slNode  node;       /* Linked list node.  */
  char       *srcPath;    /* Source file path.  */
  } WorkItem;


/* -------------------------------------------------------------------------- **
 * Global Constants:
 *
 *  Copyright   - Copyright information.
 *  License     - License information string.
 *  Revision    - Revision string, generated by revision control.
 *  Id          - Longer revision string.
 *
 *  HelpMsg     - The program help message.
 *  VerboseMsg  - Verbose help message.
 */

static const char *Copyright =
                    "Copyright (c) 2012 by Christopher R. Hertel";
static const char *License =
                    "License: GNU General Public License version 3 (GPLv3)\n"
                    "         http://www.gnu.org/licenses/gpl-3.0.html";
static const char *Revision =
                    "$Revision$";
static const char *Id =
                    "$Id: PrequelD.c; 2014-09-22 17:14:11 -0500; Christopher R. Hertel$";

static const char *HelpMsg[] =
  {
  "  Available Options:",
  "  -c <file> Specify the configuration file to use.",
  "  -f        Run in the foreground, not as a daemon.",
  "  -h        Produce this useful help message, then exit (-hv == more help).",
  "  -l <file> Send log messages to <file>.",
  "  -q        Be quiet.  Set the verbosity level to zero.",
  "  -t        Test-parse the configuration file, then exit.",
  "  -v        Be verbose.  Add more -v's for more verbosity.",
  "  -V        Output version information.",
  NULL
  };

static const char *VerboseMsg[] =
  {
  "The Options Available to You:",
  "  -c <file> Specify the configuration file to use.",
  "            Default: \"" DEFAULT_CONFIG_FILE "\".",
  "  -f        Run in the foreground, not as a daemon.",
  "            Default: Run as a daemon.",
  "  -h        Produce a useful help message, then exit.",
  "            Default: Don't produce a useful help message.  Run normally.",
  "  -l <file> Send log messages to <file>.",
  "            Default:  When running in the foreground, log messages are sent",
  "                      to <stderr>.  When running in the background, log",
  "                      messages are sent to syslog.  All initial messages",
  "                      (as the program starts up) are sent to <stdout> or",
  "                      <stderr>.",
  "  -q        Be quiet.  Set the verbosity level to zero (0) and produce only",
  "            the minimum set of diagnostic messages.  Default verbosity: 1.",
  "  -t        Parse the configuration file and report any errors to <stderr>.",
  "            The program will exit once parsing is complete.",
  "            Use -tv to dump the contents of a successfully parsed",
  "            configuration file.",
  "  -v        Be verbose.  Add more -v's for more verbosity.",
  "            Use of -q or -v overrides the config file verbosity settings.",
  "            Default verbosity: 1.",
  "  -V        Output version information.",
  "            Increased verbosity provides copyright and license information.",
  NULL
  };


/* -------------------------------------------------------------------------- **
 * Global Variables:
 *
 *  Verbosity     - Controls the level of diagnostic messages that are
 *                  produced.  The minimum value is 0.  Anything above 10
 *                  is ridiculous.  Default: 1.  A maximum value of 255
 *                  is enforced both in the PD_read_config module and in
 *                  <ReadOpts()> function, below.
 *
 *  Daemonize     - By default PrequelD will run as a daemon, but this
 *                  default behavior can be overridden with a command-line
 *                  option.  There is no configuration file option for this,
 *                  so we use a global variable to represent this attribute.
 *
 *  Cfg           - Pointer used to retrieve the configuration information
 *                  from the configuration file.
 *
 *  WorkerThread  - The thread ID of the background thread that is doing all
 *                  of the real work (that is, generating and maintaining
 *                  hash files).  The "foreground" thread communicates with
 *                  clients.
 *
 *  GlobalMutex   - A global mutex attribute.  The worker thread needs brief
 *                  access to the <Cfg> list and other state attribues.
 *                  This allows the foreground and background to share.
 *
 *  Shutdown      - Used to let the worker process know when it is time to
 *                  shut down and return.
 *
 *  WorkQueue     - A queue of source file names that are waiting to be
 *                  hashed.  The queue is filled when a request is made
 *                  and no hash cache file is found.  It is emptied by
 *                  the worker thread.  Queued entries have priority over
 *                  source files found during directory traversal.
 */

static unsigned int     Verbosity     = 1;
static bool             Daemonize     = true;
static pd_Config       *Cfg           = NULL;
static pthread_t        WorkerThread;
static pthread_mutex_t  GlobalMutex   = PTHREAD_MUTEX_INITIALIZER;
static bool             Shutdown      = false;
static ubi_slList       WorkQueue[1];


/* -------------------------------------------------------------------------- **
 * Static Functions:
 */

static void Usage( const char *progname, int status )
  /* ------------------------------------------------------------------------ **
   * Provide usage information, then exit.
   *
   *  Input:  progname  - Pointer to a string containing the program name.
   *          status    - Exit status to return.
   *
   *  Output: <none>
   *
   *  Notes:  Output is sent to <stdout> so that it can be piped through
   *          'more' or 'less' or something else.
   *
   * ------------------------------------------------------------------------ **
   */
  {
  int          i;
  const char **msg = (Verbosity > 1) ? VerboseMsg : HelpMsg;

  Say( "Usage: %s [options]\n", progname );
  for( i = 0; NULL != msg[i]; i++ )
    Say( "%s\n", msg[i] );

  exit( status );
  } /* Usage */


static void LockLog( char *fmt, ... )
  /* ------------------------------------------------------------------------ **
   * Lock/unlock the global mutex to safely write a log message.
   *
   *  Input:  fmt - Format string, as used in printf(), etc.
   *          ... - Variable parameter list.
   *
   *  Output: <none>
   *
   *  Notes:  A simple wrapper around <vLog()> in PD_utils.
   *
   *  See:    <PD_utils.vLog()>
   *
   * ------------------------------------------------------------------------ **
   */
  {
  va_list ap;

  if( 0 == pthread_mutex_lock( &GlobalMutex ) )
    {
    va_start( ap, fmt );
    vLog( fmt, ap );
    va_end( ap );
    (void)pthread_mutex_unlock( &GlobalMutex );
    }
  } /* LockLog */


static void deltaTval( struct timeval *tval )
  /* ------------------------------------------------------------------------ **
   * Calculate the difference between then and now.
   *
   *  Input:  tval  - A pointer to a timeval structure containing an initial
   *                  time (start time).  The contents of <tval> will be
   *                  updated to indicate the difference in time between
   *                  the initial time and the current time.
   *
   *  Output: <none>
   *
   *  Notes:  If the contents of <tval> are all zero or <tval> is ahead of
   *          the current time, the input is considered to be invalid and
   *          <tval> will be returned with all zeros to indicate the error.
   *
   *  See:    gettimeofday(2)
   *
   * ------------------------------------------------------------------------ **
   */
  {
  struct timeval now_tv[1];
  struct timeval result = { 0, 0 };

  /* Is the input valid?  */
  if( (0 != tval->tv_sec) || (0 != tval->tv_usec) )
    {
    /* Attempt to get the current time. */
    if( 0 == gettimeofday( now_tv, NULL ) )
      {
      /* <now_tv> must be greater than <tval>.  */
      if( (now_tv->tv_sec > tval->tv_sec)
       || ((now_tv->tv_sec == tval->tv_sec)
        && (now_tv->tv_usec > tval->tv_usec)) )
        {
        result.tv_sec = now_tv->tv_sec - tval->tv_sec;
        if( now_tv->tv_usec > tval->tv_usec )
          result.tv_usec = now_tv->tv_usec - tval->tv_usec;
        else
          {
          result.tv_sec--;
          result.tv_usec = (1000000 - tval->tv_usec) + now_tv->tv_usec;
          }
        }
      }
    }

  *tval = result;
  return;
  } /* deltaTval */


FIX: HERE!


static void *Responder( void *sockptr )
  /* ------------------------------------------------------------------------ **
   * Respond to requests from a client.
   *
   *  Input:  sockptr - A pointer to an integer, which is the open
   *                    communications socket.
   *
   *  Output: <none>
   *
   *  Notes:  This is, essentially, the mainline of a thread that is
   *          spawned to deal with a single client connection.  It
   *          handles requests from the client until the client closes
   *          the connection.
   *
   *  See:    The <Readme.txt> file includes the definition of the simple
   *          client/server protocol.
   *
   * ------------------------------------------------------------------------ **
   */
  {
  int             client_sock = *((int *)thingy);     /* Copy the socked id.  */
  bool            run   = true;                       /* Ready to run.        */
  struct timeval  tv[1] = { RECV_TIMEOUT };
  RecvBufr        Rb[1];
  struct pollfd   pfd[1];
  int             result;

  /* Free unused memory and detach the thread so we can just exit when done.  */
  free( thingy );
  (void)pthread_detach( pthread_self() );

  /* Log entry to let the world know we're running. */
  if( Verbosity > 2 )
    LockLog( "Responder() running to handle a new connection.\n" );

  /* Set a timeout on the i/o socket. */
  if( setsockopt( client_sock, SOL_SOCKET, SO_RCVTIMEO,
                  (void *)tv, sizeof( struct timeval ) ) )
    {
    /* This should never happen. */
    LockLog( "Error setting timeout on socket; %s.\n", ErrStr );
    run = false;
    }

  /* Read and handle request messages, one at a time.  */
  while( run )
    {
    }

  /* All done.  Close the socket and the thread.  */
  (void)close( client_sock );
  return( NULL );
  } /* Responder */


static void Listener( const int lsock )
  /* ------------------------------------------------------------------------ **
   * Listen for incomming connection requests and spawn responder threads.
   *
   *  Input:  lsock - Listening socket.
   *
   *  Output: <none>
   *
   *  Notes:  This function is run within the primary thread, but it is
   *          started after the worker thread has been spun off so it
   *          must lock the global mutex before accessing any commonly
   *          used objects.
   *
   *          We allocate an integer from the heap, copy the socket number,
   *          and pass the pointer to the child.  This is done in part to
   *          avoid an annoying problem.  On 64-bit systems (it seems) the
   *          integer type is a different size than the void * type.  Doing
   *          things the old fashioned way (casting the int to void * and
   *          then casting back within the child) generates a legitimate
   *          warning.  Casting between different size types may not work
   *          as we would expect.
   *
   *          As long as we can get the integer from memory, this method is
   *          more 'correct'... sort of.
   *
   *  See Also: <Responder()>
   *
   * ------------------------------------------------------------------------ **
   */
  {
  int       newSock;
  int       result = 0;
  int      *parptr;
  pthread_t threadhandle;

  /* Wait for connection requests, then spawn off threads to handle the
   * incoming connections.
   */
  while( (newSock = accept( lsock, NULL, NULL )) >= 0 )
    {
    parptr = (int *)malloc( sizeof( int ) );
    if( NULL != parptr )
      {
      *parptr = newSock;
      result  = pthread_create( &threadhandle, NULL, &Responder, parptr );
      }
    if( (NULL == parptr) || result )      /* Check for problems.  */
      {
      if( 0 == pthread_mutex_lock( &GlobalMutex ) )
        {
        if( NULL == parptr )
          {
          LogX( EXIT_FAILURE,
                "Failure: Memory allocation failure creating subthread.\n" );
          }
        else
          {
          /* We free <parptr> here because the subthread was not created.
           *  Normally, <parptr> would be freed by the subthread.
           */
          Log( "Warning: Error creating responder subthread; %s.\n",
               strerror( result ) );
          free( parptr );
          }
        (void)pthread_mutex_unlock( &GlobalMutex );
        }
      (void)close( newSock );
      }
    }

  /* Lock the mutex to write the error message to the log.
   *  To get here, there must have been an error returned by <accept()>.
   */
  if( 0 == pthread_mutex_lock( &GlobalMutex ) )
    {
    /* The pthread lock does not modify errno, so we don't need to store it.  */
    Log( "Failure: Error accepting socket connection; %s.\n", ErrStr );
    (void)pthread_mutex_unlock( &GlobalMutex );
    }
  close( lsock );
  } /* Listener */


static void WorkHash( const char *srcPathName )
  /* ------------------------------------------------------------------------ **
   * Create a hash cache file given a source file name.
   *
   *  Input:  srcPathName - The pathname of the source file to be hashed.
   *
   *  Output: <none>
   *
   *  Notes:  Dancing with the mutex.
   *
   * ------------------------------------------------------------------------ **
   */
  {
  pd_ConfigRec  *entry;                   /* Configuration record pointer.    */
  char          *cacheDir;                /* Copy of the cacheDir path.       */
  int            minBlocks;               /* Minimum source file block size.  */
  pd_v1HashType  hashType;                /* Type of hash to be used.         */
  unsigned char  key[PD_V1_KEY_SIZE];     /* SourceDir's Server Secret.       */
  int            result;                  /* Store function call return val.  */
  int            syserr;                  /* Store returned system error val. */
  struct timeval tval[1];                 /* For calculating hash times.      */

  /* Try to grab the mutex.
   *  If we can't grab the mutex, then something's wrong but we cannot log it
   *  because we need the mutex in order to (safely) write to the log.  We'll
   *  have to bail out.
   */
  if( 0 != pthread_mutex_lock( &GlobalMutex ) )
    return;

  /* We have mutex.
   *  Find the config record that points to the source directory tree in
   *  which the source file resides.
   */
  entry = pd_FindSrcDir( Cfg, srcPathName );
  if( NULL == entry )
    {
    if( Verbosity > 1 )
      Log( "Queued file is not in scope: %s\n", srcPathName );
    (void)pthread_mutex_unlock( &GlobalMutex );
    return;
    }
  /* This should be impossible.
   *  Check PD_read_config if this ever happens.
   */
  if( NULL == (entry->cacheDir) )
    {
    Log( "Warning: Bad configuration entry; cacheDir is NULL.\n" );
    (void)pthread_mutex_unlock( &GlobalMutex );
    return;
    }

  /* We have mutex and a configuration entry.
   *  Copy all of the config values so that we can release the mutex.
   */
  cacheDir  = strdup( entry->cacheDir );
  minBlocks = entry->minBlocks;
  hashType  = entry->v1HashType;
  syserr    = 0;
  (void)memcpy( key, entry->userParam, PD_V1_KEY_SIZE );
  /* Unlock the mutex.  */
  (void)pthread_mutex_unlock( &GlobalMutex );

  /* Check that the <cacheDir> copy was successfully created. */
  if( NULL == cacheDir )
    {
    if( Verbosity )
      Log( "Warning: Memory allocation failure in WorkHash().\n" );
    return;
    }

  /* If anyone knows any reason why this hash file should not be created,
   *  speak now...
   */
  result = pd_v1ShouldHash( srcPathName, cacheDir, minBlocks );
  if( pd_Success != result )
    {
    if( Verbosity > 1 )
      {
      Log( "Won't hash %s; %s.\n", srcPathName,
           pd_v1StrResult( result ) );
      }
    free( cacheDir );
    return;
    }

  /* If we're going to output timing, try to get the start time.
   *  Set the start time to zero if the gettimeofday(2) call fails.
   */
  if( (Verbosity > 2) && (0 != gettimeofday( tval, NULL )) )
    tval->tv_sec = tval->tv_usec = 0;

  /* Now do the hashing.  */
  result = pd_v1CreateHashCache( srcPathName,
                                 cacheDir,
                                 hashType,
                                 key,
                                 &syserr );
  /* Optionally generate the delta time.  */
  if( Verbosity > 2 )
    deltaTval( tval );
  /* Clean up. */
  free( cacheDir );

  /* If we're not going to (or can't) report anything, we're done.  */
  if( (Verbosity < 1) || (0 != pthread_mutex_lock( &GlobalMutex )) )
    return;

  /* Report the results.
   *  It is not a fatal error to fail to create the cache file, but it should
   *  probably be logged.  Logging requires the mutex.
   */
  if( pd_Success == result )
    {
    if( Verbosity > 2 )
      {
      if( (0 != tval->tv_sec) || (0 !=tval->tv_usec) )
        {
        int m  = ((tval->tv_sec) / 60);
        int s  = ((tval->tv_sec) - (m * 60));
        int ms = ((tval->tv_usec) / 1000);

        if( ((tval->tv_usec) - (ms * 1000)) >= 500 )
          ++ms;
        Log( "  Hashed: %s in %0dm%0d.%0.3ds.\n", srcPathName, m, s, ms );
        }
      else
        Log( "  Hashed: %s.\n", srcPathName );
      }
    }
  else
    {
    if( syserr )
      Log( "Failure hashing %s; %s; %s.\n", srcPathName,
           pd_v1StrResult( result ), strerror( syserr ) );
    else
      Log( "Failure hashing %s; %s.\n", srcPathName,
           pd_v1StrResult( result ) );
    }

  /* And release the mutex again. */
  (void)pthread_mutex_unlock( &GlobalMutex );
  } /* WorkHash */


static void *WorkerMain( void *thingy )
  /* ------------------------------------------------------------------------ **
   * Worker thread mainline.
   *
   *  Input:  thingy  - Pointer to an opaque blob that currently isn't used.
   *                    This is the <void *arg> parameter to
   *                    pthread_create(3).
   *
   *  Output: Always returns NULL.
   *
   *  Notes:  This function is the mainline of a background thread.  It's
   *          job is to generate the hash cache files.
   *
   *  FIX:    The wDir state is designed to allow the worker thread to
   *          traverse configured source directories and hash files that
   *          have not been requested yet.  The requested files, listed
   *          in the <WorkQueue> have higher priority.  Unfortunately,
   *          directory traversal has not been implemented yet.
   *
   *          In addition, we should traverse the cache directories and
   *          purge cache files that are out of date or for which the
   *          source file no longer exists.
   *
   * ------------------------------------------------------------------------ **
   */
  {
  static enum { wNone, wStop, wQueue, wDir } doState;   /* What shall we do?  */
  static struct timespec ts = { 0, 500000000 };         /* Half a second.     */
  WorkItem              *srcEntry = NULL;

  do
    {
    /* Start our loop by waiting a half second, just to pace ourselves. */
    (void)nanosleep( &ts, NULL );

    /* Determine which action to take, and collect any required data.
     *  This requires locking/unlocking the global mutex.
     */
    doState = wNone;      /* Default action.  */
    if( 0 == pthread_mutex_lock( &GlobalMutex ) )
      {
      /* Note:  See pthread_mutex_lock(3).  We do not check for an error
       *        because none of the listed possibilities are at all likely
       *        to occurr and, if an error were to occur, we don't have a
       *        sensible way of handling it (other than to wait and retry).
       */
      if( Shutdown )
        doState = wStop;
      else
        {
        if( 0 == ubi_slCount( WorkQueue ) )
          doState = wDir;
        else
          {
          srcEntry = (WorkItem *)ubi_slDequeue( WorkQueue );
          if( (NULL != srcEntry) && (NULL != srcEntry->srcPath) )
            {
            doState = wQueue;
            if( Verbosity > 2 )
              Log( "Dequeued: %s\n", srcEntry->srcPath );
            }
          else
            Log( "Error: NULL entry in priority queue.\n" );
          }
        }
      (void)pthread_mutex_unlock( &GlobalMutex );
      }

    /* Now do the thing.  */
    switch( doState )
      {
      case wQueue:
        /* Hash an entry from the queue, then free the entry as a whole.  */
        if( srcEntry )
          {
          WorkHash( srcEntry->srcPath );
          free( srcEntry );
          }
        break;
      case wDir:
        /* Hash an entry from a source directory. */
        /* FIX: Need directory traversal. */
        break;
      default:
        break;
      }

    } while( wStop != doState );

  return( NULL );
  } /* WorkerMain */


static void StartWorker( void )
  /* ------------------------------------------------------------------------ **
   * Start a background thread to generate hash cache files.
   *
   *  Input:  <none>
   *  Output: <none>
   *
   *  Notes:  The worker thread does the work of creating hash cache files
   *          from source content.  It runs separately so that it does not
   *          interfere with communication with our clients.
   *
   *          <WorkerThread> is a global variable.
   *          <WorkerMain()> is is the "mainline" of the worker thread.
   *
   * ------------------------------------------------------------------------ **
   */
  {
  int            result;
  pthread_attr_t attr[1];

  /* Set up the attributes to make the thread joinable, then start it.  */
  if( (result = pthread_attr_init( attr )) )
    LogX( EXIT_FAILURE, "Failure initializing worker thread attributes; %s.\n",
          strerror( result ) );

  if( (result = pthread_attr_setdetachstate( attr, PTHREAD_CREATE_JOINABLE )) )
    LogX( EXIT_FAILURE,
          "Failure setting \"joinable\" attribute for worker thread; %s.\n",
          strerror( result ) );

  if( (result = pthread_create( &WorkerThread, attr, WorkerMain, NULL )) )
    LogX( EXIT_FAILURE, "Failure spawning worker thread; %s.\n",
          strerror( result )  );
  } /* StartWorker */


static int OpenListenSock( const char *sockpath )
  /* ------------------------------------------------------------------------ **
   * Open a Unix Domain socket and set it to listen for connection requests.
   *
   *  Input:  sockpath  - The pathname of the Unix Domain socket to be
   *                      opened for listening.
   *
   *  Output: The opened and listening socket.
   *          Only a valid value will be returned.  On error, this function
   *          will exit the program.
   *
   *  Notes:  We call this prior to spinning off any threads, so we can avoid
   *          locking the global mutex.
   *
   * ------------------------------------------------------------------------ **
   */
  {
  struct sockaddr_un laddr[1];
  int                lsock;

  /* Sanity check.
   * We must be able to fit the socket path into a Unix Domain socket address.
   */
  if( strlen( sockpath ) >= sizeof( laddr->sun_path ) )
    {
    LogX( EXIT_FAILURE,
          "Annoyance: Path '%s' exceeds maximum unix domain address length.\n",
          sockpath );
    }

  /* Create a unix domain socket. */
  lsock = socket( AF_UNIX, SOCK_STREAM, 0 );
  if( lsock < 0 )
    {
    LogX( EXIT_FAILURE,
          "Failure: Unable to create unix domain socket; %s.\n", ErrStr );
    }

  /* Bind the socket to the name within the namespace. */
  (void)unlink( sockpath );
  (void)memset( laddr, 0, sizeof( struct sockaddr_un ) );
  laddr->sun_family = AF_UNIX;
  (void)strcpy( laddr->sun_path, sockpath );
  if( bind( lsock, (struct sockaddr *)laddr, sizeof( laddr ) ) < 0 )
    {
    (void)close( lsock );
    LogX( EXIT_FAILURE,
          "Failure: Socket bind() to '%s' failed; %s.\n", sockpath, ErrStr );
    }

  /* Set the socket to listen. */
  if( listen( lsock, 32 ) < 0 )
    {
    (void)close( lsock );
    (void)unlink( sockpath );
    LogX( EXIT_FAILURE,
          "Failure: Cannot listen on unix domain socket '%s'; %s.\n",
          sockpath, ErrStr );
    }

  return( lsock );
  } /* OpenListenSock */


static void Spawn( void )
  /* ------------------------------------------------------------------------ **
   * Spawn a daemon process, which will take over control for us.
   *
   *  Input:  <none>
   *  Output: <none>
   *
   *  Notes:  This function causes the program to run in the background.
   *
   *          If the child process is created successfully, the parent
   *          process is terminated using _exit(2).  This bypasses executing
   *          any functions registered with atexit(3) or on_exit(3).  We
   *          don't have any such functions but, even so, this is the normal
   *          way to exit the parent process.
   *          See: http://www.steve.org.uk/Reference/Unix/faq_2.html#SEC6
   *
   * ------------------------------------------------------------------------ **
   */
  {
  pid_t pid = fork();

  if( pid < 0 )   /* Error. */
    LogX( EXIT_FAILURE, "Cannot spawn child process; %s\n", ErrStr );

  if( pid > 0 )   /* Parent process; just exit. */
    _exit( EXIT_SUCCESS );

  /* Child process.
   */
  if( setsid() < 0 )
    LogX( EXIT_FAILURE, "Failure: setsid(2) failed in Spawn(); %s.\n", ErrStr );
  if( Verbosity )
    Log( "Process %d spawned.\n", getpid() );
  /* Close standard file descriptors. */
  close(  STDIN_FILENO );
  close( STDOUT_FILENO );
  close( STDERR_FILENO );
  return;
  } /* Spawn */


static void ReadKeys( void )
  /* ------------------------------------------------------------------------ **
   * Read and store the server secret signing keys from the key files.
   *
   *  Input:  <none>
   *  Output: <none>
   *
   *  Notes:  The signing key is officially known as the "Server Secret".
   *          See the definition of Server Secret in [MS-PCCRC], section 1.1.
   *
   *          The "Server Secret" is the SHA-256 hash of "an arbitrary length
   *          binary string stored on the server”.  [MS-PCCRC] does not give
   *          a name to this arbitrary binary string.  In Prequel
   *          documentation, it is referred to as the "Server Passphrase".
   *          So, the Server Secret is the hash of the Server Passphrase.
   *
   *          This function makes one or more passes through the sourcedir
   *          configuration list.  Each time, it finds the first entry
   *          that has a NULL <userParam> pointer.  It attempts to read the
   *          signing key from the keyfile.  If it succeeds, it goes
   *          through the rest of the list looking for matching keyfile
   *          names.  If it finds a match, it points the <userParam> of
   *          the matching entry to the already-copied key.
   *
   *          The userParam pointer could be used for storing a more complex
   *          structure or other extended information.  Right now, it's only
   *          used for storing the signing key.
   *
   * ------------------------------------------------------------------------ **
   */
  {
  FILE          *keyF;
  pd_ConfigRec  *entry;
  char          *kfName;
  unsigned char *ss = NULL;
  size_t         result;

  do
    {
    kfName = NULL;
    forEach( entry, Cfg )   /* Read ConfigRec entries sequentially. */
      {
      if( NULL == entry->userParam )
        {
        if( NULL == kfName )
          {
          kfName = entry->keyFileName;
          if( NULL == (ss = (unsigned char *)malloc( PD_V1_KEY_SIZE )) )
            LogX( EXIT_FAILURE,
                  "Failure: malloc(3) failed in ReadKeys(); %s.\n", ErrStr );
          if( NULL == (keyF = fopen( kfName, "r" )) )
            LogX( EXIT_FAILURE,
                  "Failure: Could not open keyfile %s; %s.\n", kfName, ErrStr );
          result = fread( ss, 1, PD_V1_KEY_SIZE, keyF );
          if( PD_V1_KEY_SIZE != result )
            LogX( EXIT_FAILURE,
                  "Failure: Only %d bytes in keyfile %s.\n", result, kfName );
          (void)fclose( keyF );
          entry->userParam = ss;
          }
        else
          {
          if( 0 == strcmp( kfName, entry->keyFileName ) )
            entry->userParam = ss;
          }
        }
      }
    } while( NULL != kfName );

  } /* ReadKeys */


static void ReadConfig( char *fname )
  /* ------------------------------------------------------------------------ **
   * Open, read, and interpret the configuration file.
   *
   *  Input:  fname - The name of the file to open, or NULL.
   *                  If <fname> is NULL, then the default file name will
   *                  be used.
   *
   *  Output: <none>
   *
   *  Notes:  The configuration file format was inspired, somewhat, by the
   *          format of the ISC dhcpd.conf file.
   *
   * ------------------------------------------------------------------------ **
   */
  {
  FILE *configF;

  /* Ensure that we have a configurage file pathname,
   * then attempt to open the file for reading.
   */
  if( NULL == fname )
    fname = DEFAULT_CONFIG_FILE;
  if( NULL == (configF = fopen( fname, "r" )) )
    Fail( "Unable to open configuration file \"%s\" for input; %s.\n",
          fname, ErrStr );

  /* Parse it.
   *  <Cfg> is a global pointer.
   */
  Cfg = pd_ParseCfg( configF );

  /* Close it.
   */
  fclose( configF );
  } /* ReadConfig */


static void ReadOpts( int argc, char *argv[] )
  /* ------------------------------------------------------------------------ **
   * Interpret any command-line options, and the configuration file.
   *
   *  Input:  argc  - Count of arguments.
   *          argv  - Array of pointers to argument strings.
   *
   *  Output: <none>
   *
   *  Notes:  This function also calls <ReadConfig()>, which reads and
   *          interprets the configuration file.
   *
   *          This is quite a workhorse function.  It handles collecting
   *          and validating the configuration of the daemon.
   *
   * ------------------------------------------------------------------------ **
   */
  {
  int           c;
  FILE         *LogF;
  extern char  *optarg;
  extern int    optind;
  char         *ConfigFile  = NULL;
  char         *LogFile     = NULL;
  bool          VerbSet     = false;
  bool          SpewHelp    = false;
  bool          SpewVersion = false;
  bool          TestConfig  = false;

  /* Read the arguments.
   */
  while( (c = getopt( argc, argv, "c:fhl:qtvV" )) >= 0 )
    {
    switch( c )
      {
      case 'c':
        ConfigFile  = optarg;
        break;
      case 'f':
        Daemonize   = false;
        break;
      case 'h':
        SpewHelp    = true;
        break;
      case 'l':
        LogFile     = optarg;
        break;
      case 'q':
        Verbosity   = 0;
        VerbSet     = true;
        break;
      case 't':
        TestConfig  = true;
        break;
      case 'v':
        if( Verbosity < 0xFF )
          Verbosity++;
        VerbSet     = true;
        break;
      case 'V':
        SpewVersion = true;
        break;
      default:
        /* Unknown option.  Provide simple help, then exit.
         */
        Verbosity = 0;
        Usage( argv[0], EXIT_FAILURE );
        break;
      }
    }

  /* Provide version information (and more) if it was requested.
   */
  if( SpewVersion )
    {
    Say( "%s\n", Revision );
    if( Verbosity )
      {
      Say( "%s\n", Id );
      if( Verbosity > 1 )
        {
        Say( "%s\n", Copyright );
        if( Verbosity > 2 )
          {
          Say( "%s\n", License );
          if( Verbosity > 3 )
            {
            Say( "Developed in participation with the " );
            Say( "Protocol Freedom Information Foundation.\n" );
            }
          }
        }
      }
    if( SpewHelp )
      {
      if( Verbosity )
        Say( "\n" );
      }
    else
      exit( EXIT_SUCCESS );
    }

  /* If help was requested, send help.
   */
  if( SpewHelp )
    {
    Usage( argv[0], EXIT_SUCCESS );
    }

  /* If the user requested a configuration file test, provide it and
   *  then exit the program.
   */
  if( TestConfig )
    {
    (void)setLogFile( stderr );
    if( NULL == ConfigFile )
      ConfigFile = DEFAULT_CONFIG_FILE;
    ReadConfig( ConfigFile );
    if( (Verbosity == 1) && (NULL != Cfg) )
      Log( "%s: successfully parsed.\n", ConfigFile );
    if( Verbosity > 1)
      pd_DumpCfg( Cfg );
    exit( EXIT_SUCCESS );
    }

  /* Enable logging.
   *  If a log file name was specified, then all messages from this point
   *  on will be directed to the log file.
   *  If no log file was specified, and we will run as a daemon, then we
   *  start logging to syslog().
   *  Otherwise, we log to <stderr> unless/until a log file name is given
   *  in the configuration file.
   */
  if( NULL == LogFile )
    {
    if( Daemonize )
      OpenSyslog( SYSLOG_NAME );
    else
      (void)setLogFile( stderr );
    }
  else
    {
    LogF = fopen( LogFile, "a" );
    if( NULL == LogF )
      Fail( "Unable to open log file \"%s\" for output; %s.\n",
            LogFile, ErrStr );
    (void)setLogFile( LogF );
    }

  /* Open and read the configuration file.
   *  Command-line options override configfile options.  This is particularly
   *  tricky when dealing with logging, which has already started.
   */
  ReadConfig( ConfigFile );
  if( NULL == Cfg )         /* Parsing returned no configuration.  Exit.  */
    LogX( EXIT_FAILURE, "Null configuration.  Exiting.\n" );

  if( NULL == LogFile )
    {
    /* We have already started logging to syslog (background) or stderr
     * (foreground).  If a log file was specified in the config file, and
     * if we are not running in the foreground, use the specified config
     * file.
     */
    if( (NULL != Cfg->logFileName) && Daemonize )
      {
      LogF = fopen( Cfg->logFileName, "a" );
      if( NULL == LogF )
        Fail( "Unable to open log file \"%s\" for output; %s.\n",
              Cfg->logFileName, ErrStr );
      (void)setLogFile( LogF );
      }
    else
      {
      /* When writing to <stderr>, don't print timestamps.  */
      (void)setLogTimeStamp( false );
      }
    }
  else
    {
    /* If we have a command-line specified logfile, store it in the Cfg
     *  structure for later use.
     */
    Cfg->logFileName = replaceStr( LogFile, Cfg->logFileName );
    }

  /* User-set verbosity overrides config file.  */
  if( VerbSet )
    {
    pd_ConfigRec *entry;

    forEach( entry, Cfg )
      entry->verbosity = (0xFF & Verbosity);
    }

  } /* ReadOpts */


/* -------------------------------------------------------------------------- **
 * Mainline:
 */

int main( int argc, char *argv[] )
  /* ------------------------------------------------------------------------ **
   * Program mainline.
   *
   *  Input:  argc  - You know what this is.
   *          argv  - You know what to do.
   *
   *  Output: EXIT_SUCCESS or, on failure, EXIT_FAILURE.
   *
   * ------------------------------------------------------------------------ **
   */
  {
  int listenSock;

  /* Gather working parameters.
   *  Note that ReadOpts() also takes care of reading the configuration file.
   */
  ReadOpts( argc, argv );         /* Get all set up to run. */
  ReadKeys();                     /* Find the signing keys. */

  /* Become a daemon, unless we were told otherwise.  */
  if( Daemonize )
    Spawn();

  /* Before creating any subthreads, let's try to open the listening socket.  */
  listenSock = OpenListenSock( Cfg->sockFileName );

  /* Initialize the priority queue and start the worker thread. */
  (void)ubi_slInitList( WorkQueue );
  StartWorker();

  /* Listen for incoming requests on the named Unix Domain socket.  */
  Listener( listenSock );

  /* When we stop listening, it's time to shut down the worker thread.  */
  (void)pthread_mutex_lock( &GlobalMutex );
  Shutdown = true;
  (void)pthread_mutex_unlock( &GlobalMutex );
  (void)pthread_join( WorkerThread, NULL );

  /* Clean up and exit. */
  if( Verbosity )
    Log( "Normal exit.\n" );
  return( EXIT_SUCCESS );
  } /* main */

/* ========================================================================== */