title: pam_krb5(5)

summary: Kerberos PAM module

text:
# pam_krb5(5)

## NAME
pam_krb5 - Kerberos PAM module

## SYNOPSIS

```
  auth            sufficient      pam_krb5.so minimum_uid=1000
  session         required        pam_krb5.so minimum_uid=1000
  account         required        pam_krb5.so minimum_uid=1000
  password        sufficient      pam_krb5.so minimum_uid=1000
```

## DESCRIPTION
The Kerberos service module for PAM, typically installed at /lib/security/pam_krb5.so, provides functionality for the four PAM operations: authentication, account management, session management, and password management. pam_krb5.so is a shared object that is dynamically loaded by the PAM subsystem as necessary, based on the system PAM configuration. PAM is a system for plugging in external authentication and session management modules so that each application doesn't have to know the best way to check user authentication or create a user session on that system. For details on how to configure PAM on your system, see the PAM man page, often pam(7).

Here are the actions of this module when called from each group:

auth

Provides implementations of pam_authenticate() and pam_setcred(). The former takes the username from the PAM session, prompts for the user's password (unless configured to use an already-entered password), and then performs a Kerberos initial authentication, storing the obtained credentials (if successful) in a temporary ticket cache. The latter, depending on the flags it is called with, either takes the contents of the temporary ticket cache and writes it out to a persistent ticket cache owned by the user or uses the temporary ticket cache to refresh an existing user ticket cache. After doing the initial authentication, the Kerberos PAM module will attempt to obtain tickets for a key in the local system keytab and then verify those tickets. Unless this step is performed, the authentication is vulnerable to KDC spoofing, but it requires that the system have a local key and that the PAM module be running as a user that can read the keytab file (normally /etc/krb5.keytab. You can point the Kerberos PAM module at a different keytab with the keytab option. If that keytab cannot be read or if no keys are found in it, the default (potentially insecure) behavior is to skip this check. If you want to instead fail authentication if the obtained tickets cannot be checked, set "verify_ap_req_nofail" to true in the [libdefaults] section of /etc/krb5.conf. Note that this will affect applications other than this PAM module.

By default, whenever the user is authenticated, a basic authorization check will also be done using krb5_kuserok(). The default behavior of this function is to check the user's account for a .k5login file and, if one is present, ensure that the user's principal is listed in that file. If .k5login is not present, the default check is to ensure that the user's principal is in the default local realm and the user portion of the principal matches the account name (this can be changed by configuring a custom aname to localname mapping in krb5.conf; see the Kerberos documentation for details). This can be customized with several configuration options; see below.

If the username provided to PAM contains an "@" and Kerberos can, treating the username as a principal, map it to a local account name, pam_authenticate() will change the PAM user to that local account name. This allows users to log in with their Kerberos principal and let Kerberos do the mapping to an account. This can be disabled with the no_update_user option. Be aware, however, that this facility cannot be used with OpenSSH. OpenSSH will reject usernames that don't match local accounts before this remapping can be done and will pass an invalid password to the PAM module. Also be aware that several other common PAM modules, such as pam_securetty, expect to be able to look up the user with getpwnam() and cannot be called before pam_krb5 when using this feature.

When pam_setcred() is called to initialize a new ticket cache, the environment variable KRB5CCNAME is set to the path to that ticket cache. By default, the cache will be named /tmp/krb5cc_UID_RANDOM where UID is the user's UID and RANDOM is six randomly-chosen letters. This can be configured with the ccache and ccache_dir options.

pam-krb5 does not use the default ticket cache location or default_cc_name in the "[libdefaults]" section of krb5.conf. The default cache location would share a cache for all sessions of the same user, which causes confusing behavior when the user logs out of one of multiple sessions.

If pam_setcred() initializes a new ticket cache, it will also set up that ticket cache so that it will be deleted when the PAM session is closed. Normally, the calling program (login, sshd, etc.) will run the user's shell as a sub-process, wait for it to exit, and then close the PAM session, thereby cleaning up the user's session.

session

Provides implementations of pam_open_session(), which is equivalent to calling pam_setcred() with the PAM_ESTABLISH_CRED flag, and pam_close_session(), which destroys the ticket cache created by pam_setcred().

account

Provides an implementation of pam_acct_mgmt(). All it does is do the same authorization check as performed by the pam_authenticate() implementation described above.

password

Provides an implementation of pam_chauthtok(), which implements password changes. The user is prompted for their existing password (unless configured to use an already entered one) and the PAM module then obtains credentials for the special Kerberos principal "kadmin/changepw". It then prompts the user for a new password, twice to ensure that the user entered it properly (again, unless configured to use an already entered password), and then does a Kerberos password change. Unlike the normal Unix password module, this module will allow any user to change any other user's password if they know the old password. Also, unlike the normal Unix password module, root will always be prompted for the old password, since root has no special status in Kerberos. (To change passwords in Kerberos without knowing the old password, use kadmin(8) instead.)

Both the account and session management calls of the Kerberos PAM module will return PAM_IGNORE if called in the context of a PAM session for a user who did not authenticate with Kerberos (a return code of "ignore" in the Linux PAM configuration language).

Note that this module assumes the network is available in order to do a Kerberos authentication. If the network is not available, some Kerberos libraries have timeouts longer than the timeout imposed by the login process. This means that using this module incautiously can make it impossible to log on to console as root. For this reason, you should always use the ignore_root or minimum_uid options, list a local authentication module such as pam_unix first with a control field of "sufficient" so that the Kerberos PAM module will be skipped if local password authentication was successful.

This is not the same PAM module as the Kerberos PAM module available from Sourceforge, or the one included on Red Hat systems. It supports many of the same options, has some additional options, and doesn't support some of the options those modules do.

## CONFIGURATION
The Kerberos PAM module takes many options, not all of which are relevant to every PAM group; options that are not relevant will be silently ignored. Any of these options can be set in the PAM configuration as arguments listed after "pam_krb5.so". Some of the options can also be set in the system krb5.conf file; if this is possible, it will be noted below in the option description.

To set a boolean option in the PAM configuration file, just give the name of the option in the arguments. To set an option that takes an argument, follow the option name with an equal sign (=) and the value, with no separating whitespace. Whitespace in option arguments is not supported in the PAM configuration.

To set an option for the PAM module in the system krb5.conf file, put that option in the "[appdefaults]" section. All options must be followed by an equal sign (=) and a value, so for boolean options add "= true". The Kerberos PAM module will look for options either at the top level of the "[appdefaults]" section or in a subsection named "pam", inside or outside a section for the realm. For example, the following fragment of a krb5.conf file would set forwardable to true, minimum_uid to 1000, and set ignore_k5login only if the realm is EXAMPLE.COM.

```
    [appdefaults]
        forwardable = true
        pam = {
            minimum_uid = 1000
            EXAMPLE.COM = {
                ignore_k5login = true
            }
        }
```

For more information on the syntax of krb5.conf, see krb5.conf(5). Note that options that depend on the realm will be set only on the basis of the default realm, either as configured in krb5.conf(5) or as set by the realm option described below. If the user authenticates to an account qualified with a realm, that realm will not be used when determining which options will apply.

There is no difference to the PAM module whether options are specified at the top level or in a "pam" section; the "pam" section is supported in case there are options that should be set for the PAM module but not for other applications.

If the same option is set in krb5.conf and in the PAM configuration, the latter takes precedent. Note, however, that due to the configuration syntax, there's no way to turn off a boolean option in the PAM configuration that was turned on in krb5.conf.

The start of each option description is annotated with the version of pam-krb5 in which that option was added with the current meaning.

### Authorization
alt_auth_map=<format>

[3.12] This functions similarly to the search_k5login option. The <format> argument is used as the authentication Kerberos principal, with any %s in <format> replaced with the username. If the username contains an "@", only the part of the username before the realm is used to replace %s. If <format> contains a realm, it will be used; otherwise, the realm of the username (if any) will be appended to the result. There is no quote removal. If this option is present, the default behavior is to try this alternate principal first and then fall back to the standard behavior if it fails. The primary usage is to allow alternative principals to be used for authentication in programs like sudo. Most examples will look like:

```
    alt_auth_map=%s/root

```

which attempts authentication as the root instance of the username first and then falls back to the regular username (but see force_alt_auth and only_alt_auth).

This option also allows a cheap way to attempt authentication in an alternative realm first and then fall back to the primary realm. A setting like:

```
    alt_auth_map=%s@EXAMPLE.COM

```

will attempt authentication in the EXAMPLE.COM realm first and then fall back on the local default realm. This is more convenient than running the module multiple times with multiple default realms set with realm, but it is very limited: only two realms can be tried, and the alternate realm is always tried first.

This option can be set in "[appdefaults]" in krb5.conf, although normally it doesn't make sense to do that; normally it is used in the PAM options of configuration for specific programs. It is only applicable to the auth and account groups. If this option is set for the auth group, be sure to set it for the account group as well or account authorization may fail.

force_alt_auth

[3.12] This option is used with alt_auth_map and forces authentication as the mapped principal if that principal exists in the KDC. Only if the KDC returns principal unknown does the Kerberos PAM module fall back to normal authentication. This can be used to force authentication with an alternate instance. If alt_auth_map is not set, it has no effect. This option can be set in "[appdefaults]" in krb5.conf and is only applicable to the auth group.

ignore_k5login

[2.0] Never look for a .k5login file in the user's home directory. Instead, only check that the Kerberos principal maps to the local account name. The default check is to ensure the realm matches the local realm and the user portion of the principal matches the local account name, but this can be customized by setting up an aname to localname mapping in krb5.conf. This option can be set in "[appdefaults]" in krb5.conf and is only applicable to the auth and account groups.

ignore_root

[1.1] Do not do anything if the username is "root". The authentication and password calls will silently fail (allowing that status to be ignored via a control of "optional" or "sufficient"), and the account and session calls (including pam_setcred) will return PAM_IGNORE, telling the PAM library to proceed as if they weren't mentioned in the PAM configuration. This option is supported and will remain, but normally you want to use minimum_uid instead. This option can be set in "[appdefaults]" in krb5.conf.

minimum_uid=<uid>

