From 95ad4868ac1f52f3d9c923e24f3d8c45dce6bb03 Mon Sep 17 00:00:00 2001
From: Eric Biggers <ebiggers@google.com>
Date: Fri, 7 Aug 2020 16:37:05 -0700
Subject: [PATCH] README.md: recommend 'sudo make install PREFIX=/usr' on
 Ubuntu (#244)

Ubuntu's PAM configuration framework only recognizes files in /usr, not
/usr/local.  So for installs from source, unfortunately we have to
recommend installing to /usr, despite this not being conventional.

Resolves https://github.com/google/fscrypt/issues/240
---
 README.md | 42 ++++++++++++++++++++++++++----------------
 1 file changed, 26 insertions(+), 16 deletions(-)

diff --git a/README.md b/README.md
index 9f80c7d1..eeee3203 100644
--- a/README.md
+++ b/README.md
@@ -130,19 +130,23 @@ Once all the dependencies are installed, you can get the repository by running:
 ```shell
 go get -d github.com/google/fscrypt/...
 ```
-Running `make` in `$GOPATH/src/github.com/google/fscrypt` builds the
-executable (`fscrypt`) and PAM module (`pam_fscrypt.so`) in the `bin/`
-directory. Use `make bin/fscrypt` or `make bin/pam_fscrypt.so`
-to build only one.
+Running `make` in `$GOPATH/src/github.com/google/fscrypt` builds the binary
+(`fscrypt`) and PAM module (`pam_fscrypt.so`) in the `bin/` directory.
 
-Running `sudo make install` installs `fscrypt` to `/usr/local/bin`,
-`pam_fscrypt.so` to `/usr/local/lib/security`, and `pam_fscrypt/config` to
-`/usr/local/share/pam-configs`. Use `make install-bin` to only install
-`fscrypt`. Use `make install-pam` to only install the pam files.
+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`.
 
-See the `Makefile` for instructions on how to customize the build (e.g. installing
-to a custom location, using different build flags, building a static binary,
-etc ...)
+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`.
+
+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.
 
 Alternatively, if you only want to install the `fscrypt` binary to
 `$GOPATH/bin`, simply run:
@@ -150,6 +154,8 @@ Alternatively, if you only want to install the `fscrypt` binary to
 go get github.com/google/fscrypt/cmd/fscrypt
 ```
 
+See the `Makefile` for instructions on how to further customize the build.
+
 ## Runtime Dependencies
 
 To run, `fscrypt` needs the following libraries:
@@ -332,12 +338,16 @@ passphrase.
 
 #### Enabling the PAM module on Ubuntu
 
-Both the official `fscrypt` package for Ubuntu and `sudo make install`
-will install a configuration file for [Ubuntu's PAM configuration
+The official `fscrypt` package for Ubuntu will install a configuration file for
+[Ubuntu'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.
+`/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.
+
+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`.
 
 #### Enabling the PAM module on Arch Linux