Skip to content

Commit

Permalink
README: improve PAM configuration documentation (again)
Browse files Browse the repository at this point in the history
Make some more corrections:

- pam-config-framework isn't actually Ubuntu-specific but actually
  applies to Debian and any Debian derivative.

- The pam-config-framework file is indeed installed by `make install`,
  just not into the correct location.

- On Debian (and Debian derivatives), the PAM configuration isn't
  actually part of the 'fscrypt' package but rather 'libpam-fscrypt'.

- Clarify where to add the pam_fscrypt.so session hook.
  • Loading branch information
ebiggers committed Mar 3, 2021
1 parent 3cdb794 commit 91ee1a7
Showing 1 changed file with 19 additions and 16 deletions.
35 changes: 19 additions & 16 deletions README.md
Expand Up @@ -40,7 +40,7 @@ native encryption. See [Runtime Dependencies](#runtime-dependencies).
- [Setting up for login protectors](#setting-up-for-login-protectors)
- [Securing your login passphrase](#securing-your-login-passphrase)
- [Enabling the PAM module](#enabling-the-pam-module)
- [Enabling the PAM module on Ubuntu](#enabling-the-pam-module-on-ubuntu)
- [Enabling the PAM module on Debian or Ubuntu](#enabling-the-pam-module-on-debian-or-ubuntu)
- [Enabling the PAM module on Arch Linux](#enabling-the-pam-module-on-arch-linux)
- [Enabling the PAM module on other Linux distros](#enabling-the-pam-module-on-other-linux-distros)
- [Allowing `fscrypt` to check your login passphrase](#allowing-fscrypt-to-check-your-login-passphrase)
Expand Down Expand Up @@ -169,13 +169,14 @@ Running `sudo make install` installs `fscrypt` into `/usr/local/bin`,
`pam_fscrypt.so` into `/usr/local/lib/security`, and `pam_fscrypt/config` into
`/usr/local/share/pam-configs`.

For Ubuntu, use `sudo make install PREFIX=/usr` to install into `/usr` instead
of the default of `/usr/local`. Ordinarily you shouldn't manually install
software into `/usr`, since `/usr` is reserved for Ubuntu's own packages.
However, Ubuntu only recognizes PAM configuration files in `/usr`, not in
`/usr/local`. This means that the PAM module will only work if you install into
`/usr`. Note: if you later decide to switch to using the Ubuntu package for
`fscrypt`, you'll have to first manually run `sudo make uninstall PREFIX=/usr`.
On Debian (and Debian derivatives such as Ubuntu), use `sudo make install
PREFIX=/usr` to install into `/usr` instead of the default of `/usr/local`.
Ordinarily you shouldn't manually install software into `/usr`, since `/usr` is
reserved for Debian's own packages. However, Debian's PAM configuration
framework only recognizes configuration files in `/usr`, not in `/usr/local`.
Therefore, the PAM module will only work if you install into `/usr`. Note: if
you later decide to switch to using the Debian package `libpam-fscrypt`, you'll
have to first manually run `sudo make uninstall PREFIX=/usr`.

It is also possible to use `make install-bin` to only install the `fscrypt`
binary, or `make install-pam` to only install the PAM files.
Expand Down Expand Up @@ -368,18 +369,18 @@ directories to be automatically unlocked when you log in (and be automatically
locked when you log out), and for login passphrase-protected directories to
remain accessible when you change your login passphrase.

#### Enabling the PAM module on Ubuntu
#### Enabling the PAM module on Debian or Ubuntu

The official `fscrypt` package for Ubuntu will install a configuration file for
[Ubuntu's PAM configuration
The official `libpam-fscrypt` package for Debian (and Debian derivatives such as
Ubuntu) will install a configuration file for [Debian's PAM configuration
framework](https://wiki.ubuntu.com/PAMConfigFrameworkSpec) to
`/usr/share/pam-configs/fscrypt`. This file contains reasonable defaults for
the PAM module. To automatically apply these defaults, run `sudo
pam-auth-update` and follow the on-screen instructions.
the PAM module. To automatically apply these defaults, run
`sudo pam-auth-update` and follow the on-screen instructions.

This file also gets installed if you build and install `fscrypt` from source,
but only if you use `make install PREFIX=/usr` to install into `/usr` instead of
the default of `/usr/local`.
but it is only installed to the correct location if you use `make install
PREFIX=/usr` to install into `/usr` instead of the default of `/usr/local`.

#### Enabling the PAM module on Arch Linux

Expand Down Expand Up @@ -418,7 +419,9 @@ line:
```
session optional pam_fscrypt.so
```
after `pam_unix.so` in `/etc/pam.d/common-session` or similar.
after `pam_unix.so` in `/etc/pam.d/common-session` or similar, but before
`pam_systemd.so` or any other module that accesses the user's home directory or
starts processes which access the user's home directory during their session.

`pam_fscrypt.so` accepts several options:

Expand Down

0 comments on commit 91ee1a7

Please sign in to comment.