Fix #420: run services inside a PAM session

Apply a PAM session to run/task/sysv/services Finit starts, pam_limits
above all, so a service running as a given user picks up that user's
limits the way a login does.

Add a new `pam` setting for the new block format (only), like the
per-service directories, naming a file in /etc/pam.d:

    service weston {
        user    = "weston"
        pam     = "weston-autologin"
        command = "/usr/bin/weston --continue-without-input"
    }

pam_close_session() has to be called by a process still holding the
handle, and the handle does not survive exec().  Hence the keeper: it
holds the handle, drops to the service's credentials, and waits for a
parent-death signal before closing the session.  Same shape as
systemd's (sd-pam), for the same reason, and one per fork, so the
script hooks open and close their own.

The keeper closes the descriptors it inherited from Finit and only
those.  Closing everything would also take out what pam_open_session()
opened for itself, a keyring fd or a lock file, and leave the modules
to close a session with those pulled out from under them.  Closing
nothing, as (sd-pam) does, would leave it holding the write end of the
notify pipe for the service's whole lifetime and starve notify = "s6"
services of their ready signal.  So the fds open before pam_start()
are snapshotted and exactly those are closed, while the ones PAM opens
after are marked close-on-exec so the daemon does not inherit them
either.

A refused value, a denied account stack, an uninstalled pam.d file,
and a build without PAM support all keep the service from starting
rather than running it with the stacks skipped: one that quietly loses
pam_limits and its private /tmp, with nothing said.  Capabilities a
module like pam_cap.so granted are merged into the IAB Finit applies
instead of being replaced by it, which only helps a service that also
sets capabilities, the other arm being a plain setuid() with nothing
left to restore once permitted is empty.

The test sysroot gains pam_permit.so, pam_deny.so and pam_limits.so,
which ldd cannot see, libpam dlopen()s them, and the test skips when
the host has none to stage.  The negative cases pin the exit status
rather than only asserting crashed, which serv reports for any early
exit, so a bad command or an unwritable pidfile cannot pass for a
rejected session.

Signed-off-by: Joachim Wiberg <troglobit@gmail.com>

doc/ChangeLog.md

@@ -85,6 +85,10 @@ All relevant changes are documented in this file.
   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 -- registering `org.finit` on the

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
@@ -285,3 +298,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