Skip to content

Installation Guide

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

Software dependencies

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 typically offers better performance. The performance (in terms of credentials per second) can be measured with the remunge executable. The selection of the cryptographic library can be overridden with the configure --with-crypto-lib option.

MUNGE includes bzip2 and zlib compression support if these libraries are found 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 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

On most platforms, the munged daemon does not require root privileges. If possible, it should be run as a non-privileged user.

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. Since authentication is based on UID and GID, all hosts within this realm are expected to have consistent user/UID and group/GID mappings. Credentials are valid only within a 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 it 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. It also 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, and if the local defaults used to encode the credential can be decoded by the remote daemon.
  $ munge -n | 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, and if the remote defaults used to encode the credential can be decoded by the local daemon.
  $ ssh somehost munge -n | 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

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

  • Error: Found pid 1234 bound to socket "/run/munge/munge.socket.2"
    The munged daemon (pid 1234) is already running.

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