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:

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. 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 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.
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.