Add a Login Issue Banner with pam_issue

You will finish with a PAM login configuration that places a chosen issue file before 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 you are changing a production login service.

You need root access to edit /etc/pam.d/login and the ability to open a second login session for recovery. The examples only affect the login service. They do not configure SSH, graphical login managers or every PAM-aware application.

1. Check the module and target service

Confirm that the module supplied by the installed package exists, then inspect the PAM file you intend to change. These are read-only commands:

$ 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 supplied module provides only the auth PAM type. A file in /etc/pam.d/ omits the service field, so the filename selects the service. The installed login file already documents a commented example, which is a useful starting point.

2. Prepare a deliberately small issue file

Do not put passwords, private host details or operational secrets in an issue banner. It is displayed before authentication and may be visible to anyone who can reach the login prompt. Create a simple root-owned file with elevated privileges:

$ 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. That is a destructive change to the file contents, so check the path before pressing Enter. To undo this example later, replace the file with your approved banner or remove it with sudo rm -- /etc/issue-login after removing the PAM reference.

3. Add the PAM rule

Make a backup before editing the authentication stack. Keep an existing root shell or console login open while testing. If the edit breaks authentication, that session is your recovery path.

$ 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

issue=/etc/issue-login selects the file explicitly. The module's documented default is not stated in the local manual, so being explicit avoids relying on a distribution default. optional means a failure from this banner module does not normally decide the authentication result when other auth modules are present. Do not change another module's control flag while making this edit.

Checkpoint: verify the line and the file without starting a login attempt:

$ 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 local virtual terminal or a separate console login and watch for the banner before the username prompt. The exact terminal and prompt formatting belong to login, not pam_issue. If you cannot test a separate session, do not deploy this change yet.

A normal successful test should show the two issue lines before the username prompt. The module returns PAM_SUCCESS when it sets the new prompt. If the prompt was already changed, it can return PAM_IGNORE; that is a reason to inspect the PAM stack and module ordering rather than blindly adding duplicate rules.

If the banner does not appear, check the service you tested, the rule spelling and the file permissions. A rule in /etc/pam.d/login does not automatically affect SSH. Check system logs only after confirming the configuration line and selected file.

5. Add escape codes only when you need them

By default, pam_issue parses getty-style escapes beginning with a backslash. The useful ones include \d for the current day, \t for the current time, \n for the host name, \l for the terminal name, \m for the machine architecture and \U for the logged-in user count with the correct singular or plural word.

For example, this banner contains only general system information:

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

Review the result on a test login before using it. Hostname, operating system release and terminal details can disclose information to an unauthenticated user. If the file must be shown literally, including backslash sequences, add noesc to the PAM rule:

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

Do not use both an escape-producing design and noesc by accident. It is an option to stop parsing, not a way to escape a particular line.

6. Recover from a failed change

If a test login fails or the service behaves unexpectedly, use the still-open root shell. Restore the known-good copy, check the file, and 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 recovery. If you no longer need the banner, remove the PAM rule and then remove /etc/issue-login. Never delete the file first while leaving a required PAM rule pointing at it.