# pam_systemd

## NAME



           pam_systemd - Register user sessions in the systemd login manager
    


## SYNOPSIS



           pam_systemd.so
    


## DESCRIPTION



           **pam_systemd** registers user sessions with the systemd login manager
           systemd-logind.service(8), and hence the systemd control group
           hierarchy.
    
           The module also applies various resource management and runtime
           parameters to the new session, as configured in the **JSON User**
           **Records******[1] of the user, when one is defined.
    
           On login, this module — in conjunction with systemd-logind.service
           — ensures the following:
    
            1. If it does not exist yet, the user runtime directory
               /run/user/$UID is either created or mounted as new "tmpfs"
               file system with quota applied, and its ownership changed to
               the user that is logging in.
    
            2. The _$XDG_SESSION_ID_ environment variable is initialized. If
               auditing is available and **pam_loginuid.so** was run before this
               module (which is highly recommended), the variable is
               initialized from the auditing session id
               (/proc/self/sessionid). Otherwise, an independent session
               counter is used.
    
            3. A new systemd scope unit is created for the session. If this
               is the first concurrent session of the user, an implicit
               per-user slice unit below user.slice is automatically created
               and the scope placed into it. An instance of the system
               service user@.service, which runs the systemd user manager
               instance, is started.
    
            4. The "$TZ", "$EMAIL" and "$LANG" environment variables are
               configured for the user, based on the respective data from the
               user's JSON record (if it is defined). Moreover, any
               environment variables explicitly configured in the user record
               are imported, and the umask, nice level, and resource limits
               initialized.
    
           On logout, this module ensures the following:
    
            1. If enabled in logind.conf(5) (_KillUserProcesses=_), all
               processes of the session are terminated. If the last
               concurrent session of a user ends, the user's systemd instance
               will be terminated too, and so will the user's slice unit.
    
            2. If the last concurrent session of a user ends, the user
               runtime directory /run/user/$UID and all its contents are
               removed, too.
    
           If the system was not booted up with systemd as init system, this
           module does nothing and immediately returns **PAM_SUCCESS**.
    


