.\"@ pam_xdg - manage XDG Base Directories (runtime dir life time, environ).
.\"
.\" Copyright (c) 2021 Steffen Nurpmeso <steffen@sdaoden.eu>.
.\" SPDX-License-Identifier: ISC
.\"
.\" Permission to use, copy, modify, and/or distribute this software for any
.\" purpose with or without fee is hereby granted, provided that the above
.\" copyright notice and this permission notice appear in all copies.
.\"
.\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
.\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
.\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
.\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
.\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
.\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
.\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
.
.Dd August 1, 2021
.Dt PAM_XDG 8
.Os
.
.
.Sh NAME
.Nm pam_xdg.so
.Nd PAM module that manages XDG Base Directories
.
.
.Sh SYNOPSIS
.
.Nm
.Op Ar runtime
.Op Ar notroot
.Op Ar track_sessions Op Ar per_user_lock
.
.
.Sh DESCRIPTION
.
.Nm
is a PAM module that manages creation of the
.Ev XDG_RUNTIME_DIR
directory, as well as injection of environment variables denoting all
directories specified by the
.Lk https://specifications.\:freedesktop.\:org/basedir-\:\
spec/\:basedir-\:spec-\:latest.html "XDG Base Directory Specification"
into user sessions.
.
.Pp
When linked into the PAM session system the runtime directory will be
created once a user creates his or her first login session.
Unless
.Ar runtime
was given all XDG related environment variables will be created in all
user sessions with their default or computed values, otherwise only
.Ev XDG_RUNTIME_DIR .
If
.Ar notroot
was given the module will bypass itself for root account logins and
perform no actions for root.
Lastly
.Ar track_sessions
will enable session tracking: once the last session ends, the user's
.Ev XDG_RUNTIME_DIR
will be recursively removed; on high-load servers then setting
.Ar per_user_lock
will reduce lock file lock contention.
.
.Pp
In order to make use of this module, place the following in the
.Ql session
part of the control file of desire under
.Pa /etc/pam.d ,
on Linux it may be
.Pa /etc/pam.d/common-session
if that exists, on BSD's the files
.Pa /etc/pam.d/system
as well as
.Pa /etc/pam.d/login ,
.Pa /etc/pam.d/sshd
and
.Pa /etc/pam.d/su
may be desirable, adjusting paths as necessary:
.
.Bd -literal -offset indent
session optional pam_xdg.so notroot track_sessions
.Ed
.
.
.Sh "SEE ALSO"
.
.Xr pam 3 ,
.Xr pam.conf 5
.
.
.Sh AUTHORS
.
.An "Steffen Nurpmeso" Aq steffen@sdaoden.eu .
.
.
.Sh CAVEATS
.
On Unix systems any
.Dq daemonized
program or script is reparented to the program running with PID 1,
most likely leaving the PAM user session without PAM recognizing this.
Yet careless such code may hold or expect availability of resources of
the session it just left, truly performing cleanup when sessions end
seems thus unwise.
Since so many PAM modules do support session tracking and cleanup
.Nm
readded optional support for this.
.
.\" s-ts-mode