Skip to content

Installation Guide

Jump to bottom
Chris Dunlap edited this page Jan 20, 2020 · 20 revisions

Software dependencies

  • Libgcrypt or OpenSSL
    Either the Libgcrypt or OpenSSL cryptographic library is required. Libgcrypt is distributed under LGPLv2.1+. OpenSSL switched to the ASLv2 license for the 3.0.0 release, but all prior releases are covered by the dual OpenSSL and SSLeay license which, on some distributions, is incompatible with the GPL license used by MUNGE. While Libgcrypt offers a more compatible license, OpenSSL may offer better performance (which can be measured with the remunge executable).

  • bzip2
    Support for bzip2 compression will be included if the library is found when the software is built.

  • zlib
    Support for zlib compression will be included if the library is found when the software is built.

  • pkgconf or pkg-config
    A .pc file will be installed if a suitable directory is found or specified when the software is built.

Building the latest release

Installing from the source tarball

The commands ./configure; make; make install should configure, build, and install the software. For example:

  tar xJf munge-0.5.14.tar.xz \
  && cd munge-0.5.14          \
  && ./configure              \
     --prefix=/usr            \
     --sysconfdir=/etc        \
     --localstatedir=/var     \
     --runstatedir=/run       \
  && make                     \
  && make check               \
  && sudo make install

The make check command is optional; it runs the test suite.

The configure --runstatedir option is slated to appear in autoconf-2.70; however, it has been backported to Debian's autoconf-2.69-9. The configure --with-runstatedir option can also be used to set this value in case the configure script was built by an earlier version of autoconf.

The following configure options allow further customization of the installation:

  • --with-crypto-lib=(libgcrypt|openssl)
    cryptographic library selection

  • --with-logrotateddir=DIR / --without-logrotateddir
    installation directory for logrotate config files

  • --with-munge-socket=PATH
    socket pathname default for client/server communication

  • --with-pkgconfigdir=DIR / --without-pkgconfigdir
    installation directory for pkg-config .pc files

  • --with-runstatedir=DIR
    installation director for modifiable per-process data; overrides --runstatedir if both are specified

  • --with-sysconfigdir=DIR / --without-sysconfigdir
    installation directory for systemd/sysvinit config files

  • --with-systemdunitdir=DIR / --without-systemdunitdir
    installation directory for systemd service unit files

  • --with-sysvinitddir=DIR / --without-sysvinitddir
    installation directory for SysV-style init scripts

Installing from rpm on CentOS/Fedora

RPMs for recent CentOS/Fedora can be built directly from the tarball. As of 0.5.14, GPG verification of the source is performed by default. This requires the public key (dun.gpg) and detached GPG signature (e.g., munge-0.5.14.tar.xz.asc) to reside in the same directory as the tarball (e.g., munge-0.5.14.tar.xz):

  $ ls
  dun.gpg  munge-0.5.14.tar.xz  munge-0.5.14.tar.xz.asc
  
  $ rpmbuild -tb munge-0.5.14.tar.xz

GPG verification can be disabled by specifying --without verify to rpmbuild; this removes the need for the public key and detached signature:

  $ rpmbuild -tb --without verify munge-0.5.14.tar.xz

Three or more binary RPMs will be generated: munge, munge-devel, munge-libs, and potentially a debugsource and a couple debuginfo RPMs. The munge RPM contains the munged daemon, mungekey utility, and client executables. The munge-devel RPM contains a header file for developing applications using MUNGE. The munge-libs RPM contains a shared library for running applications that use MUNGE.

The binary RPMs can be installed with rpm:

  $ sudo rpm -ivh munge-0.5.14-1.x86_64.rpm \
    munge-devel-0.5.14-1.x86_64.rpm munge-libs-0.5.14-1.x86_64.rpm

Installing from rpm on CentOS 6

The top-level munge.spec requires systemd, but RPMs for CentOS 6 using a SysV-style init script can be built using the specfile in extra/munge.spec-centos.6. For example, to extract the alternate specfile and then build RPMs in ${HOME}/rpmbuild using the munge-0.5.14.tar.xz tarball in the current directory:

  $ tar xJf munge-0.5.14.tar.xz munge-0.5.14/extra/munge.spec-centos.6

  $ rpmbuild -bb -D "%_topdir ${HOME}/rpmbuild" -D "%_sourcedir `pwd`" \
    munge-0.5.14/extra/munge.spec-centos.6

