Add a Login Issue Banner with pam_issue

Compliance wants a warning banner before every console login, and pam_issue is the PAM module for that job. It puts a chosen text file in front of the username prompt. This guide uses the installed Linux-PAM module version from libpam-modules:amd64 1.5.3-5ubuntu5.7. Allow about ten minutes, plus a separate maintenance window if the target is a production login service.

You need root access to edit /etc/pam.d/login and a second login session standing by for recovery. The examples only touch the login service: they do not configure SSH, graphical login managers or any other PAM-aware application.

1. Check the module and target service

Confirm the module shipped by the installed package actually exists, then look at the PAM file before changing it. These are read-only:

$ dpkg-query -W -f='${Package} ${Version}\n' libpam-modules:amd64
libpam-modules 1.5.3-5ubuntu5.7
$ test -r /usr/lib/x86_64-linux-gnu/security/pam_issue.so && echo 'pam_issue is installed'
pam_issue is installed
$ grep -n 'pam_issue' /etc/pam.d/login
13:# auth       required   pam_issue.so issue=/etc/issue

The shipped module only provides the auth PAM type. A file under /etc/pam.d/ has no service field of its own, so the filename is what selects the service, and the installed login file already has a commented example line ready to build on.

2. Prepare a deliberately small issue file

Create a simple root-owned file:

$ sudo install -o root -g root -m 0644 /dev/null /etc/issue-login
$ sudo sh -c 'printf "%s\n" "Authorised access only." "This system is monitored." > /etc/issue-login'
$ sudo sed -n '1,2p' /etc/issue-login
Authorised access only.
This system is monitored.

The first command creates or truncates the file, so check the path before you press enter. To undo this example later, replace the file with your approved banner text, or remove it entirely with sudo rm -- /etc/issue-login once the PAM reference to it is gone.

3. Add the PAM rule

Back up the file before you touch the authentication stack, and keep a root shell or console login open while you test. If the edit breaks login, that session is how you get back in.

$ sudo cp -p /etc/pam.d/login /etc/pam.d/login.before-pam-issue
$ sudoedit /etc/pam.d/login

Add this line near the other auth rules, or uncomment the matching packaged example:

auth       optional   pam_issue.so issue=/etc/issue-login

Naming issue=/etc/issue-login explicitly avoids relying on whatever the distribution default happens to be, since the local manual does not state it. optional means a failure from this banner module will not usually decide the overall authentication result while other auth modules are present. Leave every other module's control flag exactly as you found it.

$ grep -nF 'pam_issue.so issue=/etc/issue-login' /etc/pam.d/login
13:auth       optional   pam_issue.so issue=/etc/issue-login
$ sudo test -r /etc/issue-login && echo 'issue file is readable'
issue file is readable

4. Test without locking yourself out

Open a new virtual terminal or a separate console login and watch for the banner ahead of the username prompt; the exact formatting there belongs to login, not to pam_issue itself. No spare session to test with means no deploying this yet.

A working test shows both issue lines before the prompt. The module returns PAM_SUCCESS when it sets the new prompt, or PAM_IGNORE if the prompt was already changed by something else, which is a reason to check the module ordering rather than pile on a duplicate rule.

Banner not showing up? Check which service you actually tested, the rule's spelling and the file's permissions. A rule in /etc/pam.d/login has no effect on SSH. Only dig into system logs after the configuration line and the file itself both check out.

5. Add escape codes only when you need them

By default, pam_issue parses getty-style backslash escapes: \d for the day, \t for the time, \n for the host name, \l for the terminal, \m for the architecture and \U for the logged-in user count with the right singular or plural.

For example, this banner sticks to general system information:

$ sudo sh -c 'printf "%s\n" "\n" "\U currently logged in" "Login time: \t" > /etc/issue-login'

Check the result on a real test login before shipping it. Hostname, OS release and terminal details all leak information to someone who has not authenticated yet. To show the file literally, backslashes and all, add noesc to the rule:

auth       optional   pam_issue.so noesc issue=/etc/issue-login

Do not accidentally combine escape-producing text with noesc: it stops parsing entirely, it does not let you escape one particular line.

6. Recover from a failed change

If a test login fails or behaves oddly, use the root shell you kept open. Restore the known-good copy, check it, then test again:

$ sudo cp -p /etc/pam.d/login.before-pam-issue /etc/pam.d/login
$ grep -n 'pam_issue' /etc/pam.d/login
13:# auth       required   pam_issue.so issue=/etc/issue

Start a fresh ordinary login to confirm the recovery worked. To drop the banner for good, remove the PAM rule first and only then delete /etc/issue-login. Deleting the file while a required PAM rule still points at it is asking for trouble.