## OPTIONS



           The following options are understood:
    
           _class=_
               Takes a string argument which sets the session class. The
               _XDG_SESSION_CLASS_ environment variable (see below) takes
               precedence. See sd_session_get_class(3) for a way to query the
               class of a session. The following session classes are defined:
    
               **Table 1. Session Classes**
               ┌──────────────────┬───────────────────────────────────┐
               │ **Name** │ **Explanation** │
               ├──────────────────┼───────────────────────────────────┤
               │ **user** │ A regular interactive             │
               │                  │ user session. This is             │
               │                  │ the default class for             │
               │                  │ sessions for which a TTY          │
               │                  │ or X display is known at          │
               │                  │ session registration              │
               │                  │ time.                             │
               ├──────────────────┼───────────────────────────────────┤
               │ **user-early** │ Similar to **user** but               │
               │                  │ sessions of this class            │
               │                  │ are not ordered after             │
               │                  │ systemd-user-sessions.service(8), │
               │                  │ i.e. may be started               │
               │                  │ before regular sessions           │
               │                  │ are allowed to be                 │
               │                  │ established. This                 │
               │                  │ session class is the              │
               │                  │ default for sessions of           │
               │                  │ the root user that would          │
               │                  │ otherwise qualify for             │
               │                  │ the **user** class, see               │
               │                  │ above. (Added in v256.)           │
               ├──────────────────┼───────────────────────────────────┤
               │ **user-light** │ Similar to **user** , but sessions of  │
               │                  │ this class will not pull in the   │
               │                  │ user@.service(5) of the user, and │
               │                  │ thus possibly have no service     │
               │                  │ manager of the user running.      │
               │                  │ (Added in v258.)                  │
               ├──────────────────┼───────────────────────────────────┤
               │ **user-early-light** │ Similar to **user-early** , but        │
               │                  │ sessions of this class will not   │
               │                  │ pull in the user@.service(5) of   │
               │                  │ the user, and thus possibly have  │
               │                  │ no service manager of the user    │
               │                  │ running. (Added in v258.)         │
               ├──────────────────┼───────────────────────────────────┤
               │ **user-incomplete** │ Similar to **user** but for sessions  │
               │                  │ which are not fully set up yet,   │
               │                  │ i.e. have no home directory       │
               │                  │ mounted or similar. This is used  │
               │                  │ by systemd-homed.service(8) to    │
               │                  │ allow users to log in via ssh(1)  │
               │                  │ before their home directory is    │
               │                  │ mounted, delaying the mount until │
               │                  │ the user provided the unlock      │
               │                  │ password. Sessions of this class  │
               │                  │ are upgraded to the regular **user** │
               │                  │ class once the home directory is  │
               │                  │ activated.                        │
               ├──────────────────┼───────────────────────────────────┤
               │ **greeter** │ Similar to **user** but for sessions  │
               │                  │ that are spawned by a display     │
               │                  │ manager ephemerally and which     │
               │                  │ prompt the user for login         │
               │                  │ credentials.                      │
               ├──────────────────┼───────────────────────────────────┤
               │ **lock-screen** │ Similar to **user** but for sessions  │
               │                  │ that are spawned by a display     │
               │                  │ manager ephemerally and which     │
               │                  │ show a lock screen that can be    │
               │                  │ used to unlock locked user        │
               │                  │ accounts or sessions.             │
               ├──────────────────┼───────────────────────────────────┤
               │ **background** │ Used for background sessions,     │
               │                  │ such as those invoked by cron(8)  │
               │                  │ and similar tools. This is the    │
               │                  │ default class for sessions for    │
               │                  │ which no TTY or X display is      │
               │                  │ known at session registration     │
               │                  │ time.                             │
               ├──────────────────┼───────────────────────────────────┤
               │ **background-light** │ Similar to **background** , but        │
               │                  │ sessions of this class will not   │
               │                  │ pull in the user@.service(5) of   │
               │                  │ the user, and thus possibly have  │
               │                  │ no service manager of the user    │
               │                  │ running. (Added in v256.)         │
               ├──────────────────┼───────────────────────────────────┤
               │ **manager** │ The user@.service(5) service of   │
               │                  │ the user is registered under this │
               │                  │ session class. (Added in v256.)   │
               ├──────────────────┼───────────────────────────────────┤
               │ **manager-early** │ Similar to **manager** , but for the   │
               │                  │ root user. Compare with the **user** │
               │                  │ vs. **user-early** situation. (Added  │
               │                  │ in v256.)                         │
               ├──────────────────┼───────────────────────────────────┤
               │ **none** │ Skips registering this session    │
               │                  │ with logind. No session scope     │
               │                  │ will be created, and the user     │
               │                  │ service manager will not be       │
               │                  │ started. (Added in v258.)         │
               └──────────────────┴───────────────────────────────────┘
    
               Added in version 197.
    
           _type=_
               Takes a string argument which sets the session type. The
               _XDG_SESSION_TYPE_ environment variable (see below) takes
               precedence. One of **unspecified** , **tty** , **x11** , **wayland** , **mir** , or
               **web**. See sd_session_get_type(3) for details about the session
               type.
    
               Added in version 209.
    
           _desktop=_
               Takes a single, short identifier string for the desktop
               environment. The _XDG_SESSION_DESKTOP_ environment variable (see
               below) takes precedence. This may be used to indicate the
               session desktop used, where this applies and if this
               information is available. For example: **GNOME** , or **KDE**. It is
               recommended to use the same identifiers and capitalization as
               for _$XDG_CURRENT_DESKTOP_ , as defined by the **Desktop Entry**
               **Specification******[2]. (However, note that the option only takes a
               single item, and not a colon-separated list like _$XDG_CURRENT_DESKTOP_.) See sd_session_get_desktop(3) for
               further details.
    
               Added in version 240.
    
           _area=_
               Takes a filename as parameter. If specified and the user logs
               into their account the _$HOME_ environment variable will be set
               to ~/Areas/ suffixed by the specified string, but only if that
               directory exists. Moreover, the _$XDG_AREA_ variable will be set
               to the (unprefixed) parameter.
    
               This functionality may be used to maintain multiple separate
               secondary home directories within the primary home directory
               of the user. Typically, the area to log into is specified
               while logging in, if the account permits that (accounts
               provided by pam_systemd_home(8) do), but this parameter may be
               used to define a default if that's not provided.
    
               Note that this only adjusts _$HOME_ during login, it does not
               affect the otherwise reported home directory of the user.
               Specifically this means that sshd(8) will continue to look for
               SSH keys of the user only in the primary home directory of the
               user, not in any of their areas.
    
               Note that the default area to log into can also be configured
               as part of the user account. The area specified via _area=_
               overrides the default area configured there. Also note that if
               the area is specified explicitly by the user at login time, it
               overrides both. Also note that setting this parameter to an
               empty string has the effect of undoing the effect of any
               default area configured as part of the user record, i.e.
               ensuring the user logs into the primary home directory of
               their account.
    
               For details on the area concept see pam_systemd_home(8).
    
               Added in version 258.
    
           _default-capability-bounding-set=_ , _default-capability-ambient-set=_
               Takes a comma-separated list of process capabilities (e.g.
               **CAP_WAKE_ALARM** , **CAP_BLOCK_SUSPEND** , ...) to set for the invoked
               session's processes, if the user record does not encode
               appropriate sets of capabilities directly. See capabilities(7)
               for details on the capabilities concept. If not specified, the
               default bounding set is left as is (i.e. usually contains the
               full set of capabilities). The default ambient set is set to
               **CAP_WAKE_ALARM** for regular users if the PAM session is
               associated with a local seat or if it is invoked for the
               systemd user service user@.service. Otherwise, defaults to the
               empty set.
    
               Added in version 254.
    
           _debug_[=]
               Takes an optional boolean argument. If yes or without the
               argument, the module will log debugging information as it
               operates.
    


