Add support for running services inside a PAM session

.github/workflows/build.yml

@@ -99,7 +99,7 @@ jobs:
       - name: Install dependencies
         run: |
           sudo apt-get -y update
-          sudo apt-get -y install pkg-config tree jq libcap-dev libconfuse-dev libblkid-dev
+          sudo apt-get -y install pkg-config tree jq libcap-dev libconfuse-dev libblkid-dev libpam0g-dev
           wget https://github.com/troglobit/libuev/releases/download/v2.4.1/libuev-2.4.1.tar.xz
           wget https://github.com/troglobit/libite/releases/download/v2.6.2/libite-2.6.2.tar.gz
           tar xf libuev-2.4.1.tar.xz

configure.ac

@@ -40,7 +40,7 @@ AC_PROG_MKDIR_P
 
 # Configuration.
 AC_CHECK_HEADERS([termios.h sys/ioctl.h mntent.h sys/sysmacros.h])
-AC_CHECK_FUNCS([strstr getopt getmntent getmntent_r])
+AC_CHECK_FUNCS([strstr getopt getmntent getmntent_r close_range])
 
 # Check for uint[8,16,32]_t
 AC_TYPE_UINT8_T
@@ -85,6 +85,11 @@ AC_ARG_ENABLE(libcap,
         AS_HELP_STRING([--disable-libcap], [Disable Linux capabilities support]),,[
 				enable_libcap=yes])
 
+AC_ARG_ENABLE(pam,
+        AS_HELP_STRING([--disable-pam], [Disable PAM session support for services]),
+        [pam_explicit=yes],
+        [enable_pam=yes])
+
 AC_ARG_ENABLE(redirect,
         AS_HELP_STRING([--disable-redirect], [Disable redirection of service output to /dev/null]),,[
 	enable_redirect=yes])
@@ -235,6 +240,26 @@ AS_IF([test "x$enable_libcap" = "xyes"], [
 	])
 ])
 
+AS_IF([test "x$enable_pam" = "xyes"], [
+	AS_IF([test "x$enable_static" = "xyes"], [
+		AS_IF([test "x$pam_explicit" = "xyes"], [
+			AC_MSG_ERROR([--enable-pam does not work with --enable-static, PAM dlopen()s its modules])], [
+			AC_MSG_NOTICE([PAM disabled for static build, PAM dlopen()s its modules])
+			enable_pam=no])])
+])
+AS_IF([test "x$enable_pam" = "xyes"], [
+	AC_CHECK_HEADER([security/pam_appl.h], [], [
+		AC_MSG_WARN([PAM headers not found, PAM support disabled])
+		enable_pam=no])
+	AS_IF([test "x$enable_pam" = "xyes"], [
+		AC_CHECK_LIB([pam], [pam_start], [
+			AC_DEFINE(HAVE_LIBPAM, 1, [Have Linux-PAM for per-service session support])
+			LIBS="$LIBS -lpam"
+		], [
+			AC_MSG_WARN([libpam not found, PAM support disabled])
+			enable_pam=no])])
+])
+
 AS_IF([test "x$enable_fastboot" = "xyes"], [
 	AC_DEFINE(FAST_BOOT, 1, [Skip fsck check on filesystems listed in /etc/fstab])])
 
@@ -257,6 +282,8 @@ AS_IF([test "x$enable_dbus" = "xyes"], [
 	AC_DEFINE(HAVE_DBUS, 1, [Build D-Bus support via libink])])
 AM_CONDITIONAL(DBUS, [test "x$enable_dbus" = "xyes"])
 
