PAM-MySQL

Until some up-to-date document is ready, we provide several old documents for reference.

Introduction

This is a successor of the "old" pam_mysql module, which comes with a more stable, secure and robust implementation.

Prerequisites

To try this module, you need the following stuff:

• A *NIX system, in which PAM facility is set up and working either system-wide or in a chroot jail.
• A MySQL server, up and running.

Available options

The module options are listed below with default in ()s:

verbose (0)

If set to 1, produce logs with detailed messages that describes what pam-mysql is doing. May be useful for debugging.

user

The user name used to open the specified MySQL database.

passwd

The password used to open the specified MySQL database.

host

The host name or absolute path to the unix socket where the MySQL server is listening. The following formats are accepted:

1. absolute path to the unix socket (e.g. /tmp/mysql.sock)
2. host name (e.g. somewhere.example.com)
3. host name + port number (e.g. somewhere.example.com:3306)

db

The name of the database that contains a user-password table.

table

The name of table that maps unique login names to the passwords. This can be a combination of tables with full JOIN syntax if you need more control. For example:

[table=Host LEFT JOIN HostUser ON HostUser.host_id=Host.id \
           LEFT JOIN User ON HostUser.user_id=User.id]
    

update_table

The name of the table used for password alteration. If not defined, the value of the "table" option will be used instead. This is handy if you have a complex JOIN instead of a simple table in the "table" option above.

usercolumn

The name of the column that contains a unix login name field. Should be in a fully qualified form.

passwdcolumn

The name of the column that contains a (encrypted) password string. Should be in a fully qualified form.

statcolumn

The name of the column that indicates the status of the user. Should be in a fully qualified form.

crypt (0)

Specifies the method to encrypt the user's password:

• 0 (or "plain") = No encryption. Passwords stored in plaintext. HIGHLY DISCOURAGED.
• 1 (or "Y") = Use crypt(3) function
• 2 (or "mysql") = Use MySQL PASSWORD() function. It is possible that the encryption function used by pam-mysql is different from that of the MySQL server, as pam-mysql uses the function defined in MySQL's C-client API instead of using PASSWORD() SQL function in the query.
• 3 (or "md5") = Use MySQL MD5() function

md5 (false)

If set to "true", use MD5 by default for crypt(3) hash. Only meaningful when crypt is set to "Y".

where

Specifies additional criteria for the query. For example:

[where=Host.name="web" AND User.active=1]
      

sqllog

If set to either "true" or "yes", SQL logging is enabled.

logtable

The name of the table to which logs are written.

logmsgcolumn

The name of the column in the log table to which the description of the log entry is stored.

logusercolumn

The name of the column in the log table to which the name of the user being authenticated is stored.

logpidcolumn

The name of the column in the log table to which the pid of the process utilising the pam_mysql's authentication service is stored.

loghostcolumn

The name of the column in the log table to which the hostname of the machine where the authentication is performed is stored.

logtimecolumn

The name of the column in the log table to which the timestamp of the log entry is stored.

config_file (note: available in 0.7, not in 0.6!)

Path to a NSS-MySQL style configuration file which enumerates the options per line. Acceptable option names and the counterparts in the PAM-MySQL are listed below:

Name	Counterpart
users.host	host
users.database	db
users.db_user	user
users.db_passwd	passwd
users.where_clause	host
users.table	table
users.update_table	update_table
users.user_column	usercolumn
users.password_column	passwdcolumn
users.status_column	statcolumn
users.password_crypt	crypt
users.use_md5	md5
users.where_clause	where
verbose	verbose
log.enabled	sqllog
log.table	logtable
log.message_column	logmsgcolumn
log.pid_column	logpidcolumn
log.user_column	logusercolumn
log.host_column	loghostcolumn
log.time_column	logtimecolumn

Bugs

Beware that user names and clear text passwords may be logged to mysql.log if you explicitly configured pam-mysql to log select statements. (Not sure why you want to anyway, slogs your system down badly!)