## MODULE TYPES PROVIDED



           Only **session** is provided.
    


## ENVIRONMENT



           The following environment variables are initialized by the module
           and available to the processes of the user's session:
    
           _$XDG_SESSION_ID_
               A short session identifier, suitable to be used in filenames.
               The string itself should be considered opaque, although often
               it is just the audit session ID as reported by
               /proc/self/sessionid. Each ID will be assigned only once
               during machine uptime. It may hence be used to uniquely label
               files or other resources of this session. Combine this ID with
               the boot identifier, as returned by sd_id128_get_boot(3), for
               a globally unique identifier.
    
           _$XDG_RUNTIME_DIR_
               Path to a user-private user-writable directory that is bound
               to the user login time on the machine. It is automatically
               created the first time a user logs in and removed on the
               user's final logout. If a user logs in twice at the same time,
               both sessions will see the same _$XDG_RUNTIME_DIR_ and the same
               contents. If a user logs in once, then logs out again, and
               logs in again, the directory contents will have been lost in
               between, but applications should not rely on this behavior and
               must be able to deal with stale files. To store
               session-private data in this directory, the user should
               include the value of _$XDG_SESSION_ID_ in the filename. This
               directory shall be used for runtime file system objects such
               as **AF_UNIX** sockets, FIFOs, PID files and similar. It is
               guaranteed that this directory is local and offers the
               greatest possible file system feature set the operating system
               provides. For further details, see the **XDG Base Directory**
               **Specification******[3]._$XDG_RUNTIME_DIR_ is not set if the current
               user is not the original user of the session.
    
           _$TZ_ , _$EMAIL_ , _$LANG_
               If a JSON user record is known for the user logging in these
               variables are initialized from the respective data in the
               record.
    
               Added in version 245.
    
           _$SHELL_PROMPT_PREFIX_ , _$SHELL_PROMPT_SUFFIX_ , _$SHELL_WELCOME_
               These environment variables are initialized from the service
               credentials "shell.prompt.prefix", "shell.prompt.suffix" and
               "shell.welcome" if set. They are passed to the invoked session
               processes, where they are imported into any shell prompt
               (specifically _$SHELL_PROMPT_PREFIX_ is added as prefix to _$PS1_ ,
               and _$SHELL_PROMPT_SUFFIX_ as suffix) or printed on screen when
               a shell first initializes.
    
               Added in version 257.
    
           The following environment variables are read by the module and may
           be used by the PAM service to pass metadata to the module. If
           these variables are not set when the PAM module is invoked but can
           be determined otherwise they are set by the module, so that these
           variables are initialized for the session and applications if
           known at all.
    
           _$XDG_SESSION_TYPE_
               The session type. This may be used instead of _type=_ on the
               module parameter line, and is usually preferred.
    
               Added in version 209.
    
           _$XDG_SESSION_CLASS_
               The session class. This may be used instead of _class=_ on the
               module parameter line, and is usually preferred.
    
               Added in version 209.
    
           _$XDG_SESSION_DESKTOP_
               The desktop identifier. This may be used instead of _desktop=_
               on the module parameter line, and is usually preferred.
    
               Added in version 209.
    
           _$XDG_SEAT_
               The seat name the session shall be registered for, if any.
    
               Added in version 209.
    
           _$XDG_VTNR_
               The VT number the session shall be registered for, if any.
               (Only applies to seats with a VT available, such as "seat0")
    
               Added in version 209.
    
           _$XDG_AREA_
               If an area (secondary home directories of the user, within the
               primary home directory) to log into has been selected this
               variable is set to the area name (without any path prefix). It
               is otherwise unset. For details about areas, see above.
    
               Added in version 258.
    
           If not set, **pam_systemd** will initialize _$XDG_SEAT_ and _$XDG_VTNR_
           based on the _$DISPLAY_ variable (if the latter is set).
    


