MUNGE Installation Guide


1. Installing the Software

   MUNGE requires either the Libgcrypt or OpenSSL cryptographic library.
   Libgcrypt is licensed under the LGPL, whereas OpenSSL is licensed under
   dual original-BSD-style licenses.  On some systems, the OpenSSL license
   is incompatible with the GPL license used by MUNGE.  While Libgcrypt
   offers a more compatible license, OpenSSL offers better performance.
   The selection of the cryptographic library can be specified at build
   time with the configure script's "--with-crypto-lib" option.

   MUNGE includes bzip2 and zlib compression support if these libraries
   are found when the software is built.

   MUNGE can be installed using one of the following methods:

   A. RPMs:

      You can build binary RPMs from either the tarball or the source RPM:

      $ rpmbuild -tb --clean munge-x.y.z.tar.bz2
      $ rpmbuild --rebuild --clean munge-x.y.z-1.src.rpm

      This will generate three binary RPMs: munge, munge-devel, and
      munge-libs.  The munge RPM contains the daemon and client binaries.
      The munge-devel RPM contains a header file and static library for
      developing applications using MUNGE.  The munge-libs RPM contains a
      shared library for running applications using MUNGE.

      The binary RPMs can be installed with rpm:

      # rpm -ivh munge-x.y.z-1.i386.rpm \
        munge-devel-x.y.z-1.i386.rpm munge-libs-x.y.z-1.i386.rpm

   B. Source:

      Edit src/libcommon/munge_defs.h to customize values if necessary.
      To compile the software, execute the following command; you may need
      to su to root in order to perform the "make install":

      $ ./configure --prefix=/usr --sysconfdir=/etc --localstatedir=/var \
        && make && make install


2. Securing the Installation

   On most platforms, the munged daemon does not require root privileges.
   If possible, you should run the daemon as a non-privileged user.  This can
   be controlled by the init script as detailed in the "Starting the Daemon"
   section below.

   By default, the munged daemon uses the following system directories:

   A. /etc/munge/
      This directory contains the daemon's secret key.  The recommended
      permissions for it are 0700.

   B. /var/lib/munge/
      This directory contains the daemon's PRNG seed file.  It is also
      where the daemon creates pipes for authenticating clients via
      file-descriptor-passing.  If the file-descriptor-passing authentication
      method is being used, this directory must allow execute permissions for
      all; however, it should not expose read permissions.  The recommended
      permissions for it are 0711.

   C. /var/log/munge/
      This directory contains the daemon's log file.  The recommended
      permissions for it are 0700.

   D. /var/run/munge/
      This directory contains the Unix domain socket for clients to
      communicate with the daemon.  It also contains the daemon's pid file.
      This directory must allow execute permissions for all.  The recommended
      permissions for it are 0755.

   These directories must be owned by the user that the munged daemon will
   run as.  They cannot allow write permissions for group or other (unless
   the sticky-bit is set).  In addition, all of their parent directories in
   the path on up to the root directory must be owned by either root or the
   user that the munged daemon will run as.  None of them can allow write
   permissions for group or other (unless the sticky-bit is set).


3. Creating a Secret Key

   A security realm encompasses a group of hosts having common users and
   groups.  It is defined by a shared cryptographic key.  Credentials are
   valid only within a security realm.  All munged daemons within a security
   realm must possess the same secret key.

   By default, the secret key resides in "/etc/munge/munge.key".  This
   location can be overridden on the munged command-line or via the init
   script as detailed in the "Starting the Daemon" section below.

   You can create a secret key using a variety of methods:

   A. Wait around for some random data (recommended for the paranoid):
      $ dd if=/dev/random bs=1 count=1024 >/etc/munge/munge.key

   B. Grab some pseudorandom data (recommended for the impatient):
      $ dd if=/dev/urandom bs=1 count=1024 >/etc/munge/munge.key

   C. Enter the hash of a password:
      $ echo -n "foo" | sha1sum | cut -d' ' -f1 >/etc/munge/munge.key

   D. Enter a password directly (not recommended):
      $ echo "foo" >/etc/munge/munge.key

   This file should be permissioned 0400 and owned by the user that the
   munged daemon will run as.  Securely propagate this file (e.g., via ssh)
   to all other hosts within the same security realm.


4. Starting the Daemon

   On each host within the security realm, invoke the daemon directly
   (/usr/sbin/munged) or use the init script (/etc/init.d/munge start).
   The init script sources /etc/default/munge (found on Debian-based systems)
   and /etc/sysconfig/munge (found on RedHat-based systems), if present,
   to set variables recognized by the script.

   The DAEMON_ARGS variable passes additional command-line options to
   the daemon; for example, this can be used to override the location
   of the secret key (--key-file) or set the number of worker threads
   (--num-threads).  If the init script is invoked by root, the USER variable
   causes the daemon to execute under the specified username; the "munge"
   user is used by default.


5. Testing the Installation

   The following steps can be performed to verify that the software has
   been properly installed and configured:

   A. Generate a credential on stdout:
      $ munge -n

   B. Check if a credential can be locally decoded:
      $ munge -n | unmunge

   C. Check if a credential can be remotely decoded:
      $ munge -n | ssh somehost unmunge

   D. Run a quick benchmark:
      $ remunge

   If you encounter problems, check if the munged daemon is
   running (/etc/init.d/munge status).  Also, check the logfile
   (/var/log/munge/munged.log) or try running the daemon in the foreground
   (/usr/sbin/munged --foreground).  Some error conditions can be overridden
   by "forcing" the daemon (/usr/sbin/munged --force).


6. Using MUNGE

   Applications written in C/C++ can use the interface provided by <munge.h>.
   Scripts can invoke the /usr/bin/munge and /usr/bin/unmunge executables --
   specify "-h" or "--help" for usage information, or Read The Fine Manpages.