+AM_CONDITIONAL(PAM, [test "x$enable_pam" = "xyes"])
+
 ### With features ##############################################################################
 AS_IF([test "x$bash_dir" = "xyes"], [
 	PKG_CHECK_MODULES([BASH_COMPLETION], [bash-completion >= 2.0],
@@ -461,6 +488,7 @@ Optional features:
   Replacement libsystemd: $with_libsystemd
   Use cgroup v2.........: $enable_cgroup
   Use libcap............: $enable_libcap
+  Use PAM...............: $enable_pam
   Parse kernel cmdline..: $enable_kernel_cmdline
   Keep kernel logging...: $enable_kernel_logging
   Skip fsck check.......: $enable_fastboot

doc/ChangeLog.md

@@ -34,6 +34,10 @@ All relevant changes are documented in this file.
   same service, `command = { "/lib/systemd/systemd-udevd", "-udevd" }`,
   and Finit starts the first one it finds.  The line-based format could
   only express this by repeating the whole stanza per candidate
+- New `pam = "NAME"` setting for run/task/service/sysv blocks, runs the
+  service inside a PAM session set up from `/etc/pam.d/NAME`, so the `session`
+  stack applies to the process that becomes the daemon, e.g. limits from
+  `pam_limits`, which override a per-service `rlimit`.  Issue #420
 - Finit now ships with a built-in brokerless D-Bus implementation,
   **libink**, exposing the running init system as a peer on its own
   private bus at `/run/finit/bus`, and -- opportunistically --

doc/build.md

@@ -15,6 +15,11 @@ and `/dev/disk/by-label/` symlinks after.  keventd is enabled by
 default, so this is a hard requirement unless you build with
 `--without-keventd`.
 
+PAM session support for services is built by default.  It needs
+[Linux-PAM][] (-lpam); the build falls back to no PAM support when that
+library is missing.  A static build, `--enable-static`, disables PAM
+too, since libpam loads its modules with `dlopen()`.
+
 > [!IMPORTANT]
 > Most free/open source software packages that use `configure` default
 > to install to `/usr/local`.  However, some Linux distributions do no
@@ -54,6 +59,14 @@ Below are a few of the main switches to configure:
   built-ins (.o files) and all external libraries, except the C library
   will be linked statically.
 
+* `--disable-pam`: Opt out of Finit's built-in PAM session support,
+  enabled by default, which lets a service declare `pam = "name"` and
+  run inside a session set up from `/etc/pam.d/name`.  Needs libpam,
+  falls back to disabled when it is missing, and is also disabled for
+  `--enable-static` builds.  Asking for `--enable-pam` and
+  `--enable-static` together is an error rather than a fallback.  See
+  [PAM Sessions](config/pam.md)
+
 * `--enable-kernel-cmdline`: Enable Finit pre-4.1 parsing of init args from
   `/proc/cmdline`, this is *not recommended* since Finit may be running as the
   init for container apps that can see the host's `/proc` filesystem
@@ -272,3 +285,4 @@ it only for debugging start up issues when Finit crashes.
 [libite]:  https://github.com/troglobit/libite
 [libConfuse]: https://github.com/libconfuse/libconfuse
 [util-linux]: https://github.com/util-linux/util-linux
+[Linux-PAM]:  https://github.com/linux-pam/linux-pam

doc/config/capabilities.md

@@ -189,6 +189,9 @@ ps -o user,pid,cmd -p $(pidof nginx)
 - Services without `capabilities` use standard privilege dropping:
   - Services with a non-root `user` have no special capabilities
   - Services without `user` run as root with full capabilities
+- A capability granted by `pam_cap.so` in a [PAM session](pam.md) is
+  merged into this set, but only when `capabilities` is also set.
+  Without it the grant is lost when privileges drop
 - Some very old binaries may not work correctly with ambient capabilities
 - File system capabilities are not managed by Finit (use `setcap` for that)
 

doc/config/migration.md

@@ -261,7 +261,7 @@ Worth knowing
     $SYSLOGD_ARGS"` working with an `envfile`.
   * New settings only appear in the block format.  The first are the
     [per-service directories](service-opts.md#service-directories),
-    `runtime-dir` and friends.
+    `runtime-dir` and friends, and [`pam`](pam.md).
 
 For the full description of every key, see the rest of the
 [Configuration](index.md) section.

doc/config/pam.md

@@ -0,0 +1,151 @@
+PAM Sessions
+============
+
+`pam = "NAME"` runs a service inside a PAM session set up from
+`/etc/pam.d/NAME`.  The `session` stack in that file runs for the
+process that goes on to become the daemon, so modules like `pam_limits`,
+`pam_env`, or `pam_keyinit` see the service the way they see a login.
+
+## Basic Usage
+
+A display server that needs the session a login would have arranged for
+it:
+
+```conf
+service weston {
+    user    = "weston"
+    pam     = "weston-autologin"
+    command = "/usr/bin/weston --continue-without-input"
+}
+```
+
+With `/etc/pam.d/weston-autologin`:
+
+```
+auth     required  pam_permit.so
+account  required  pam_unix.so
+session  required  pam_unix.so
+session  required  pam_limits.so
+```
+
+The `auth` line is needed even though nothing is ever authenticated.
+Opening the session goes through `pam_setcred()`, which consults the
+`auth` stack, and an empty stack comes back as a permission denial, so a
+pam.d file with only `account` and `session` lines keeps the service
+from starting.
+
+The value names a file in `/etc/pam.d`, it is not a path.  A value
+holding `/` or `..`, or one too long to fit, is refused, with an error
+in the log when the .conf file is read.  The service does not start
+either, `initctl status` reports it as missing.  Like the per-service
+directory keys, `pam` exists in the block format only.
+
+## No Authentication
+
+Finit runs the account and session stacks, `pam_acct_mgmt()`,
+`pam_setcred()`, and `pam_open_session()`, and never
+`pam_authenticate()`.  A module that asks a question gets a
+conversation error back and its entry in the stack fails.
+
+A service whose account is denied, an expired account say, does not
+start, and neither does one naming a pam.d file that is not installed.
+The child exits 71 (`EX_OSERR`), `initctl status` shows the service as
+crashed, and PAM's own reason is in the log.
+
+## Requirements
+
+PAM support is built by default, see [Building Finit](../build.md).
+Without it, e.g. after `--disable-pam`, a service declaring `pam` is
+refused rather than started with the stacks skipped:
+
+    weston: pam weston-autologin requires Finit built with --enable-pam
+
+## Which Blocks Take It
+
+`service`, `task`, `run`, and `sysv`.  Not `tty`: `login` opens a
+session of its own there.
+
+Every fork gets its own session, so the `pre:`, `post:`, `ready:`, and
+`cleanup:` scripts each open and close one too, as do the stop and
+reload scripts and the `stop` call on a `sysv` script.
+
+A refused value stops those too.  A `pre:` script forks before the
+start-time check runs, so it exits 71 without running instead of the
+service being reported missing.
+
+## The User
+
+`user` decides who the session is for.  Without it the session is for
+root.
+
+systemd documents the opposite for its equivalent.  `systemd.exec(5)`
+says `PAMName=` is "only useful in conjunction with the `User=`
+setting, and is otherwise ignored".  That was true of systemd up to and
+including v256, v257 changed it to open a session for the manager's own
+user, and the man page was never updated.  Finit does what v257 does.
+
+A service with a [controlling tty](tty.md#controlling-tty-for-services)
+has it passed to PAM as `PAM_TTY`, for the modules that care which
+terminal a session is on.
+
+## Precedence
+
+Three places where PAM and a Finit setting cover the same ground:
+
+- `pam_limits` overrides a per-service `rlimit`.  A block asking for
+  `nofile = 4096` under a `limits.conf` that says 512 gets 512.
+- `pam_env` overrides Finit's own environment defaults, `PATH`, `USER`,
+  `LOGNAME`, and `HOME`, and `envfile` in turn overrides `pam_env`.  A
+  `HOME` from the session stack also moves the working directory, which
+  otherwise is the home directory from `/etc/passwd`.
+- The groups from `/etc/group` and `extra-groups` override `pam_group`.
+
+## The Session Keeper
+
+A helper is forked next to the service to close the session when the
+service exits, `(finit-pam)`:
+
+```
+     CGroup : /system/weston cpu 0 [100, max] mem [--.--, max]
+              |- 312 /usr/bin/weston --continue-without-input
+              `- 313 (finit-pam)
+```
+
+There is one per fork.  It runs as the service's user, in the service's
+cgroup, and stopping the service takes it along.
+
+A daemon that reaps children in its own `wait()` loop will see a child
+it never forked.  systemd has the same property, with `(sd-pam)`.
+
+## Limitations
+
+- `type = "forking"` closes the session early.  The initial process
+  exits by design, the keeper's parent-death signal fires with it, and
+  the session is closed while the real daemon runs on.  Finit warns
+  about the combination when it reads the .conf file, and starts the
+  service anyway:
+
+        /etc/finit.d/foo.conf: foo: pam with type = forking closes the
+        session when the initial process exits
+
+- A daemon whose initial thread exits while the process lives closes the
+  session the same way.  The parent-death signal follows the thread that
+  forked the keeper, not the process.
+- A capability granted by `pam_cap.so` is only kept when the service
+  also sets [`capabilities`](capabilities.md).
+- The keeper shares the service's cgroup, so an empty cgroup directory
+  can outlive a stop until the next start reuses it.  Cosmetic.
+- A module that blocks has no time bound.  `pam_open_session()` waits
+  for as long as the module does, `pam_ldap` against an unreachable
+  server, say, or `pam_mount` on a hung network mount.  The fork has already succeeded by then, so the service
+  reaches the running state and stays there with no daemon behind it.
+  Nothing crashes and nothing restarts.
+
+## See Also
+
+- [Service Options](service-opts.md) - the other run/task/service keys
+- [Linux Capabilities](capabilities.md) - the key `pam_cap.so` needs
+- [Building Finit](../build.md) - `--disable-pam` and its dependency
+- [pam(8)](https://man7.org/linux/man-pages/man8/pam.8.html) - the PAM library
+- [pam.d(5)](https://man7.org/linux/man-pages/man5/pam.d.5.html) - the file format
+- [pam_limits(8)](https://man7.org/linux/man-pages/man8/pam_limits.8.html) - limits from `limits.conf`

doc/config/runlevels.md

@@ -160,6 +160,9 @@ albeit deprecated.
 each `/etc/finit.d/*.conf` read.  I.e., a set of task/run/service
 blocks can share the same rlimits if they are in the same .conf.
 
+For a service with [`pam`](pam.md), `pam_limits` runs after these
+limits are applied, so `limits.conf` has the last word.
+
 Miscellaneous Settings
 ----------------------
 

doc/config/service-env.md

@@ -27,6 +27,9 @@ the `ps` command we can see that the process is started with:
     foo -n --extra-arg=bar -s -x
 
 > [!NOTE]
+For a service with [`pam`](pam.md), the session environment is applied
+before `envfile`, so the file overrides anything `pam_env` set.
+
 > The leading `-` on `envfile` determines if Finit should treat a
 > missing environment file as blocking the start of the service or not.
 > When `-` is used, a missing environment file does *not* block the

doc/config/service-opts.md

@@ -56,6 +56,7 @@ Other run/task/service settings are:
   * `log {}` -- see [Redirecting Output](logging.md#redirecting-output)
   * `tty` -- see [Controlling TTY](tty.md#controlling-tty-for-services)
   * `notify` -- see [Service Synchronization](service-sync.md)
+  * `pam` -- see the [PAM Sessions](pam.md) section
   * `if` -- see [Conditional Execution](services.md#conditional-execution)
   * `type = "forking"` -- see description of the [service](services.md) block
   * a leading `-` on `command` -- see

doc/features.md

@@ -178,6 +178,26 @@ See the [Linux Capabilities](config/capabilities.md) section for detailed
 information, examples, and security best practices.
 
 
+**PAM Sessions**
+
+A service can run inside a PAM session, so the `session` stack in
+`/etc/pam.d` applies to it, e.g. limits from `pam_limits`:
+
+```conf
+service weston {
+    user    = "weston"
+    pam     = "weston-autologin"
+    command = "/usr/bin/weston --continue-without-input"
+}
+```
+
+Without a `user` the session is for root.  Requires a build with PAM
+support, which is the default; see `--disable-pam`.
+
+See the [PAM Sessions](config/pam.md) section for the pam.d file the
+example needs, and for how PAM and Finit settings interact.
+
+
 **Supplementary Groups**
 
 Finit supports supplementary groups for services, allowing them to access

mkdocs.yml

@@ -39,6 +39,7 @@ nav:
     - Logging: config/logging.md
     - Cgroups: config/cgroups.md
     - Capabilities: config/capabilities.md
+    - PAM Sessions: config/pam.md
     - Templating: config/templating.md
     - SysV Compatibility: config/sysv.md
     - Rescue Mode: config/rescue.md

src/Makefile.am

@@ -76,6 +76,9 @@ endif
 if DBUS
 finit_SOURCES     += dbus.c
 endif
+if PAM
+finit_SOURCES     += pam.c pam.h
+endif
 
 pkginclude_HEADERS = cgroup.h cond.h conf.h finit.h helpers.h log.h \
 		     plugin.h svc.h service.h