## SESSION LIMITS



           PAM modules earlier in the stack, that is those that come before
           **pam_systemd.so** , can set session scope limits using the PAM context
           objects. The data for these objects is provided as **NUL** -terminated
           C strings and maps directly to the respective unit resource
           control directives. Note that these limits apply to individual
           sessions of the user, they do not apply to all user processes as a
           combined whole. In particular, the per-user **user@.service** unit
           instance, which runs the **systemd --user** manager process and its
           children, and is tracked outside of any session, being shared by
           all the user's sessions, is not covered by these limits.
    
           See systemd.resource-control(5) for more information about the
           resources. Also, see pam_set_data(3) for additional information
           about how to set the context objects.
    
           _systemd.memory_max=_
               Sets unit _MemoryMax=_.
    
               Added in version 239.
    
           _systemd.tasks_max=_
               Sets unit _TasksMax=_.
    
               Added in version 239.
    
           _systemd.cpu_weight=_
               Sets unit _CPUWeight=_.
    
               Added in version 239.
    
           _systemd.io_weight=_
               Sets unit _IOWeight=_.
    
               Added in version 239.
    
           _systemd.runtime_max_sec=_
               Sets unit _RuntimeMaxSec=_.
    
               Added in version 244.
    
           Example data as can be provided from an another PAM module:
    
               pam_set_data(handle, "systemd.memory_max", (void *)"200M", cleanup);
               pam_set_data(handle, "systemd.tasks_max",  (void *)"50",   cleanup);
               pam_set_data(handle, "systemd.cpu_weight", (void *)"100",  cleanup);
               pam_set_data(handle, "systemd.io_weight",  (void *)"340",  cleanup);
               pam_set_data(handle, "systemd.runtime_max_sec", (void *)"3600", cleanup);
    


## EXAMPLE



           Here's an example PAM configuration fragment that allows users
           sessions to be managed by systemd-logind.service:
    
               #%PAM-1.0
               -auth     [success=done authtok_err=bad perm_denied=bad maxtries=bad default=ignore] pam_systemd_home.so
               auth      sufficient pam_unix.so
               auth      required   pam_deny.so
    
               account   required   pam_nologin.so
               -account  [success=done authtok_expired=bad new_authtok_reqd=bad maxtries=bad acct_expired=bad default=ignore] pam_systemd_home.so
               account   required   pam_unix.so
    
               -password sufficient pam_systemd_home.so
               password  sufficient pam_unix.so sha512 shadow try_first_pass
               password  required   pam_deny.so
    
               -session  optional   pam_keyinit.so revoke
               -session  optional   pam_loginuid.so
               -session  optional   pam_systemd_home.so
               **-session  optional   pam_systemd.so**
               session   required   pam_unix.so
    


## NOTES



            1. JSON User Records
               https://systemd.io/USER_RECORD
    
            2. Desktop Entry Specification
               https://standards.freedesktop.org/desktop-entry-spec/latest/
    
            3. XDG Base Directory Specification
               https://standards.freedesktop.org/basedir-spec/basedir-spec-latest.html
    


* * *