README
1INTRODUCTION
2
3 MUNGE (MUNGE Uid 'N' Gid Emporium) is an authentication service for
4 creating and validating user credentials. It is designed to be highly
5 scalable for use in an HPC cluster environment. It provides a portable
6 API for encoding the user's identity into a tamper-proof credential
7 that can be obtained by an untrusted client and forwarded by untrusted
8 intermediaries within a security realm. Clients within this realm can
9 create and validate credentials without the use of root privileges,
10 reserved ports, or platform-specific methods.
11
12
13RATIONALE
14
15 The need for MUNGE arose out of the HPC cluster environment. Consider the
16 scenario in which a local daemon running on a login node receives a client
17 request and forwards it on to remote daemons running on compute nodes within
18 the cluster. Since the user has already logged on to the login node, the
19 local daemon just needs a reliable means of ascertaining the UID and GID
20 of the client process. Furthermore, the remote daemons need a mechanism to
21 ensure the forwarded authentication data has not been subsequently altered.
22
23 A common solution to this problem is to use Unix domain sockets to
24 determine the identity of the local client, and then forward this
25 information on to remote hosts via trusted rsh connections. But this
26 presents several new problems. First, there is no portable API for
27 determining the identity of a client over a Unix domain socket. Second,
28 rsh connections must originate from a reserved port; the limited number
29 of reserved ports available on a given host directly limits scalability.
30 Third, root privileges are required in order to bind to a reserved port.
31 Finally, the remote daemons have no means of determining whether the
32 client identity is authentic. MUNGE solves all of these problems.
33
34
35USAGE
36
37 A process creates a credential by requesting one from the local
38 MUNGE service, either via the munge_encode() C library call or the
39 munge executable. The encoded credential contains the UID and GID of
40 the originating process. This process sends the credential to another
41 process within the security realm as a means of proving its identity.
42 The receiving process validates the credential with the use of its local
43 MUNGE service, either via the munge_decode() C library call or the unmunge
44 executable. The decoded credential provides the receiving process with a
45 reliable means of ascertaining the UID and GID of the originating process.
46 This information can be used for accounting or access control decisions.
47
48
49DETAILS
50
51 The contents of the credential (including any optional payload data) are
52 encrypted with a key shared by all munged daemons within the security realm.
53 The integrity of the credential is ensured by a message authentication
54 code (MAC). The credential is valid for a limited time defined by its
55 time-to-live (TTL); this presumes clocks within a security realm are
56 in sync. Unexpired credentials are tracked by the local munged daemon in
57 order to prevent replay attacks on a given host. Decoding of a credential
58 can be restricted to a particular user and/or group ID. The payload data
59 can be used for purposes such as embedding the destination's address to
60 ensure the credential is only valid on a specific host. The internal
61 format of the credential is encoded in a platform-independent manner.
62 And the credential itself is base64 encoded to allow it to be transmitted
63 over virtually any transport.
64
65
66LICENSE
67
68 MUNGE is free software: you can redistribute it and/or modify it under
69 the terms of the GNU General Public License as published by the Free
70 Software Foundation, either version 3 of the License, or (at your option)
71 any later version.
72
73 Additionally for the MUNGE library (libmunge), you can redistribute it
74 and/or modify it under the terms of the GNU Lesser General Public License
75 as published by the Free Software Foundation, either version 3 of the
76 License, or (at your option) any later version.
77
78
79KEYS
80
81 Releases are signed with the following GPG key:
82
83 pub rsa4096/0x3B7ECB2B30DE0871 2011-10-01 [SC]
84 Key fingerprint = A441 880C 3D4C 7C36 C5DD 41E1 3B7E CB2B 30DE 0871
85 uid [ultimate] Chris Dunlap <chris.m.dunlap@gmail.com>
86 uid [ultimate] Chris Dunlap <cdunlap@llnl.gov>
87 uid [ultimate] Chris Dunlap <dun@imsa.edu>
88 sub rsa4096/0x48A5CADDECA74B8A 2011-10-01 [E]
89
90
91HOMEPAGE
92
93 https://dun.github.io/munge/
94
README.AIX
1If you're building MUNGE from source on AIX, you need to export the
2OBJECT_MODE environment variable to your environment. It should be set to
3either "32" or "64" depending on whether you want code to be generated for
4a 32-bit or 64-bit architecture. If you are using gcc, you also need to
5set CFLAGS to either "-maix32" or "-maix64". Finally, you should set the
6"--enable-arch" option as well:
7
8 $ CFLAGS="-maix32" OBJECT_MODE=32 ./configure --enable-arch=32
9
10 $ CFLAGS="-maix64" OBJECT_MODE=64 ./configure --enable-arch=64
11
12In the configure script, AC_INIT is called before anything else and performs
13some basic compiler checks. The "-maix" gcc compiler flag must agree
14with the OBJECT_MODE environment variable recognized by the AIX linker.
15One alternative is to always set OBJECT_MODE=32. The gcc compiler
16will default to "-maix32" which allows the AC_INIT checks to succeed.
17The "--enable-arch" option can then be used to control whether code is
18generated for a 32-bit or 64-bit architecture. For example:
19
20 $ export OBJECT_MODE=32
21 $ ./configure --enable-arch=64
22
23This is the trick that is used in the RPM spec file.
24
25--
26
27MUNGE supports two different types of client authentication under AIX.
28The getpeereid() method is supported by AIX 5.2 ML4 and later. The configure
29script tests for this when "checking for getpeereid". The recvfd-mknod
30file-descriptor-passing method is supported by earlier AIX versions.
31The configure script tests for this when "checking for /dev/spx" and
32"checking for struct strrecvfd".
33
34The getpeereid() method is substantially faster; if your system supports that,
35you can stop reading now. On the other hand, the file-descriptor-passing
36method on AIX is excruciatingly slow unless special steps are taken.
37This is due to the fact that a unique STREAMS-based pipe must be created in
38the filesystem for each client authentication attempt, and the journaling
39of the jfs filesystem makes this quite slow. To increase performance,
40the authentication pipe needs to be created in a ramdisk.
41
42The following steps create a 5MB ramdisk and mount it as "/tmp/munge".
43A small ramdisk will do just fine. You should then create two directories:
44/tmp/munge/client (permissioned 1733) & /tmp/munge/server (permissioned 0711).
45These directories can be named whatever you like, but these names will be used
46in the following example.
47
48 # mkramdisk 10000
49 /dev/rramdisk0
50
51 # mkfs -V jfs /dev/ramdisk0
52 mkfs: destroy /dev/ramdisk0 (y)? y
53 Device /dev/ramdisk0:
54 Standard empty file system
55 Size: 10000 512-byte (UBSIZE) blocks
56 Initial Inodes: 1792
57
58 # mkdir /tmp/munge
59
60 # mount -V jfs -o nointegrity /dev/ramdisk0 /tmp/munge
61
62 # chmod 0755 /tmp/munge
63
64 # mkdir /tmp/munge/client
65 # chmod 1733 /tmp/munge/client
66
67 # mkdir /tmp/munge/server
68 # chmod 0711 /tmp/munge/server
69
70 # mount
71 node mounted mounted over vfs date options
72 -------- --------------- --------------- ------ ------------ ---------------
73 /dev/ramdisk0 /tmp/munge jfs Oct 01 10:01 rw,nointegrity
74
75The MUNGE_AUTH_SERVER_DIR and MUNGE_AUTH_CLIENT_DIR defines in
76src/libcommon/munge_defs.h need to be modified, and then the source
77needs to be recompiled.
78
79 #define MUNGE_AUTH_SERVER_DIR "/tmp/munge/server"
80 #define MUNGE_AUTH_CLIENT_DIR "/tmp/munge/client"
81
82Alternatively, you can override these settings with the munged
83"--auth-server-dir" and "--auth-client-dir" command-line options.
84
85 munged --auth-server-dir /tmp/munge/server \
86 --auth-client-dir /tmp/munge/client
87
88These options will be moved into the configuration file once one exists.
89
README.MULTILIB
1Multilib allows you to have both 32-bit and 64-bit versions of libmunge
2installed at the same time, capable of communicating with either a 32-bit
3or 64-bit version of munged.
4
5On Linux, at least, 32-bit libraries usually reside in /usr/lib, and
664-bit libraries usually reside in /usr/lib64. But on ia64, for example,
764-bit libraries reside in /usr/lib since everything is 64-bit there.
8
9If you are building from source, you can pass a command-line option to
10the configure script:
11
12 $ ./configure --enable-arch=32
13
14 $ ./configure --enable-arch=64
15
16If you are building RPMs, you can pass a command-line option to rpmbuild:
17
18 $ rpmbuild -ta --clean --with arch32 munge-x.y.z.tar.bz2
19
20 $ rpmbuild -ta --clean --with arch64 munge-x.y.z.tar.bz2
21
22You might also have to specify the --target command-line option:
23
24 $ rpmbuild -ta --clean --with arch32 --target i386 munge-x.y.z.tar.bz2
25
26 $ rpmbuild -ta --clean --with arch64 --target x86_64 munge-x.y.z.tar.bz2
27
28For each platform, you will have one source RPM and three binary RPMs
29(munge, munge-devel, and munge-libs).
30
31If you wanted to install both 32-bit and 64-bit MUNGE libraries on an
32RPM-based x86_64 system, for example, you would need to install either
33the 32-bit or 64-bit version of the main munge RPM (containing munged),
34and both 32-bit and 64-bit versions of the munge-devel and munge-libs RPMs:
35
36 $ rpm -ivh RPMS/x86_64/munge-0.5-1.x86_64.rpm \
37 RPMS/x86_64/munge-devel-0.5-1.x86_64.rpm \
38 RPMS/x86_64/munge-libs-0.5-1.x86_64.rpm \
39 RPMS/i386/munge-devel-0.5-1.i386.rpm \
40 RPMS/i386/munge-libs-0.5-1.i386.rpm
41
42You can then link your application against either the 32-bit or 64-bit library:
43
44 $ gcc -o foo foo.c -m32 -lmunge
45
46 $ gcc -o foo foo.c -m64 -lmunge
47
48
49AIX uses RPM 3.x which does not recognize the "--with" command-line option.
50The 'arch 32_64' define builds a single multiarch library where both 32-bit
51and 64-bit objects reside in libmunge.a. Note that the 'arch 32_64' string
52must be quoted to appear as a single command-line argument. Export the
53OBJECT_MODE variable to the environment.
54
55The OS detection in RPM 3.x appends the OS version and release to the name
56(eg, "aix5.3"). Since I didn't want to pin the spec file to a particular
57set of AIX versions, I used the generic OS string "aix". Consequently,
58you must specify "--target ppc-aix" when building the RPM, and "--ignoreos"
59when installing the RPM.
60
61 $ export OBJECT_MODE=32
62 $ rpm -ta --clean --define 'arch 32' --target ppc-aix munge-x.y.z.tar.bz2
63
64 $ export OBJECT_MODE=64
65 $ rpm -ta --clean --define 'arch 64' --target ppc-aix munge-x.y.z.tar.bz2
66
67 $ export OBJECT_MODE=32
68 $ rpm -ta --clean --define 'arch 32_64' --target ppc-aix munge-x.y.z.tar.bz2
69
70You can then link your application against either the 32-bit or 64-bit library:
71
72 $ export OBJECT_MODE=32
73 $ gcc -o foo foo.c -lmunge
74
75 $ export OBJECT_MODE=64
76 $ gcc -o foo foo.c -lmunge
77
){kind=link}
){kind=link}
){kind=link}
){kind=link}