Check and Clear Timestamps with pam_timestamp_check

pam_timestamp_check answers one narrow question: is the PAM timestamp for an authenticated user still valid. You will also learn how to clear that timestamp and how to tell a real result apart from a broken installation. Allow about ten minutes. You need a shell account, the libpam-modules-bin package, and a PAM configuration that uses pam_timestamp.

This guide describes the installed Ubuntu package libpam-modules-bin 1.5.3-5ubuntu5.7. The local manual page is dated 7 May 2023. The command's timestamp is created by the pam_timestamp PAM module, not by this checker alone.

1. Confirm the command and its privilege boundary

Start by checking which executable will run and whether it has the privilege bit the program requires:

$ command -v pam_timestamp_check
/usr/sbin/pam_timestamp_check
$ stat -c '%A %U %G %n' /usr/sbin/pam_timestamp_check
-rwsr-xr-x root root /usr/sbin/pam_timestamp_check

The exact stat line varies with local ownership and permissions. The detail that matters is the s in the owner execute position, shown above as rws. The manual says the program returns status 2 when it is not setuid root. On this machine the packaged file is currently not setuid, so an ordinary check prints pam_timestamp_check must be setuid root and returns 2. That is an installation or packaging condition, not evidence that a timestamp has expired.

2. Check the default timestamp

With a correctly installed executable, run the command without options:

$ pam_timestamp_check
$ printf 'exit status: %s\n' "$?"
exit status: 0

Status 0 means the default timestamp is valid. The command normally has no success message, so capture its status immediately: running another command before printf replaces the status you actually need.

A status of 7 means the timestamp is not valid, which can mean it expired, was never created, or does not match the user and target being checked. The checker does not ask for a password and does not create a fresh timestamp; a PAM-aware application has to perform the authentication flow that creates one.

$ if pam_timestamp_check; then
>     echo 'PAM timestamp is valid'
> else
>     rc=$?
>     echo "PAM timestamp check failed with status $rc"
> fi

3. Check a timestamp for another target user

By default, the command checks the timestamp for the user being authenticated as themselves. When PAM authenticates as a different user, the timestamp file uses a different name, so pass that target account as the final argument:

$ pam_timestamp_check root
$ printf 'root target status: %s\n' "$?"
root target status: 7

Replace root with the account the PAM transaction actually targets. A status of 7 here is only an example result: your machine may return 0, 7, or an error caused by its own PAM and timestamp state. Do not treat a check for one target user as a check for every account.

Use the target account the calling PAM service actually requests. Guessing the account name is a common distraction when troubleshooting a command that sometimes prompts and sometimes does not.

4. Clear the timestamp

Use -k when you deliberately want to remove the selected timestamp instead of checking it:

$ pam_timestamp_check -k
$ printf 'clear exit status: %s\n' "$?"
clear exit status: 0

$ pam_timestamp_check -k root
$ printf 'root clear exit status: %s\n' "$?"
root clear exit status: 0

If the command fails, do not assume the timestamp was removed. Check the returned status and investigate before starting a task that depends on re-authentication. There is no undo command for restoring the old timestamp; the practical recovery is to authenticate again through the relevant PAM application, letting pam_timestamp create a new timestamp when its configuration permits that.

5. Watch validity continuously when troubleshooting

The -d option turns the command from a one-shot exit-status check into a polling loop, printing the status on standard output and continuing indefinitely:

$ pam_timestamp_check -d
valid
valid
invalid

The exact output and timing depend on the installed implementation and timestamp state. Stop the loop with Ctrl-C. Use a short terminal session for diagnosis, never a service or unattended job, since the command is designed to keep polling until interrupted.

Do not combine -d with a script expecting one exit status and immediate completion. For a single answer, omit -d and test the exit status instead.

6. Interpret failures without changing configuration

The documented return values are useful when a shell message is too vague:

The timestamp files live below /var/run/sudo/... according to the manual page. Do not edit or delete files there by hand: their names and layout are implementation details, and manual changes can produce confusing results. Use -k for a supported removal instead.