[2.0] Do not do anything if the authenticated account name corresponds to a local account and that local account has a UID lower than <uid>. If both of those conditions are true, the authentication and password calls will silently fail (allowing that status to be ignored via a control of "optional" or "sufficient"), and the account and session calls (including pam_setcred) will return PAM_IGNORE, telling the PAM library to proceed as if they weren't mentioned in the PAM configuration. Using this option is highly recommended if you don't need to use Kerberos to authenticate password logins to the root account (which isn't recommended since Kerberos requires a network connection). It provides some defense in depth against user principals that happen to match a system account incorrectly authenticating as that system account.

This option can be set in "[appdefaults]" in krb5.conf.

only_alt_auth

[3.12] This option is used with alt_auth_map and forces the use of the mapped principal for authentication. It disables fallback to normal authentication in all cases and overrides search_k5login and force_alt_auth. If alt_auth_map is not set, it has no effect and the standard authentication behavior is used. This option can be set in "[appdefaults]" in krb5.conf and is only applicable to the auth group.

search_k5login

[2.0] Normally, the Kerberos implementation of pam_authenticate attempts to obtain tickets for the authenticating username in the local realm. If this option is set and the local user has a .k5login file in their home directory, the module will instead open and read that .k5login file, attempting to use the supplied password to authenticate as each principal listed there in turn. If any of those authentications succeed, the user will be successfully authenticated; otherwise, authentication will fail. This option is useful for allowing password authentication (via console or sshd without GSS-API support) to shared accounts. If there is no .k5login file, the behavior is the same as normal. Using this option requires that the user's .k5login file be readable at the time of authentication. This option can be set in "[appdefaults]" in krb5.conf and is only applicable to the auth group.

### Kerberos Behavior
anon_fast

[4.6] Attempt to use Flexible Authentication Secure Tunneling (FAST) by first authenticating as the anonymous user (WELLKNOWN/ANONYMOUS) and using its credentials as the FAST armor. This requires anonymous PKINIT be enabled for the local realm, that PKINIT be configured on the local system, and that the Kerberos library support FAST and anonymous PKINIT. FAST is a mechanism to protect Kerberos against password guessing attacks and provide other security improvements. To work, FAST requires that a ticket be obtained with a strong key to protect exchanges with potentially weaker user passwords. This option uses anonymous authentication to obtain that key and then uses it to protect the subsequent authentication.

If anonymous PKINIT is not available or fails, FAST will not be used and the authentication will proceed as normal.

To instead use an existing ticket cache for the FAST credentials, use fast_ccache instead of this option. If both fast_ccache and anon_fast are set, the ticket cache named by fast_ccache will be tried first, and the Kerberos PAM module will fall back on attempting anonymous PKINIT if that cache could not be used.

This option can be set in "[appdefaults]" in krb5.conf and is only applicable to the auth and password groups.

The operation is the same as if using the fast_ccache option, but the cache is created and destroyed automatically. If both fast_ccache and anon_fast options are used, the fast_ccache takes precedent and no anonymous authentication is done.

fast_ccache=<ccache_name>

[4.3] The same as anon_fast, but use an existing Kerberos ticket cache rather than anonymous PKINIT. This allows use of FAST with a realm that doesn't support PKINIT or doesn't support anonymous authentication. <ccache_name> should be a credential cache containing a ticket obtained using a strong key, such as the randomized key for the host principal of the local system. If <ccache_name> names a ticket cache that is readable by the authenticating process and has tickets then FAST will be attempted. The easiest way to use this option is to use a program like k5start to maintain a ticket cache using the host's keytab. This ticket cache should normally only be readable by root, so this option will not be able to protect authentications done as non-root users (such as screensavers).

If no credentials are present in the ticket cache, or if the ticket cache does not exist or is not readable, FAST will not used and authentication will proceed as normal. However, if the credentials in that ticket cache are expired, authentication will fail if the KDC supports FAST.

To use anonymous PKINIT to protect the FAST exchange, use the anon_fast option instead. anon_fast is easier to configure, since no existing ticket cache is required, but requires PKINIT be available and configured and that the local realm support anonymous authentication. If both fast_ccache and anon_fast are set, the ticket cache named by fast_ccache will be tried first, and the Kerberos PAM module will fall back on attempting anonymous PKINIT if that cache could not be used.

This option can be set in "[appdefaults]" in krb5.conf and is only applicable to the auth and password groups.

forwardable

[1.0] Obtain forwardable tickets. If set (to either true or false, although it can only be set to false in krb5.conf), this overrides the Kerberos library default set in the [libdefaults] section of krb5.conf. This option can be set in "[appdefaults]" in krb5.conf and is only applicable to the auth group.

keytab=<path>

[3.0] Specifies the keytab to use when validating the user's credentials. The default is the default system keytab (normally /etc/krb5.keytab), which is usually only readable by root. Applications not running as root that use this PAM module for authentication may wish to point it to another keytab the application can read. The first principal found in the keytab will be used as the principal for credential verification. This option can be set in "[appdefaults]" in krb5.conf and is only applicable to the auth group.

realm=<realm>

[2.2] Set the default Kerberos realm and obtain credentials in that realm, rather than in the normal default realm for this system. If this option is used, it should be set for all groups being used for consistent results. This setting will affect authorization decisions since it changes the default realm. This setting will also change the service principal used to verify the obtained credentials to be in the specified realm. If you only want to set the realm assumed for user principals without changing the realm for authorization decisions or the service principal used to verify credentials, see the user_realm option.

renew_lifetime=<lifetime>

[2.0] Obtain renewable tickets with a maximum renewable lifetime of <lifetime>. <lifetime> should be a Kerberos lifetime string such as "2d4h10m" or a time in minutes. If set, this overrides the Kerberos library default set in the [libdefaults] section of krb5.conf. This option can be set in "[appdefaults]" in krb5.conf and is only applicable to the auth group.

ticket_lifetime=<lifetime>

[3.0] Obtain tickets with a maximum lifetime of <lifetime>. <lifetime> should be a Kerberos lifetime string such as "2d4h10m" or a time in minutes. If set, this overrides the Kerberos library default set in the [libdefaults] section of krb5.conf. This option can be set in "[appdefaults]" in krb5.conf and is only applicable to the auth group.

user_realm

[4.6] Obtain credentials in the specified realm rather than in the default realm for this system. If this option is used, it should be set for all groups being used for consistent results (although the account group currently doesn't care about realm). This will not change authorization decisions. If the obtained credentials are supposed to allow access to a shell account, the user will need an appropriate .k5login file entry or the system will have to have a custom aname_to_localname mapping.

### PAM Behavior
clear_on_fail

[3.9] When changing passwords, PAM first does a preliminary check through the complete password stack, and then calls each module again to do the password change. After that preliminary check, the order of module invocation is fixed. This means that even if the Kerberos password change fails (or if one of the other password changes in the stack fails), other password PAM modules in the stack will still be called even if the failing module is marked required or requisite. When using multiple password PAM modules to synchronize passwords between multiple systems when they change, this behavior can cause unwanted differences between the environments. Setting this option provides a way to work around this behavior. If this option is set and a Kerberos password change is attempted and fails (due to network errors or password strength checking on the KDC, for example), this module will clear the stored password in the PAM stack. This will force any subsequent modules that have use_authtok set to fail so that those environments won't get out of sync with the password in Kerberos. The Kerberos PAM module will not meddle with the stored password if it skips the user due to configuration such as minimum_uid.

Unfortunately, setting this option interferes with other desirable PAM configurations, such as attempting to change the password in Kerberos first and falling back on the local Unix password database if that fails. It therefore isn't the default. Turn it on (and list pam_krb5 first after pam_cracklib if used) when synchronizing passwords between multiple environments.

This option can be set in "[appdefaults]" in krb5.conf and is only applicable to the password group.

debug

[1.0] Log more verbose trace and debugging information to syslog at LOG_DEBUG priority, including entry and exit from each of the external PAM interfaces (except pam_close_session). This option can be set in "[appdefaults]" in krb5.conf.

defer_pwchange

[3.11] By default, pam-krb5 lets the Kerberos library handle prompting for a password change if an account's password is expired during the auth group. If this fails, pam_authenticate() returns an error. According to the PAM standard, this is not the correct way to handle expired passwords. Instead, pam_authenticate() should return success without attempting a password change, and then pam_acct_mgmt() should return PAM_NEW_AUTHTOK_REQD, at which point the calling application is responsible for either rejecting the authentication or calling pam_chauthtok(). However, following the standard requires that all applications call pam_acct_mgmt() and check its return status; otherwise, expired accounts may be able to successfully authenticate. Many applications do not do this.

If this option is set, pam-krb5 uses the fully correct PAM mechanism for handling expired accounts instead of failing in pam_authenticate(). Due to the security risk of widespread broken applications, be very careful about enabling this option. It should normally only be turned on to solve a specific problem (such as using Solaris Kerberos libraries that don't support prompting for password changes during authentication), and then only for specific applications known to call pam_acct_mgmt() and check its return status properly.

This option is only supported when pam-krb5 is built with MIT Kerberos. If built against Heimdal, this option does nothing and normal expired password change handling still happens. (Heimdal is missing the required API to implement this option, at least as of version 1.6.)

This option can be set in "[appdefaults]" in krb5.conf and is only applicable to the auth group.

fail_pwchange

[4.2] By default, pam-krb5 lets the Kerberos library handle prompting for a password change if an account's password is expired during the auth group. If this option is set, expired passwords are instead treated as an authentication failure identical to an incorrect password. Also see defer_pwchange and force_pwchange. This option can be set in "[appdefaults]" in krb5.conf and is only applicable to the auth group.

force_pwchange

[3.11] If this option is set and authentication fails with a Kerberos error indicating the user's password is expired, attempt to immediately change their password during the authenticate step. Under normal circumstances, this is unnecessary. Most Kerberos libraries will do this for you, and setting this option will prompt the user twice to change their password if the first attempt (done by the Kerberos library) fails. However, some system Kerberos libraries (such as Solaris's) have password change prompting disabled in the Kerberos library; on those systems, you can set this option to simulate the normal library behavior. This option can be set in "[appdefaults]" in krb5.conf and is only applicable to the auth group.

no_update_user

[4.7] Normally, if pam-krb5 is able to canonicalize the principal to a local name using krb5_aname_to_localname() or similar calls, it changes the PAM_USER variable for this PAM session to the canonicalized local name. Setting this option disables this behavior and leaves PAM_USER set to the initial authentication identity. This option can be set in "[appdefaults]" in krb5.conf and is only applicable to the auth group.

silent

[1.0] Don't show messages and errors from Kerberos, such as warnings of expiring passwords, to the user via the prompter. This is equivalent to the behavior when the application passes in PAM_SILENT, but can be set in the PAM configuration. This option is only applicable to the auth and password groups.

trace=<log-file>

[4.6] Enables Kerberos library trace logging to the specified log file if it is supported by the Kerberos library. This is intended for temporary debugging. The specified file will be appended to without further security checks, so do not specify a file in a publicly writable directory like /tmp.

### PKINIT
pkinit_anchors=<anchors>

[3.0] When doing PKINIT authentication, use <anchors> as the client trust anchors. This is normally a reference to a file containing the trusted certificate authorities. This option is only used if try_pkinit or use_pkinit are set. This option can be set in "[appdefaults]" in krb5.conf and is only applicable to the auth and password groups.

pkinit_prompt

[3.0] Before attempting PKINIT authentication, prompt the user to insert a smart card. You may want to set this option for programs such as gnome-screensaver that call PAM as soon as the mouse is touched and don't give the user an opportunity to enter the smart card first. Any information entered at the first prompt is ignored. If try_pkinit is set, a user who wishes to use a password instead can just press Enter and then enter their password as normal. This option is only used if try_pkinit or use_pkinit are set. This option can be set in "[appdefaults]" in krb5.conf and is only applicable to the auth and password groups.

pkinit_user=<userid>

[3.0] When doing PKINIT authentication, use <userid> as the user ID. The value of this string is highly dependent on the type of PKINIT implementation you're using, but will generally be something like:

```
    PKCS11:/usr/lib/pkcs11/lib/soft-pkcs11.so

```

to specify the module to use with a smart card. It may also point to a user certificate or to other types of user IDs. See the Kerberos library documentation for more details. This option is only used if try_pkinit or use_pkinit are set.

This option can be set in "[appdefaults]" in krb5.conf and is only applicable to the auth and password groups.

preauth_opt=<option>

[3.3] Sets a preauth option (currently only applicable when built with MIT Kerberos). <option> is either a key/value pair with the key separated from the value by "=" or a boolean option (in which case it's turned on). In krb5.conf, multiple options should be separated by whitespace. In the PAM configuration, this option can be given multiple times to set multiple options. In either case, <option> may not contain whitespace. The primary use of this option, at least in the near future, will be to set options for the MIT Kerberos PKINIT support. For the full list of possible options, see the PKINIT plugin documentation. At the time of this writing, "X509_user_identity" is equivalent to pkinit_user and "X509_anchors" is equivalent to pkinit_anchors. "flag_DSA_PROTOCOL" can only be set via this option.

Any settings made with this option are applied after the pkinit_anchors and pkinit_user options, so if an equivalent setting is made via preauth_opt, it will probably override the other setting.

This option can be set in "[appdefaults]" in krb5.conf and is only applicable to the auth and password groups. Note that there is no way to remove a setting made in krb5.conf using the PAM configuration, but options set in the PAM configuration are applied after options set in krb5.conf and therefore may override earlier settings.

try_pkinit

[3.0] Attempt PKINIT authentication before trying a regular password. You will probably also need to set the pkinit_user configuration option. If PKINIT fails, the PAM module will fall back on regular password authentication. This option is currently only supported if pam-krb5 was built against Heimdal 0.8rc1 or later or MIT Kerberos 1.6.3 or later. If this option is set and pam-krb5 is built against MIT Kerberos, and PKINIT fails and the module falls back to password authentication, the user's password will not be stored in the PAM stack for subsequent modules. This is a bug in the interaction between the module and MIT Kerberos that requires some reworking of the PKINIT authentication method to fix.

This option can be set in "[appdefaults]" in krb5.conf and is only applicable to the auth and password groups.

use_pkinit

[3.0] Require PKINIT authentication. You will probably also need to set the pkinit_user configuration option. If PKINIT fails, authentication will fail. This option is currently only supported if pam-krb5 was built against Heimdal 0.8rc1 or later. MIT Kerberos doesn't provide a method to enforce use of PKINIT, so try_pkinit must be used with that implementation instead. This option can be set in "[appdefaults]" in krb5.conf and is only applicable to the auth and password groups.

### Prompting
banner=<banner>

[3.0] By default, the prompts when a user changes their password are:

```
    Current Kerberos password:
    Enter new Kerberos password:
    Retype new Kerberos password:

```

The string "Kerberos" is inserted so that users aren't confused about which password they're changing. Setting this option replaces the word "Kerberos" with whatever this option is set to. Setting this option to the empty string removes the word before "password:" entirely.

If set in the PAM configuration, <banner> may not contain whitespace. If you want a value containing whitespace, set it in krb5.conf.

This option can be set in "[appdefaults]" in krb5.conf and is only applicable to the password group.

expose_account

[3.0] By default, the Kerberos PAM module password prompt is simply "Password:". This avoids leaking any information about the system realm or account to principal conversions. If this option is set, the string "for <principal>" is added before the colon, where <principal> is the user's principal. This string is also added before the colon on prompts when changing the user's password. Enabling this option with ChallengeResponseAuthentication enabled in OpenSSH may cause problems for some ssh clients that only recognize "Password:" as a prompt. This option is automatically disabled if search_k5login is enabled since the principal displayed would be inaccurate.

This option can be set in "[appdefaults]" in krb5.conf and is only applicable to the auth and password groups.

force_first_pass

[4.0] Use the password obtained by a previous authentication or password module to authenticate the user without prompting the user again. If no previous module obtained the user's password, fail without prompting the user. Also see try_first_pass and use_first_pass for weaker versions of this option. This option is only applicable to the auth and password groups. For the password group, it applies only to the old password. See use_authtok for a similar setting for the new password.

no_prompt

[4.6] Never prompt for the current password. Instead, pass in a NULL password to the Kerberos library and let the Kerberos library do the prompting. This may be needed if, for example, the Kerberos library is configured to use other authentication mechanisms than passwords and needs full control over the prompting process. The major disadvantage of this option is that it means the PAM module will never see the user's password and therefore cannot save it in the PAM module data for any subsequent modules. In other words, this option cannot be used if another module is in the stack behind the Kerberos PAM module and wants to use use_first_pass. The Kerberos library also usually includes the principal in the prompt, and therefore this option implies behavior similar to expose_account. Similar to expose_account, this can cause problems with OpenSSH if ChallengeResponseAuthentication is enabled, since clients may not recognize password prompts other than "Password:".

Using this option with search_k5login would result in a password prompt for every principal listed in the user's .k5login file. This is probably not desired behavior, although it's not prohibited by the module.

This option is only applicable to the auth and password groups. For the password group, it applies only to the authentication process; the user will still be prompted for a new password.

prompt_principal

[3.6] Before prompting for the user's password (or using the previously entered password, if try_first_pass, use_first_pass, or force_first_pass are set), prompt the user for the Kerberos principal to use for authentication. This allows the user to authenticate with a different principal than the one corresponding to the local username, provided that either a .k5login file or local Kerberos principal to account mapping authorize that principal to access the local account. Be cautious when using this configuration option and don't use it with OpenSSH PasswordAuthentication, only ChallengeResponseAuthentication. Some PAM-enabled applications expect PAM modules to only prompt for passwords and may even blindly give the password to the first prompt, no matter what it is. Such applications, in combination with this option, may expose the user's password in log messages and Kerberos requests.

try_first_pass

[1.0] If the authentication module isn't the first on the stack, and a previous module obtained the user's password, use that password to authenticate the user without prompting them again. If that authentication fails, fall back on prompting the user for their password. This option has no effect if the authentication module is first in the stack or if no previous module obtained the user's password. Also see use_first_pass and force_first_pass for stronger versions of this option. This option is only applicable to the auth and password groups. For the password group, it applies only to the old password.

use_authtok

[4.0] Use the new password obtained by a previous password module when changing passwords rather than prompting for the new password. If the new password isn't available, fail. This can be used to require passwords be checked by another, prior module, such as pam_cracklib. This option is only applicable to the password group.

use_first_pass

[1.0] Use the password obtained by a previous authentication module to authenticate the user without prompting the user again. If no previous module obtained the user's password for either an authentication or password change, fall back on prompting the user. If a previous module did obtain the user's password but authentication with that password fails, fail without further prompting the user. Also see try_first_pass and force_first_pass for other versions of this option. This option is only applicable to the auth and password groups. For the password group, it applies only to the old password. See use_authtok for a similar setting for the new password.

### Ticket Caches
ccache=<pattern>

[2.0] Use <pattern> as the pattern for creating credential cache names. <pattern> must be in the form <type>:<residual> where <type> and the following colon are optional if a file cache should be used. The special token %u, anywhere in <pattern>, is replaced with the user's numeric UID. The special token %p, anywhere in <pattern>, is replaced with the current process ID. If <pattern> ends in the literal string "XXXXXX" (six X's), that string will be replaced by randomly generated characters and the ticket cache will be created using mkstemp(3). This is strongly recommended if <pattern> points to a world-writable directory.

This option can be set in "[appdefaults]" in krb5.conf and is only applicable to the auth and session groups.

ccache_dir=<directory>

[1.2] Store both the temporary ticket cache used during authentication and user ticket caches in <directory> instead of in /tmp. The algorithm for generating the ticket cache name is otherwise unchanged. <directory> may be prefixed with "FILE:" to make the cache type unambiguous (and this may be required on systems that use a cache type other than file as the default). Be aware that pam_krb5 creates and stores a temporary ticket cache file owned by root during the login process. If you set ccache above to avoid using the system /tmp directory for user ticket caches, you may also want to set ccache_dir to move those temporary caches to some other location. This will allow pam_krb5 to continue working even if the system /tmp directory is full.

This option can be set in "[appdefaults]" in krb5.conf and is only applicable to the auth and session groups.

no_ccache

[1.0] Do not create a ticket cache after authentication. This option shouldn't be set in general, but is useful as part of the PAM configuration for a particular service that uses PAM for authentication but isn't creating user sessions and doesn't want the overhead of ever writing the user credentials to disk. When using this option, the application should only call pam_authenticate(); other functions like pam_setcred(), pam_start_session(), and pam_acct_mgmt() don't make sense with this option. Don't use this option if the application needs PAM account and session management calls. This option is only applicable to the auth group.

retain_after_close

[2.3] Normally, the user's ticket cache is destroyed when either pam_end() or pam_close_session() is called by the authenticating application so that ticket caches aren't left behind after the user logs out. In some cases, however, this isn't desirable. (On Solaris 8, for instance, the default behavior means login will destroy the ticket cache before running the user's shell.) If this option is set, the PAM module will never destroy the user's ticket cache. If you set this, you may want to call kdestroy in the shell's logout configuration or run a temporary file removal program to avoid accumulating hundreds of ticket caches in /tmp. This option can be set in "[appdefaults]" in krb5.conf and is only applicable to the auth and session groups.

## ENVIRONMENT
KRB5CCNAME

Set by pam_setcred() with the PAM_ESTABLISH_CRED option, and therefore also by pam_open_session(), to point to the new credential cache for the user. See the ccache and ccache_dir options. By default, the cache name will be prefixed with "FILE:" to make the cache type unambiguous.

PAM_KRB5CCNAME

Set by pam_authenticate() to point to the temporary ticket cache used for authentication (unless the no_ccache option was given). pam_setcred() then uses that environment variable to locate the temporary cache even if it was not called in the same PAM session as pam_authenticate() (a problem with sshd running in some modes). This environment variable is only used internal to the PAM module.

## FILES
/tmp/krb5cc_UID_RANDOM

The default credential cache name. UID is the decimal UID of the local user and RANDOM is a random six-character string. The pattern may be changed with the ccache option and the directory with the ccache_dir option.

/tmp/krb5cc_pam_RANDOM

The credential cache name used for the temporary credential cache created by pam_authenticate(). This cache is removed again when the PAM session is ended or when pam_setcred() is called and will normally not be user-visible. RANDOM is a random six-character string.

~/.k5login

File containing Kerberos principals that are allowed access to that account.

## BUGS
If try_pkinit is set and pam-krb5 is built with MIT Kerberos, the user's password is not saved in the PAM data if PKINIT fails and the module falls back to password authentication.

## CAVEATS
Be sure to list this module in the session group as well as the auth group when using it for interactive logins. Otherwise, some applications (such as OpenSSH) will not set up the user's ticket cache correctly.

The Kerberos library, via pam-krb5, will prompt the user to change their password if their password is expired, but when using OpenSSH, this will only work when ChallengeResponseAuthentication is enabled. Unless this option is enabled, OpenSSH doesn't pass PAM messages to the user and can only respond to a simple password prompt.

If you are using MIT Kerberos, be aware that users whose passwords are expired will not be prompted to change their password unless the KDC configuration for your realm in [realms] in krb5.conf contains a master_kdc setting or, if using DNS SRV records, you have a DNS entry for _kerberos-master as well as _kerberos.

pam_authenticate() returns failure when called for an ignored account, requiring the system administrator to use "optional" or "sufficient" to ignore the module and move on to the next module. It's arguably more correct to return PAM_IGNORE, which causes the module to be ignored as if it weren't in the configuration, but this increases the risk of inadvertent security holes when listing pam-krb5 as the only authentication module.

This module treats the empty password as an authentication failure rather than attempting to use that password to avoid unwanted prompting behavior in the Kerberos libraries. If you have a Kerberos principal that intentionally has an empty password, it won't work with this module.

This module will not refresh an existing ticket cache if called with an effective UID or GID different than the real UID or GID, since refreshing an existing ticket cache requires trusting the KRB5CCNAME environment variable and the environment should not be trusted in a setuid context.

Old versions of OpenSSH are known to call pam_authenticate followed by pam_setcred(PAM_REINITIALIZE_CRED) without first calling pam_open_session, thereby requesting that an existing ticket cache be renewed (similar to what a screensaver would want) rather than requesting a new ticket cache be created. Since this behavior is indistinguishable at the PAM level from a screensaver, pam-krb5 when used with these old versions of OpenSSH will refresh the ticket cache of the OpenSSH daemon rather than setting up a new ticket cache for the user. The resulting ticket cache will have the correct permissions, but will not be named correctly or referenced in the user's environment and will be overwritten by the next user login. The best solution to this problem is to upgrade OpenSSH. I'm not sure exactly when this problem was fixed, but at the very least OpenSSH 4.3 and later do not exhibit it.

## AUTHOR
pam-krb5 was originally written by Frank Cusack. Andres Salomon made extensive modifications, and then Russ Allbery <eagle@eyrie.org> adopted it and made even more extensive modifications. Russ Allbery currently maintains the module.

## COPYRIGHT AND LICENSE
Copyright 2005, 2006, 2007, 2008, 2009, 2010, 2014 Russ Allbery <eagle@eyrie.org>

Copyright 2008, 2009, 2010, 2011, 2012, 2013, 2014 The Board of Trustees of the Leland Stanford Junior University

Copying and distribution of this file, with or without modification, are permitted in any medium without royalty provided the copyright notice and this notice are preserved. This file is offered as-is, without any warranty.

## SEE ALSO
kadmin(8), kdestroy(1), krb5.conf(5), pam(7), passwd(1), syslog(3)

The current version of this module is available from its web page at <https://www.eyrie.org/~eagle/software/pam-krb5/>.


title: pam_mount.conf(5)

text:
# pam_mount.conf(5)

## Name
pam_mount.conf - Description of the pam_mount configuration file

## Overview
The pam_mount configuration file defines soft defaults for commands pam_mount will be executing, the messages it will show, and which volumes to mount on login. Since pam_mount 0.18, the configuration file is written in XML so as to simplify the pam_mount code base while giving formatting freedom to the end-user. Special characters like <, > and & that are used by XML itself must be encoded as <, > and &, respectively; additionally, " must be encoded as " within a "" area, but these three/four symbols are unlikely to be seen often anyway.

Do not use comments inside elements taking verbatim text, like <fusermount></fusermount> - this is not handled by the pam_mount XML tree parser.

## Volume definitions
Volumes are defined with the <volume> element, which primarily takes the parameters as attributes, such as

<volume user="joe" fstype="nfs" server="fsbox" path="/home/%(USER)" mountpoint="/bigdisk/%(USER)" />

and define to mount what for whom and how. There are a lot of tunables, which are described in this section.

### Simple user control
The following attributes control whether the volume is going to get mounted once the user logs in. By default, volumes apply to all users, and specifying attributes limits it to the given conditions, i.e. they are logically ANDed. There is a more powerful and verbose mechanism for specifying complex conditions, described further below in the section "Extended user control".

user="username"

Limit the volume to the specified user, identified by name

uid="number" or uid="number-number"

Limit the volume to the specified user(s), identified by UID or UID range.

pgrp="groupname"

Limit the volume to users which have the group identified by name as their primary group.

gid="number" or gid="number-number"

Limit the volume to users which have the group(s) given by GID or GID range as a primary group.

sgrp="groupname"

Limit the volume to users which are a member of the group identified by name (either as primary or secondary group).

### Volume configuration
The following attributes select volume source, destination, options and so on.

fstype="type"

The filesystem type, which can be anything your kernel, userspace and pam_mount understand. If the fstype specifies a pam_mount-special type, pam_mount will handle it. Otherwise, the fstype is passed to mount(8) which then in turn looks for a userspace helper /sbin/mount.fstype and runs that if it exists, and in any other case, mount(8) would call mount(2) to cause the kernel to directly mount it. mount(8) knows of an auto fstype, which might be helpful in some cases. Not specifying the fstype attribute implies fstype="auto". Note that mounting with auto may fail if the filesystem kernel module is not loaded yet, since mount(8) will check /proc/partitions.

The fstypes cifs, smbfs, ncpfs, fuse, nfs and nfs4 are overridden by pam_mount and we run the respective helper programs directly instead of invoking mount(8) with the basic default set of arguments which are often insufficient for networked filesystems. See this manpage's section "Examples" below for more details.

noroot="1"

Call the mount program without root privileges. It defaults to yes for the fuse fstype, because FUSE volumes must be mounted as the user that logs in to get access to the files by default.

server="name"

Defines the server to which to connect in case of cifs, smbfs and ncpfs and nfs fstypes. For all other fs types, this attribute is ignored. You can also specify the server in the path attribute instead, but need to adhere to the specific syntax that is a particular fstype requires. (E.g. CIFS uses "//server/path", whereas NFS uses "server:path", etc.)

path="path"

This mandatory attribute specifies the location of the volume, relative to the server (if specified).

mountpoint="directory"

This specifies the destination directory onto which the volume is mounted. "~" expands to the user's home directory as present in the passwd database, according to sh semantics. "~name" is not supported. If this attribute is omitted, the location is read from /etc/fstab, which also requires path to be a device or a source directory of an fstab entry.

options="..."

Specifies the mount options. If omitted and /etc/fstab is used (see mountpoint), the options will also be sources from fstab.

ssh="0" or ssh="1"

The ssh option enables an input hack wrapper (zerossh, see fd0ssh(1)) for this volume to hand the password to ssh over an ssh-specific mechanism. Enable this option for any mount involving the SSH binary, e.g. ccgfs or sshfs. Do not enable it for anything else or the login will most likely hang.

cipher="cipher"

Cryptsetup cipher name for the volume. To be used with the crypt fstype.

fskeycipher="ciphertype"

OpenSSL cipher name for the fskey. Use with the crypt fstype (dm-crypt and LUKS). The special cipher keyword "none" may be used to directly pass the file's contents to cryptsetup without decryption by OpenSSL.

fskeyhash="hash"

OpenSSL hash name for the fskey.

fskeypath="path"

Path to the filesystem key.

## Variables
Within attributes and commands (see later section), specific placeholders or variables, identified by %(name) may be used. These are substituted at command invocation time.

%(USER)

Expands to the username of the user logging in.

%(DOMAIN_NAME), %(DOMAIN_USER)

Winbind has special UNIX usernames in the form of "domain\username", and %(DOMAIN_NAME) and %(DOMAIN_USER) provide the split parts of it. This is useful when a sharename on an MSAD server is the same as the username, e.g. <volume fstype="cifs" server="fsbox" path="%(DOMAIN_USER)" />.

%(USERUID), %(USERGID)

The numeric UID and GID of the primary group of the user logging in. This is obtained via getpw*(), not getuid(). It is useful in conjunction with the uid= or gid= mount options, e.g. <volume options="uid=%(USERUID)" />. Note that you do not need to specify uid=%(USERUID) for smbfs or cifs mounts because this is already done automatically by pam_mount.

%(GROUP)

The name of the group for %(USERGID).

All other variables you might find in the source code are internal to pam_mount, and are likely not to be expanded when you would expect it.

## pam_mount parameters
Besides volumes, there are other elements allowed in pam_mount.conf.xml that control pam_mount's own behavior.

### General tunables
<debug enable="1" />

Enables verbose output during login to stderr and syslog. Some programs do not cope with output sent on stderr, see doc/bugs.txt for a list. 0 disables debugging, 1 enables pam_mount tracing, and 2 additionally enables tracing in mount.crypt. The default is 0. As the config file is parsed linearly, the <debug> directive takes effect once it is seen - it it thus advised to put it near the start of the file, before any <volume> definitions.

<logout wait="microseconds" hup="yes/no" term="yes/no" kill="yes/no" />

Programs exist that do not terminate when the session is closed. (This applies to the "final" close, i.e. when the last user session ends.) Examples are processes still running in the background; or a broken X session manager that did not clean up its children, or other X programs that did not react to the X server termination notification. pam_mount can be configured to kill these processes and optionally wait before sending signals.

<luserconf name=".pam_mount.conf.xml" />

Individual users may define additional volumes in a file by the specified name relative to their home directory. The presence of <luserconf> in the master config file enables this feature. If turned on, users may mount and unmount any volumes they specify and that they have ownership of (in case of local mounts). The mount process is executed as superuser. This may have security implications, so this feature is disabled by default. Luserconfigs are parsed after any volumes from the global configuration file have been mounted, so that first mounting home directories with a global config and then mounting further volumes from luserconfigs is possible.

<mntoptions allow="options,..." />

The <mntoptions> elements determine which options may be specified in <volumes> in per-user configuration files (see <luserconf>). It does not apply to the master file. Specifying <mntoptions> is forbidden and ignored in per-user configs. The default allowed list consists of "nosuid,nodev", and this default is cleared when the first allow="..." attribute is seen by the config parser. All further allow="..." are additive, though.

<mntoptions deny="options,..." />

Any options listed in deny may not appear in the option list of per-user mounts. The default deny list is empty.

<mntoptions require="options,..." />

All options listed in require must appear in the option list of per-user mounts. The default require list consists of "nosuid,nodev", and like allow="", is cleared when first encountered by the parser, and is otherwise additive.

<path>directories...</path>

The default for the PATH environmental variable is not consistent across distributions, and so, pam_mount provides its own set of sane defaults which you may change at will.

### Volume-related
<mkmountpoint enable="1" remove="true" />

Controls automatic creation and removal of mountpoints. If a mountpoint does not exist when the volume is about to be mounted, pam_mount can be instructed to create one using the enable attribute. Normally, directories created this way are retained after logout, but remove may be set to true to remove the mountpoint again, but only if it was automatically created by pam_mount in the same session before.

### Auxiliary programs
Some mount programs need special default parameters to properly function. It is good practice to specify uid= for CIFS for example, because it is mounted as root and would otherwise show files belonging to root instead of the user logging in.

<fd0ssh>program...</fd0ssh>

fd0ssh is a hack around OpenSSH that essentially makes it read passwords from stdin even though OpenSSH normally does not do that.

<fsck>fsck -p %(FSCKTARGET)</fsck>

Local volumes will be checked before mounting if this program is set.

<ofl>ofl -k%(SIGNAL) %(MNTPT)</ofl>

The Open File Lister is used to identify processes using files within the given subdirectory, and optionally send a signal to those processes.

<pmvarrun>pmvarrun ...</pmvarrun>

pmvarrun(8) is a separate program to manage the reference count tracking user sessions.

### Mount programs
Commands to mount/unmount volumes. They can take parameters, as shown. You can specify either absolute paths, or relative ones, in which case $PATH will be searched. Since login programs have differing default PATHs, pam_mount has its own path definition (see above).

<lclmount>mount -t %(FSTYPE) ...</lclmount>

The regular mount program.

<umount>umount %(MNTPT)</umount>

Unless there is a dedicated umount program for a given filesystem type, the regular umount program will be used.

Linux supports lazy unmounting using `/sbin/umount -l`. This may be dangerous for encrypted volumes because the underlying device is not unmapped. Loopback devices are also affected by this (not being unmapped when files are still open). Also, unmount on SMB volumes needs to be called on %(MNTPT) and not %(VOLUME).

Commands for various mount programs. Not all have a dedicated umount helper because some do not need one.

<cifsmount>mount.cifs ...</cifsmount>

<cryptmount>mount.crypt ...</cryptmount>

<cryptumount>umount.crypt %(MNTPT)</cryptumount>

Mount helpers for dm-crypt and LUKS volumes.

<fusemount>mount.fuse ...</fusemount>

<fuseumount>fuserumount ...</fuseumount>

<ncpmount>ncpmount ...</ncpmount>

<ncpumount>ncpumount ...</ncpumount>

<nfsmount>mount %(SERVER):%(VOLUME) ...</nfsmount>

<smbmount>smbmount ...</smbmount>

<smbumount>smbumount ...</smbumount>

### Messages
<msg-authpw>pam_mount password:</msg-authpw>

When pam_mount cannot obtain a password through PAM, or is configured to not do so in the first place, and is configured to ask for a password interactively as a replacement, this prompt will be shown.

<msg-sessionpw>reenter...:</msg-sessionpw>

In case the 'session' PAM block does not have the password (e.g. on su from root to user), it will ask again. This prompt can also be customized.

## Extended user control
Sometimes, the simple user control attributes for the <volume> element are not sufficient where one may want to build more complex expressions as to whom a volume applies. Instead of attributes, extended user control is set up using additional elements within <volume>, for example

<volume path="/dev/shm" mountpoint="~"> <and> <sgrp>students</sgrp> <not> <sgrp>profs</sgrp> </not> </and> </volume>

Which translates to (students && !profs).

### Logical operators
<and><elements>*</and>

All elements within this one are logically ANDed. Any number of elements may appear.

<or><elements>*</or>

All elements within this one are logically ORed. Any number of elements may appear.

<xor><elements>{2}</xor>

The two elements within the <xor> are logically XORed.

<not><element></not>

The single element within the <not> is logically negated.

### User selection
<user>username</user>

Match against the given username.

<uid>number</uid> or <uid>number-number</uid>

Match the UID of the user logging in against a UID or UID range.

<gid>number</gid> or <gid>number-number</gid>

Match the primary group of the user logging in against a GID or GID range.

<pgrp>groupname</pgrp>

Check if the user logging in has groupname as the primary group.

<sgrp>groupname</sgrp>

Check if the user logging in is a member of the group given by name (i.e. it is either a primary or secondary group).

### Attributes
icase="yes" or icase="no"

The icase attribute may be used on <user>, <pgrp> and <sgrp> to enable case-insensitive matching (or not). It defaults to "no".

regex="yes" (or no)

The regex attribute may be used on <user>, <pgrp> and <sgrp> to enable interpreting the text content of the tag as a Perl-compatible regular expression pattern. This attribute may be combined with "icase" (see above). Example: <user regex="yes">joe</user> matches any user who has the letter sequence "joe" anywhere in their username. Therefore, use the regex feature cautiously and consider adding ^ and $ anchors to limit security surprises. Example: <user regex="yes">^.*joe.*$</user> if you really wanted to match the sequence at any position.

## Examples
Remember that ~ can be used in the mountpoint attribute to denote the home directory as retrievable through getpwent(3).

### sshfs and ccgfs
Not specifying any path after the colon (:) uses the path wherever ssh will put you in, usually the home directory. With fd0ssh (package hxtools) installed:

<volume fstype="fuse" path="sshfs#%(USER)@fileserver:" mountpoint="~" ssh="1" />

Without fd0ssh:

<volume fstype="fuse" path="sshfs#%(USER)@fileserver:" mountpoint="~" options="nosuid,nodev,noatime,reconnect,nonempty,allow_other,default_permissions,password_stdin" ssh="0" noroot="0" />

<volume fstype="fuse" path="ccgfs-ssh-pull#%(USER)@host:directory" mountpoint="~" />

Note that sshfs's "password_stdin" option tries to locate a string "assword" on ssh's output, while fd0ssh is rather using the "askpass" API, which might also work with passphrase-protected SSH keys whose prompt is quite different.

### encfs 1.4.x and up
<volume fstype="fuse" path="encfs#/crypto/%(USER)" mountpoint="~" options="nonempty" />

(encfs 1.3 is no longer supported.)

### NFS mounts
<volume fstype="nfs" server="fileserver" path="/home/%(USER)" mountpoint="~" />

### CIFS/SMB mounts
<volume user="user" fstype="smbfs" server="krueger" path="public" mountpoint="/home/user/krueger" />

### NCP mounts
<volume user="user" fstype="ncpfs" server="krueger" path="public" mountpoint="/home/user/krueger" options="username=user.context" />

### Bind mounts
This may come useful in conjunction with pam_chroot:

<volume path="/bin" mountpoint="~/bin" options="bind" />

### tmpfs mounts
Volatile tmpfs mount with restricted size (thanks to Mike Hommey for this example):

<volume user="test" fstype="tmpfs" mountpoint="/home/test" options="size=10M,uid=%(USER),mode=0700" />

### dm-crypt volumes
Crypt mounts require a kernel with CONFIG_BLK_DEV_DM and CONFIG_DM_CRYPT enabled, as well as all the ciphers that are going to be used, e.g. CONFIG_CRYPTO_AES, CONFIG_CRYPTO_BLOWFISH, CONFIG_CRYPTO_TWOFISH.

<volume path="/home/%(USER).img" mountpoint="~" cipher="aes-cbc-essiv:sha256" fskeycipher="aes-256-cbc" fskeyhash="sha1" fskeypath="/home/%(USER).key" />

### LUKS volumes
<volume path="/home/%(USER).img" mountpoint="~" cipher="aes-cbc-essiv:sha256" />

### cryptoloop volumes
cryptoloop is not explicitly supported by pam_mount. Citing the Linux kernel config help text: "WARNING: This device [cryptoloop] is not safe for journal[l]ed filesystems[...]. Please use the Device Mapper [dm-crypt] module instead."

### OpenBSD encrypted home
OpenBSD encrypted home directory example:

<volume path="/home/user.img" mountpoint="/home/user" options="svnd0" />


LOGARCHIVE

package: pcp-doc

title: LOGARCHIVE(5)

summary: Performance Co-Pilot archive formats

text:
# LOGARCHIVE(5)

## NAME
LOGARCHIVE - Performance Co-Pilot archive formats

## DESCRIPTION
Performance Co-Pilot (PCP) archives store historical values about arbitrary metrics recorded from a single host. Archives are machine independent and self-contained - all metric data and metadata required for off-line or off-site analysis is held within an archive.

The format is stable in order to allow long-term historical storage and processing by PMAPI(3) client tools. However some format variants are supported over time, and currently Versions 2 and 3 are supported. The mandate is that PCP will provide long-term backwards compatibility, so an archive created on any version of PCP can be read on that version of PCP and all subsequent versions of PCP. The exception is Version 1 that was retired in the PCP Version 2.0 release in May 1998.

Archives may be read by most PCP client tools, using the -a/--archive NAME option, or dumped raw by pmdumplog(1). Archives are created primarily by pmlogger(1), however they can also be created using the LOGIMPORT(3) programming interface.

Archives may be merged, analyzed, modified and subsampled using pmlogreduce(1), pmlogsummary(1), pmlogrewrite(1) and pmlogextract(1). In addition, PCP archives may be examined in sets or grouped together into ``archive folios'', which are created and managed by the mkaf(1) and pmafm(1) tools.

An archive consists of several physical files that share a common arbitrary prefix, e.g. myarchive.

myarchive.0, myarchive.1, ...

One or more data volumes containing the metric values and any error codes encountered during metric sampling. Typically the largest of the files and may grow very rapidly, depending on the selection of metrics to be logged by pmlogger(1) and the sampling intervals being used.

myarchive.meta

Information for PMAPI functions such as pmLookupName(3), pmLookupDesc(3), pmLookupLabels(3) and pmLookupInDom(3). The metadata file may grow sporadically as logged metrics, instance domains and labels vary over time.

myarchive.index

A temporal index, mapping timestamps to byte offsets in the other files.

## COMMON FEATURES
All three types of files have a similar record-based structure, a convention of network byte-order (big-endian) encoding, and 32-bit fields for tagging/padding for those records. Strings are stored as 8-bit characters without assuming a specific encoding, so normally ASCII. See also the __pmLog* types in src/include/pcopilot/libpcopilot.h.

### RECORD FRAMING
The volume and .meta files are divided into self-identifying records.

Offset

Length

Name

0

4

N, length of record, in bytes, including this field

4

N-8

record payload, usually starting with a 32-bit record type tag

N-4

4

N, length of record (again)

### ARCHIVE LABEL
All three types of files begin with an ``archive label'' header, which identifies the host name, starting timestamp and timezone information; all referring to the host that was the source of the performance data (which may be different to the host where pmlogger(1) was running).

The ``archive label'' format differs between Version 2 and Version 3, with the latter providing enhanced timestamps (64-bit encoding of the seconds part and nanosecond precision) and some additional fields.

Version 2

Offset

Length

Name

0

4

tag, PM_LOG_MAGIC | PM_LOG_VERS02=0x50052602

4

4

process id (PID) of pmlogger process that wrote file

8

4

archive start time, seconds part (past UNIX epoch)

12

4

archive start time, microseconds part

16

4

current archive volume number (or -1=.meta, -2=.index)

20

64

name of collection host

80

40

time zone string for collection host ($TZ environment variable)

Version 3

Offset

Length

Name

0

4

tag, PM_LOG_MAGIC | PM_LOG_VERS03=0x50052603

4

4

PID of pmlogger process that wrote file

8

8

archive start time, seconds part (past UNIX epoch)

16

4

archive start time, nanoseconds part

20

4

current archive volume number (or -1=.meta, -2=.index)

24

4

archive feature bits

28

4

reserved for future use

32

256

name of collection host

288

256

timezone string for collection host ($TZ environment variable), e.g. AEDT-11

544

256

timezone zoneinfo string for collection host, e.g. :Australia/Melbourne

The ``archive feature bits'' are intended to encode possible future extensions or differences to the on-disk structure or the the archive semantics. At this stage there are no such features, but if they are introduced at some point in the future, there will be associated PM_LOG_FEATURE_XXX macros added to the <pcp/pmapi.h> header file.

All fields, except for the ``current archive volume number'', match for all files in a single PCP archive.

## ARCHIVE VOLUME (.0, .1, ...) RECORDS

### pmResult
After the archive label record, an archive volume file contains one or more records, each providing metric values corresponding to the pmResult from one pmFetch(3) operation. The record size may vary according to number of metrics being fetched and the number of instances in the associated instance domains.

For Version 2 the file size is limited to 2GiB, due to storage of 32-bit byte offsets within the temporal index. For Version 3 the file size is limited to 8191PiB, due to storage of 62-bit byte offsets within the temporal index.

The pmResult format differs between Version 2 and Version 3, with the latter providing enhanced timestamps (64-bit encoding of the seconds part and nanosecond precision).

Version 2

Offset

Length

Name

0

4

timestamp, seconds part (past UNIX epoch)

4

4

timestamp, microseconds part

8

4

number of metrics with data following

12

M

pmValueSet #0

12+M

N

pmValueSet #1

12+M+N

...

...

NOP

X

pmValueBlock #0

NOP+X

Y

pmValueBlock #1

NOP+X+Y

...

...

Version 3

Offset

Length

Name

0

8

timestamp, seconds part (past UNIX epoch)

8

4

timestamp, nanoseconds part

12

4

number of metrics with data following

16

M

pmValueSet #0

16+M

N

pmValueSet #1

16+M+N

...

...

NOP

X

pmValueBlock #0

NOP+X

Y

pmValueBlock #1

NOP+X+Y

...

...

Records with a ``number of metrics'' equal to zero are ``mark records'', and represent interruptions, missing data, or time discontinuities in logging.

### pmValueSet
This subrecord represents the values for one metric at one point in time.

Offset

Length

Name

0

4

Performance Metrics Identifier (PMID)

4

4

number of values

8

4

value format, PM_VAL_INSITU=0 or PM_VAL_DPTR=1

12

M

pmValue #0

12+M

N

pmValue #1

12+M+N

...

...

The metadata describing metrics is found in the .meta file where the entries are not timestamped, as the metadata is assumed to be unchanging throughout an archive.

### pmValue
This subrecord represents one value for one instance of a metric at one point in time. It is a variant type, depending on the parent pmValueSet's value format field. This allows small numbers to be encoded compactly, but retain flexibility for larger or variable length data to be stored later in the pmResult record in a pmValueBlock subrecord.

Offset

Length

Name

0

4

internal instance identifier (or PM_IN_NULL=-1 for singular metrics)

4

4

value (INSITU) or

offset in pmResult to our pmValueBlock (DPTR)

The metadata describing the instance domain for metrics is found in the .meta file. Since the numeric mappings may change during the lifetime of the logging session, it is important to match up the timestamp of the measurement record with the corresponding instance domain record. That is, the instance domain corresponding to a measurement at time T is the instance domain observation for the metric's instance domain with largest timestamp T' <= T.

### pmValueBlock
Instances of this subrecord are placed at the end of the pmValueSet, after all the pmValue subrecords. If (and only if) needed, they are padded at the end to the next 32-bit boundary.

Offset

Length

Name

0

1

value type (same as pmDesc.type)

1

3

4 + N, the length of the subrecord

4

N

bytes that make up the raw value

4+N

0-3

padding (not included in the 4+N length field)

Note that for PM_TYPE_STRING, the length includes an explicit NULL terminator byte. For PM_TYPE_EVENT, the value byte string is further structured. Refer to PMDAEVENTARRAY(3) for more information about how arrays of event records are packed inside a pmResult container.

## METADATA FILE (.meta) RECORDS
After the archive label record, the metadata file contains interleaved metric description records, timestamped instance domain records, timestamped label records (for context, instance domain and metric labels) and (help) text records. Unlike the data volumes, these records are not forced to 32-bit alignment.

For Version 2 the file size is limited to 2GiB, due to storage of 32-bit byte offsets within the temporal index. For Version 3 the file size is limited to 8191PiB, due to storage of 62-bit byte offsets within the temporal index.

See also libpcopilot/src/logmeta.c.

### Metric Descriptions
Instances of this (pmDesc) record provide the description or metadata for each metric appearing in the PCP archive. This metadata includes the metric's PMID, data type, data semantics, instance domain identifier (or PM_INDOM_NULL for singular metrics with only one value) and a set of (1 or more) names.

Offset

Length

Name

0

4

tag, TYPE_DESC=1

4

4

PMID

8

4

data type (PM_TYPE_*)

12

4

instance domain identifier

16

4

metric semantics (PM_SEM_*)

20

4

units: bit-packed pmUnits

4

4

number of alternative names for this PMID

28

4

N: number of bytes in this name

32

N

bytes of the name, no NULL terminator nor padding

32+N

4

N2: number of bytes in next name

36+N

N2

bytes of the name, no NULL terminator nor padding

...

...

...

### Instance Domains
A set-valued metric is defined over an instance domain, which consists of an instance domain identifier (will have already been mentioned in a prior pmDesc record), a count of the number of instances and a map that defines the association between internal instance identifiers (integers) and external instance names (strings).

Because instance domains can change over time, the instance domain also requires a timestamp, and the same instance domain can occur multiple times within the .meta file. The timestamps are used to search for the temporally correct instance domain when decoding pmResult records from the archive data volumes, or answering metadata queries against the instance domain.

The instance domain format differs markedly between Version 2 and Version 3. Version 3 provides enhanced timestamps (64-bit encoding of the seconds part and nanosecond precision) and introduces a new ``delta'' instance domain format that encodes differences between the previous observation of the instance domain and the current state of the instance domain.

Full Instance Domain - Version 2

Offset

Length

Name

0

4

tag, TYPE_INDOM_V2=2

4

4

timestamp, seconds part (past UNIX epoch)

8

4

timestamp, microseconds part

12

4

instance domain number

16

4

N: number of instances in domain, normally >0

20

4

first instance number

24

4

second instance number (if appropriate)

...

...

...

20+4*N

4

first offset into string table (see below)

20+4*N+4

4

second offset into string table (etc.)

...

...

...

20+8*N

M

base of string table, containing

packed, NULL-terminated instance names

Full Instance Domain - Version 3

Offset

Length

Name

0

4

tag, TYPE_INDOM=5

4

8

timestamp, seconds part (past UNIX epoch)

12

4

timestamp, nanoseconds part

16

4

instance domain number

20

4

N: number of instances in domain, normally >0

24

4

first instance number

28

4

second instance number (if appropriate)

...

...

...

24+4*N

4

first offset into string table (see below)

24+4*N+4

4

second offset into string table (etc.)

...

...

...

24+8*N

M

base of string table, containing

packed, NULL-terminated instance names

The ``delta'' instance domain record in Version 3 uses the same physical structure as the ``full'' instance domain above with the following differences:

- The tag is TYPE_INDOM_DELTA=6.

- The ``number of instances in domain'' field becomes the sum of the number of instances added and the number of instances deleted.

- Deleted instances are encoded with the string offset set to -1 and there is no corresponding string table entry.

- Added instances are encoded exactly the same way.

The ``delta'' instance domain format is used to provide a more compact on-disk encoding for instance domains that have a large number of instances and are subject to frequent small changes, e.g. the instance domain of process ids, as exported by pmdaproc(1).

For ``full'' instance domain records the instance domain replace the previous instance domain: prior records are not searched for instance domain metadata queries after this timestamp.

Each instance domain in a Version 3 archive must have an initial ``full'' instance domain record. Subsequent records for the same instance domain can be the `full'' or the ``delta'' variant. Any instance mentioned in the prior observation of an instance domain that is not mentioned in the ``delta'' instance domain record is assumed to continue to exist for the current observation of the instance domain.

### Labels for Contexts, Instance Domains and Metrics
Instances of this (pmLogLabelSet) record provide sets of label-name:label-value pairs associated with labels of the context, instance domains and individual performance metrics - refer to pmLookupLabels(3) for further details.

Any instance domain identifier will have already been mentioned in a prior pmDesc record.

As new labels can appear during an archiving session, these records are timestamped and must be searched when decoding pmResult records from the archive data volumes. The pmLogLabelSet format differs between Version 2 and Version 3, with the latter providing enhanced timestamps (64-bit encoding of the seconds part and nanosecond precision).

Version 2

Offset

Length

Name

0

4

tag, TYPE_LABEL_V2=3

4

4

timestamp, seconds part (past UNIX epoch)

8

4

timestamp, microseconds part

12

4

label type (PM_LABEL_* type macros.)

16

4

numeric identifier - domain, PMID, etc or PM_IN_NULL=-1 for context labels

20

4

N: number of label sets in this record, usually 1 except in the case of instances

24

4

offset to the start of the JSONB labels string

28

L1

first labelset array entry (see below)

...

...

...

28+L1

LN

N-th labelset array entry (see below)

...

...

...

28+L1+...LN

M

concatenated JSONB strings for all labelsets

Version 3

Offset

Length

Name

0

4

tag, TYPE_LABEL=7

4

8

timestamp, seconds part (past UNIX epoch)

12

4

timestamp, nanoseconds part

16

4

label type (PM_LABEL_* type macros.)

20

4

numeric identifier - domain, PMID, etc or PM_IN_NULL=-1 for context labels

24

4

N: number of label sets in this record, usually 1 except in the case of instances

28

4

offset to the start of the JSONB labels string

32

L1

first labelset array entry (see below)

...

...

...

32+L1

LN

N-th labelset array entry (see below)

...

...

...

32+L1+...LN

M

concatenated JSONB strings for all labelsets

Records of this form replace the existing labels for a given label type: prior records are not searched for resolving that class of label in measurements after this timestamp.

The individual labelset array entries are variable length, depending on the number of labels present within that set. These entries contain the instance identifiers (in the case of type PM_LABEL_INSTANCES labels), lengths and offsets of each label name and value, and also any flags set for each label.

Offset

Length

Name

0

4

instance identifier (or PM_IN_NULL=-1)

4

4

length of JSONB label string

8

4

N: number of labels in this labelset

12

2

first label name offset

14

1

first label name length

15

1

first label flags (e.g. optionality)

16

2

first label value offset

18

2

first label value length

20

2

second label name offset (if appropriate)

...

...

...

### Help Text
This (pmLogText) record stores help text associated with a metric or an instance domain - as provided by pmLookupText(3) and pmLookupInDomText(3).

The metric identifier and instance domain identifier will have already been mentioned in a prior pmDesc record.

Offset

Length

Name

0

4

tag, TYPE_TEXT=4

4

4

text and identifier type (PM_TEXT_* macros.)

8

4

numeric identifier - PMID or instance domain

12

M

help text string, arbitrary text

## INDEX FILE (.index) RECORDS
After the archive label record, the temporal index file contains a plainly concatenated, unframed group of tuples, which relate timestamps to the byte offsets in the volume and .meta files. These records are fixed size, fixed format, and are not enclosed in the standard length/payload/length wrapper: they take up the entire remainder of the .index file after the archive label record.

The temporal index file provides a rapid way of seeking to a particular point of time within an archive for both the performance metric values and the associated metadata.

See also libpcopilot/src/logutil.c.

The index format differs between Version 2 and Version 3, with the latter providing enhanced timestamps (64-bit encoding of the seconds part and nanosecond precision) and 64-bit byte offsets.

Version 2

Offset

Length

Name

0

4

timestamp, seconds part (past UNIX epoch)

4

4

timestamp, microseconds part

8

4

archive volume number (0...N)

12

4

byte offset in .meta file

16

4

byte offset in archive volume file

Version 3

Offset

Length

Name

0

8

timestamp, seconds part (past UNIX epoch)

8

4

timestamp, nanoseconds part

12

4

archive volume number (0...N)

16

8

byte offset in .meta file

24

8

byte offset in archive volume file

Since the temporal index is optional, and exists only to speed up time-based random access to metrics and their metadata, the index records are emitted only intermittently. An archive reader program should not presume any particular rate of data flow into the index. However, common events that may trigger a new temporal index record include changes in instance domains, switching over to a new archive volume, and starting or stopping logging. One reliable invariant however is that, for each index entry, there are to be no meta or archive volume records with a timestamp after that in the index, but physically before the associated byte offset in the index.

## FILES
Several PCP tools create archives in standard locations:

$HOME/.pcp/pmlogger

default location for the interactive chart recording mode in pmchart(1)

$PCP_LOG_DIR/pmlogger

default location for pmlogger_daily(1) and pmlogger_check(1) scripts

## SEE ALSO
mkaf(1), PCPIntro(1), pmafm(1), pmchart(1), pmdaproc(1), pmdumplog(1), pmlogger(1), pmlogger_check(1), pmlogger_daily(1), pmlogreduce(1), pmlogrewrite(1), pmlogsummary(1), LOGIMPORT(3), PMAPI(3), pmLookupDesc(3), pmLookupInDom(3), pmLookupInDomText(3), pmLookupLabels(3), pmLookupName(3), pmLookupText(3), pcp.conf(5) and pcp.env(5).


PMNS

title: PMNS(5)

summary: the performance metrics name space

text:
# PMNS(5)

## NAME
PMNS - the performance metrics name space

## SYNOPSIS
$PCP_VAR_DIR/pmns

## DESCRIPTION
When using the Performance Metrics Programming Interface (PMAPI) of the Performance Co-Pilot (PCP), performance metrics are identified by an external name in a hierarchic Performance Metrics Name Space (PMNS), and an internal identifier, the Performance Metric Identifier (PMID).

A PMNS specifies the association between a metric's name and its PMID.

A PMNS is defined on one or more ASCII source files.

Loading of a PMNS is done by calling pmLoadNameSpace(3) or pmLoadASCIINameSpace(3).

As of Version 3.10.3 of PCP, by default duplicate names for the same PMID are allowed in the PMNS, although pmLoadASCIINameSpace(3) provides an alternative interface with user-defined control over the processing of duplicate names in the PMNS. The external format for a PMNS conforms to the syntax and semantics described in the following sections.

There is one default PMNS in the files below $PCP_VAR_DIR/pmns, although users and application developers are free to create and use alternate PMNS's. For an example of this, see the PCP Tutorial in $PCP_DEMOS_DIR/Tutorial.

Although an application can call pmLoadNameSpace(3), normally this is only done directly for the -n command line option where an explicit root PMNS file is specified. Since PCP version 2 uses a distributed PMNS (see below), an application can extract PMNS information from a host's PMCD or an archive. If the PMNS source is a version 1 archive (see PCPIntro(1)), however, then the local PMNS will be loaded using the path specified by the environment variable PMNS_DEFAULT.

## DISTRIBUTED PMNS
In PCP version 1, the PMNS functions in the API all operated on a PMNS loaded locally from a file. Since PCP version 2, however, PMNS functions may get the PMNS information remotely from a PMCD or directly from the meta data of an archive.

## PROCESSING FRAMEWORK
The PMNS specification is initially passed through pmcpp(1). This means the following facilities may be used in the specification

+

C-style comments

+

\#include directives

+

\#define directives and macro substitution

+

conditional processing via #ifdef ... #endif, etc.

When pmcpp(1) is executed, the ``standard'' include directories are the current directory and $PCP_VAR_DIR/pmns.

The pre-processing with pmcpp(1) may be omitted in some cases where the PMNS is known to not contain any C-style comments, preprocessor directives or macros. Refer to the descriptions of pmLoadASCIINameSpace(3) and pmLoadNameSpace(3) for details.

## SYNTAX
The general syntax for a non-leaf node in the PMNS is as follows

```
pathname {

        name      [pmid]

        ...
}
```

Where pathname is the full pathname from the root of the PMNS to this non-leaf node, with each component in the pathname separated by a ``.''. The root node for the PMNS must have the special name ``root'', but the common prefix ``root.'' must be omitted from all pathnames. Each component in the pathname is drawn from the ASCII(7) character set, beginning with an alphabetic character, and followed by zero or more characters drawn from the alphabetics, the digits and the underscore ``_'') character. For alphabetic characters in a pathname component, upper and lower case are distinguished.

Non-leaf nodes in the PMNS may be defined in any order.

The descendent nodes are defined by the set of names, relative to the pathname of their parent non-leaf node. For the descendent nodes, leaf nodes have a pmid specification, non-leaf nodes do not. The syntax for the pmid specification has been chosen to help manage the allocation of PMIDs across disjoint and autonomous domains of administration and implementation. Each pmid consists of 3 integer parts, separated by colons, e.g. 14:27:11. This hierarchic numbering scheme is intended to mirror the implementation hierarchy of performance metric domain, metrics cluster (data structure or operational similarity) and individual metric. In practice, the two leading components are likely to be macros in the PMNS specification source, and pmcpp(1) will convert the macros to integers. These macros for the initial components of the pmid are likely to be defined either in a standard include file, e.g. $PCP_VAR_DIR/pmns/stdpmid, or in the current source file.

To support dynamic metrics, where the existence of a metric is known to a PMDA, but not visible in the PMNS, a variant syntax for the pmid is supported, namely a domain number followed by asterisks for the other components of the pmid, e.g. 14:*:*. The corresponding metric name forms the root of a subtree of dynamic metric names defined in the corresponding PMDA as identified by the domain number.

The current allocation of the high-order (PMD or domain) component of PMIDs is as follows.

Range

Allocation

0

reserved

1-384

production PMDAs from PCP packages

385-510

end-user PMDAs (allocate from high to low)

511

reserved for dynamic PMNS entries

## EXAMPLE

```
#define KERNEL 1
#define FOO 387
root {

    network

    cpu

    dynamic     FOO:*:*
}
#define NETWORK 26
network {

    intrate     KERNEL:NETWORK:1

    packetrate
}
network.packetrate {

    in          KERNEL:NETWORK:35

    out         KERNEL:NETWORK:36
}
#define CPU 10
cpu {

    syscallrate KERNEL:CPU:10

    util
}
#define USER 20
#define SYSTEM 21
#define IDLE 22
cpu.util {

    user        KERNEL:CPU:USER

    sys         KERNEL:CPU:SYSTEM

    idle        KERNEL:CPU:IDLE
}
```

## SEE ALSO
PCPIntro(1), pmcd(1), pmcpp(1), PCPIntro(3), PMAPI(3), pmErrStr(3), pmGetConfig(3), pmLoadASCIINameSpace(3), pmLoadNameSpace(3), pcp.conf(5) and pcp.env(5).


labels.conf

title: labels.conf(5)

text:
# labels.conf(5)

## NAME
labels.conf - Performance Co-Pilot labels configuration

## SYNOPSIS
/etc/pcp/labels.conf

## DESCRIPTION
Several Performance Co-Pilot (PCP) tools and utilities support the use of metric labels. This functionality applied a hierarchical set of labels to each instance of every metric, as described in pmLookupLabels(3).

The pmcd(1) and pmproxy(1) daemons are particularly important to the labels system, respectively providing the labels in real-time and then discovering recorded (archive) labels and indexing these for pmseries(1) queries using a redis-server(1).

The /etc/pcp/labels.conf file is a single point of configuration for behaviour affecting all labels exported by pmcd or through tools using PMAPI local context services. It uses the common ``ini'' file format and any variable it specifies that is not in an explicit square-bracket enclosed section is considered a [global] variable.

The available configuration variables are as follows :

machineid_hash=none|sha256

When specified in the [global] section, controls the manner in which the local machine-id(5) is exported as a label. The default setting (none) exports a "machineid" context label with value reflecting the contents of the /etc/machine-id file, on any platforms that provide this file. The alternative (sha256) exports a "machineid_sha256" label, instead, and the value is the SHA256 (one-way) hash of the file.

## SEE ALSO
pmcd(1), pmproxy(1), pmseries(1), redis-server(1), PMAPI(3), pmLookupLabels(3) and machine-id(5).


mmv

title: mmv(5)

text:
# mmv(5)

## NAME
mmv - Memory Mapped Values for Performance Co-Pilot

## SYNOPSIS
$PCP_TMP_DIR/mmv/<file>

## DESCRIPTION
The files in $PCP_TMP_DIR/mmv are generated either by the mmv_stats_init(3) and mmv_stats2_init(3) functions from the libpcopilot_mmv library, or by a native language module such as Parfait (Java), Speed (Golang) or Hornet (Rust).

There could be multiple files in this directory, each file representing a single source of the performance metrics. The metrics are harvested by pmdammv(1) which exports them to the rest of the Performance Co-Pilot infrastructure.

## FILE FORMAT
Each file starts with the following header:

Offset

Length

Name

0

4

tag == "MMV\0"

4

4

Version (1 or 2)

8

8

Generation 1

16

8

Generation 2

24

4

Number of TOC entries

28

4

Flags

32

4

Process identifier (PID)

36

4

Cluster identifier

The version number specifies which mapping layout format is in use. There are two, both are very similar, as described below. The sole purpose of the MMV version 2 format is to allow the use of longer metric and instance names. If names longer than MMV_NAMEMAX are not in use, it is best to use MMV version 1 format as this allows older versions of PCP to also consume the data. Support for v2 format was added in the pcp-3.11.4 release.

The generation numbers are timestamps at the time of file creation, and must match for the file to be considered by the MMV PMDA.

The flags can specify ways in which the client would like the MMV PMDA to behave - e.g. the MMV_FLAG_PROCESS flag specifies that only if the process identified by PID is currently running should those values be exported.

Finally, if set, the cluster identifier is a hint to the MMV PMDA as to what cluster should be used with this application when forming the individual metric identifiers. A performance metric identifier (see PMDA(3)) consists of the PMDA domain number, the cluster number, and the individual item numbers described in the Metrics section.

The header is followed by at least 2 TOC sections: one section for metrics and another for values. The TOC section has the following format:

Offset

Length

Value

0

4

Section Type (see mmv_stats.h)

4

4

Number of entries in the section

8

8

Section's offset from the start of the file

The section types are:

1: Indoms (instance domain definitions)

2: Instances

3: Metrics (metric definitions)

4: Values

5: String

6: Labels

The only mandatory sections are Metrics and Values. Indoms and Instances sections of either version only appear if there are metrics with multiple instances. String sections only appear if there are metrics with string values, when Metrics or Indoms are defined with help text, or in v2 MMV format where metric names and instance names are stored in string sections (providing significantly more space than v1 MMV format for these names). Label sections only appear if there are metrics annotated with labels (name/value pairs). Labels are supported in v3 MMV format.

The entries in the Indoms sections have the following format:

Offset

Length

Value

0

4

Unique serial number for this domain

4

4

Number of entries in the domain

8

8

Offset to first Instance or Instance2

16

8

Short help text offset

24

8

Long help text offset

The entries in the Instances (v1) section have the following format:

Offset

Length

Value

0

8

Offset into the indom section

8

4

Unused padding (zero filled)

12

4

Internal instance identifier

16

64

External instance identifier

The entries in the Instances (v2) section have the following format:

Offset

Length

Value

0

8

Offset into the indom section

8

4

Unused padding (zero filled)

12

4

Internal instance identifier

16

8

External instance identifier string offset

The entries in the Metrics (v1) section have the following format:

Offset

Length

Value

0

64

Metric Name

64

4

Metric Item (see PMDA(3))

68

4

Metric Type (see mmv_stats.h)

72

4

Semantics (see PMAPI(3))

76

4

Dimensions (see PMAPI(3))

80

4

Instance Domain ID

84

4

Unused padding (zero filled)

88

8

Short help text offset

96

8

Long help text offset

The entries in the Metrics (v2) section have the following format:

Offset

Length

Value

0

8

Metric Name string offset

8

4

Metric Item (see PMDA(3))

12

4

Metric Type (see mmv_stats.h)

16

4

Semantics (see PMAPI(3))

20

4

Dimensions (see PMAPI(3))

24

4

Instance Domain ID

28

4

Unused padding (zero filled)

32

8

Short help text offset

40

8

Long help text offset

The entries in the Values section have the following format:

Offset

Length

Value

0

8

pmAtomValue (see PMAPI(3))

8

8

Extra space for STRING and ELAPSED

16

8

Offset into the Metrics section

24

8

Offset into the Instances section

Each entry in the strings section is a 256 byte character array, containing a single NULL-terminated character string. So each string has a maximum length of 256 bytes, which includes the terminating NULL.

The entries in the Labels (v3) section have the following format:

Offset

Length

Value

0

4

Flags (PM_LABEL_[CLUSTER|ITEM|INDOM|INSTANCES]|OPTIONAL)

4

4

Identifier for given type (indom, cluster or item)

8

4

Internal Instance or PM_IN_NULL

12

244

Payload (Name and Value JSONB String)

Each entry in the payload is a 244 byte (maximum) character array, containing a single NULL-terminated name:value pair in JSON format. Insignificant whitespace must not be present. Label names consist only of alphanumeric characters or underscores, and must begin with an alphabetic. Upper and lower case characters are considered distinct.

## SEE ALSO
PCPIntro(1), pmdammv(1), PMAPI(3), PMDA(3), mmv_stats_registry(3), pcp.conf(5) and pcp.env(5).