Installing pre-built packages

Work in progress...

Securing the installation

The munged daemon does not generally require root privileges (see the supported authentication methods for details). If possible, munged should be run as a dedicated non-privileged user in accordance with the principle of least privilege.

The munged daemon uses the following system directories (note that directories of the form ${somedir} refer to the configure script's installation directories and must be substituted accordingly):

  • ${sysconfdir}/munge [/etc/munge]
    This directory will contain the daemon's key. Its permissions should be set to 0700.

  • ${localstatedir}/lib/munge [/var/lib/munge]
    This directory will contain the daemon's PRNG seed file. On systems where a file-descriptor-passing authentication method is used, this is also where the daemon creates pipes for authenticating clients. Its permissions should be set to 0711 if using file-descriptor-passing, or 0700 otherwise.

  • ${localstatedir}/log/munge [/var/log/munge]
    This directory will contain the daemon's log file. Its permissions should be set to 0700.

  • ${runstatedir}/munge [/run/munge]
    This directory will contain the Unix domain socket for clients to communicate with the local daemon. It will also contain the daemon's pid file. This directory must allow execute permissions for all. Its permissions should be set to 0755.

These directories must be owned by the same user as the running daemon process. They cannot allow write permissions for group unless the sticky bit is set or the directory is owned by the trusted group (see munged for details on the --trusted-group option), and they cannot allow write permissions for 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 same user as the daemon process. They cannot allow write permissions for group unless the sticky bit is set or the directory is owned by the trusted group, and they cannot allow write permissions for other unless the sticky bit is set.

Configuration and setup

Creating a key

All munged daemons within a security realm share a common key. This key is used to cryptographically protect the credential. Consequently, credentials are only valid within a given security realm.

The mungekey executable is the key management utility for MUNGE. To ensure the key file maintains the correct ownership and permissions, it should be run by the same user ID that will run the munged daemon process. For example, to create a key:

  $ sudo -u munge ${sbindir}/mungekey --verbose

The key resides in ${sysconfdir}/munge/munge.key. This file must be owned by the same user ID that will run the munged daemon process, and its permissions should be set to 0600. Additionally, this key file will need to be securely propagated (e.g., via ssh) to all hosts within the security realm.

Setting command-line options

When starting the daemon via systemd or the init script, command-line options to munged can be specified in the OPTIONS line of the sysconfig file (typically found in ${sysconfdir}/default/munge or ${sysconfdir}/sysconfig/munge).

Starting and stopping the daemon

The key file ${sysconfdir}/munge/munge.key must be created before starting the daemon.

systemd

Start the daemon automatically at boot:

  $ sudo systemctl enable munge

Start the daemon now:

  $ sudo systemctl start munge

Stop the daemon:

  $ sudo systemctl stop munge

Init script

Systems utilizing init scripts typically start the daemon by passing the "start" command to the script. The location of the script varies. For example:

  $ sudo ${sysconfdir}/init.d/munge start

Stopping the daemon is done similarly:

  $ sudo ${sysconfdir}/init.d/munge stop

Command-line

Start the daemon from the command-line so it runs as a non-privileged user (e.g., "munge"):

  $ sudo -u munge ${sbindir}/munged

Stop the daemon with the --stop command-line option:

  $ sudo -u munge ${sbindir}/munged --stop

Or stop the daemon by sending a SIGTERM to the munged process:

  $ sudo -u munge kill `cat ${runstatedir}/munge/munged.pid`

Do not stop the daemon by sending a SIGKILL (i.e., kill -9). That prevents the daemon from cleaning up -- updating its seed file, removing its pid file, removing its socket, etc.

Troubleshooting

Verify the installation

The following steps can be performed to verify that the software is properly installed and working:

  • Encode a credential. This tests if the munge executable and libmunge library can be found, if munged is running, and if the client (munge/libmunge) can communicate with the server (munged):
  $ munge -n
  • Encode and decode a credential. This is similar to the test above, but also tests that the credential has been properly encoded and successfully decoded. Additionally, it shows the metadata that has been encoded into the credential.
  $ munge -n | unmunge
  • Remotely decode a locally-encoded credential. This tests if local and remote munged daemons are running with the same key, if the two versions are compatible, if the local defaults for encoding the credential can be decoded by the remote daemon, and if the clocks between both hosts are within the specified interval.
  $ munge -n -t 10 | ssh somehost unmunge
  • Locally decode a remotely-encoded credential. This tests if local and remote munged daemons are running with the same key, if the two versions are compatible, if the remote defaults for encoding the credential can be decoded by the local daemon, and if the clocks between both hosts are within the specified interval.
  $ ssh somehost munge -n -t 10 | unmunge

Check the default locations

The default locations for the socket, key file, log file, pid file, and PRNG seed file are configured at build time. These defaults can be found in the munged --help output; look for the values between square brackets:

  $ ${sbindir}/munged --help

Check the log

The munged daemon logs descriptive error messages when possible. If munged fails to start, check the log for details.

  • For systemd, check runtime status information for the munge unit:
  $ sudo systemctl status --full munge
  • For systemd, check the systemd journal:
  $ sudo journalctl -xe | grep munged
  • For systemd, limit journal output to services run by the munge user:
  $ sudo journalctl _UID=$(id -u munge)

  • The munged daemon writes to ${localstatedir}/log/munge/munged.log by default; but, the location of this file can be changed with the munged --log-file option.

  • If munged is started with the --syslog option, log messages are instead written to syslog using the "daemon" facility value. The name of the corresponding log file will vary depending on the syslog configuration.

Run the daemon in the foreground

If munged fails to start, try running it in the foreground. When run in this manner, log messages are written to stderr. But remember to start munged as the appropriate user:

  $ sudo -u munge ${sbindir}/munged --foreground

"Force" the daemon to run (but use with caution!)

Some error conditions can be overridden by "forcing" the daemon. Use the munged --force option to override errors for an existing socket, a lack of PRNG entropy, and insecure file/directory permissions. But use with caution as overriding these errors can affect security:

  $ sudo -u munge ${sbindir}/munged --force

Common errors

  • munge: Error: Failed to access "/run/munge/munge.socket.2": No such file or directory
    The client was unable to connect to the munged daemon listening on the socket /run/munge/munge.socket.2. The daemon is likely not running. Try starting it. If it fails to start, check the log for an error message.

  • unmunge: Error: Invalid credential
    The munged daemon that tried to decode the credential is likely using a different key than the daemon that encoded the credential. First check the key files for both daemons. If they match, try restarting both daemons; since the key file is read when the daemon starts, a running daemon could be using a key that differs from the current contents of its key file.

  • unmunge: Error: Expired credential
    The current time (according to the munged daemon decoding the credential) exceeds the creation time of the credential (according to the munged daemon that encoded it) plus its time-to-live value. Either the clocks are out of sync, or too much time has passed since the credential was created.

  • unmunge: Error: Rewound credential
    The current time (according to the munged daemon decoding the credential) precedes the creation time of the credential (according to the munged daemon that encoded it). Either the clocks are out of sync, or you've opened a rift in the space-time continuum.

  • unmunge: Error: Replayed credential
    The credential has previously been decoded by this particular munged daemon.

  • unmunge: Error: Unauthorized credential
    Either the UID of the client decoding the credential does not match the UID restriction with which the credential was encoded, or the GID of the client decoding the credential (or one of its supplementary group GIDs) does not match the GID restriction with which the credential was encoded.

  • munged: Error: Found pid 1234 bound to socket "/run/munge/munge.socket.2"
    A munged daemon (pid 1234) is already listening on the socket /run/munge/munge.socket.2. The munged daemon creates the socket when it starts, and removes it when it terminates. While multiple munged daemons can run on the same host concurrently, each daemon must use a different socket.

Using MUNGE

Applications written in C/C++ can use the interface defined in <munge.h>. Compiler and linker flags can be obtained from pkg-config:

  $ cc $(pkg-config --cflags --libs munge) -o foo foo.c

Scripts can invoke the munge and unmunge executables -- specify --help for usage information, or Read The Fine Manpages.

Clone this wiki locally