'\" t
.\"     Title: pam_matrix
.\"    Author: [FIXME: author] [see http://docbook.sf.net/el/author]
.\" Generator: DocBook XSL Stylesheets v1.78.1 <http://docbook.sf.net/>
.\"      Date: 2015-11-04
.\"    Manual: \ \&
.\"    Source: \ \&
.\"  Language: English
.\"
.TH "PAM_MATRIX" "8" "2015\-11\-04" "\ \&" "\ \&"
.\" -----------------------------------------------------------------
.\" * Define some portability stuff
.\" -----------------------------------------------------------------
.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.\" http://bugs.debian.org/507673
.\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html
.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\" -----------------------------------------------------------------
.\" * set default formatting
.\" -----------------------------------------------------------------
.\" disable hyphenation
.nh
.\" disable justification (adjust text to left margin only)
.ad l
.\" -----------------------------------------------------------------
.\" * MAIN CONTENT STARTS HERE *
.\" -----------------------------------------------------------------
.SH "NAME"
pam_matrix \- A PAM test module to retrieve module\-specific PAM items
.SH "SYNOPSIS"
.sp
pam_matrix\&.so [\&...]
.SH "DESCRIPTION"
.sp
Testing PAM application often requires to set up an authentication backend with as little effort as possible\&. The \fBpam_matrix\fR module allows to authenticate against a key\-value text file, provided by an option or with an environment variable\&.
.SH "IMPORTANT"
.sp
pam_matrix is a \fBtest tool\fR\&. It should be considered completely insecure and never used outside test environments! As you\(cqll see when reading description of the options and actions, many of them don\(cqt make any sense in the real world and were added just to make tests possible\&.
.SH "PASSWORD DATABASE"
.sp
The pam_matrix module authenticates user against a plain\-text CSV file\&. The format of the file is as follows:
.sp
.if n \{\
.RS 4
.\}
.nf
username:password:allowed_service
.fi
.if n \{\
.RE
.\}
.sp
Example: User bob allowed to authenticate with the service sshd
.sp
.if n \{\
.RS 4
.\}
.nf
bob:secret:sshd
.fi
.if n \{\
.RE
.\}
.SH "OPTIONS"
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
\fBpassdb=/path/to/file\fR
\- the patch to the password database\&. If the database is not provided with this module option, pam_matrix\&.so reads the PAM_MATRIX_PASSWD environment variable and tries to load the file from there\&. If that fails as well, PAM_AUTHINFO_UNAVAIL is returned\&.
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
\fBecho\fR
\- if this option is provided, pam_matrix\&.so will ask for password using PAM_PROMPT_ECHO_ON, that is, the password will be echoed back to user\&. This option was added to make it possible to test conversation functions better\&.
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
\fBverbose\fR
\- if this option is provided, pam_matrix\&.so will display a PAM_TEXT_INFO message when authentication succeeds and a PAM_ERROR_MSG when authentication fails\&. This option was added to make it possible to test conversation functions better\&.
.RE
.SH "MODULE TYPES PROVIDED"
.sp
All module types (\fBaccount\fR, \fBauth\fR, \fBpassword\fR and \fBsession\fR) are supported\&.
.sp
The \fBauth\fR module searches for the user in the passdb file and compares the provided password with the one in the passdb file\&.
.sp
The \fBpassword\fR module is able to update the password in the passdb file\&.
.sp
The \fBaccess\fR module compares the service name the PAM conversation was invoked with the allowed service for the user as set in the passdb file\&.
.sp
The \fBsession\fR module sets the HOMEDIR PAM environment variable to "/home/%u" where %u stands for the user who opens the session\&. The variable is unset on session close\&.
.SH "EXAMPLE"
.sp
.if n \{\
.RS 4
.\}
.nf
auth        required    pam_matrix\&.so passdb=/tmp/passdb verbose
account     required    pam_matrix\&.so passdb=/tmp/passdb verbose
password    required    pam_matrix\&.so passdb=/tmp/passdb verbose
session     required    pam_matrix\&.so passdb=/tmp/passdb verbose
.fi
.if n \{\
.RE
.\}