Goal

When a user logs in using SSH an email should be sent.

Intro

There are different ways to send an email when someone logs into a machine using SSH. One way could be to parse the auth log file periodically, but this is error prone and rather complex. An easier way is to call a script, that is hooked into PAM, the central authentication service on Linux systems.

The Pluggable Authentication Modules (PAM) [1] is the central authentication system for modern Linux distributions like Debian and Gentoo. Usually PAM is part of the minimal installation. PAM is used by applications which need to authenticate a user (i.e. the SSH daemon or sudo) and authentication services like Kerberos or the Unix login system which uses htpasswd. PAM manages authentication centrally by providing configuration files in which rule sets for the authentication process can be defined. As PAM already centralizes all authentication systems, it is the perfect place to hook in a script.

Configuration

The PAM configuration files usually reside in /etc/pam.d/. If for example the SSH daemon needs to authenticate a user, PAM first looks up, if a file named sshd is located in the configuration directory. If it is found, the rules are evaluated and the user gets authenticated. If the file is not found the default configuration file is looked up, named others. In case this file does not exist the defaults, which are compiled into PAM are used. Configuration files can also include other configuration files and Gentoo for example organizes them into categories like remote login, local login and so on. More on that topic can be found in the PAM documentation (c.f. [2]).

PAM uses several modules, which provide different services, like displaying the Message of the Day (MotD) or checking the password. The module pam_exec can be used to execute shell code, i.e. to call a shell script.

Version

According to [3] at least PAM in version 1.1 is needed for pam_exec to work. This is the case in Debian Squeeze (v 1.1.1) [4] and the current Gentoo ebuild (v 1.1.3) [5], but not in Debian Lenny (v 1.0.1) [6]. In Gentoo pam_exec is contained in the sys-libs/pam package, on Debian an extra package libpam-modules needs to be installed.

Example

session optional pam_exec.so /usr/local/bin/send-mail-on-ssh-login.sh

If the above line is appended to /etc/pam.d/sshd the script in /usr/local/bin/send-mail-on-ssh-login.sh will be executed, if a SSH session is opened. pam_exec also passes some environment variables, which can be read by the script. More can be found in [2] section 6.7.

An example for /usr/local/bin/send-mail-on-ssh-login.sh could be:

#!/bin/sh
if [ "$PAM_TYPE" != "open_session" ]
then
  exit 0
else
  {
    echo "User: $PAM_USER"
    echo "Remote Host: $PAM_RHOST"
    echo "Service: $PAM_SERVICE"
    echo "TTY: $PAM_TTY"
    echo "Date: `date`"
    echo "Server: `uname -a`"
  } | mail -s "$PAM_SERVICE login on `hostname -s` for account $PAM_USER" root
fi
exit 0

Finally make sure to set the execution bit of the script.

Going further

With pam_exec of course other scripts besides the short email script could be executed. Another possibility is to define the configuration line in sshd also for other services.

Data privacy

Sending emails on login may conflict with data privacy on multiuser systems. This can be circumvented by just sending emails for specific users or root (if at all accessible via SSH).

Resources

• [1] PAM Website (Offline, Web Server Directory shown)
• [2] PAM Documentation (Offline)
• [3] Login notifications, pam_exec scripting
• [4] Debian Squeeze libpam-modules
• [5] Debian Lenny libpam-modules
• [6] Gentoo sys-libs/pam ebuild

Updates

16.4.2012: Link [1] and [2] are down. No current source found.