'\" t
.\"     Title: pam_wrapper
.\"    Author: The Samba Team
.\" Generator: DocBook XSL Stylesheets vsnapshot <http://docbook.sf.net/>
.\"      Date: 2020-01-31
.\"    Manual: \ \&
.\"    Source: \ \&
.\"  Language: English
.\"
.TH "PAM_WRAPPER" "1" "2020\-01\-31" "\ \&" "\ \&"
.\" -----------------------------------------------------------------
.\" * 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_wrapper \- A preloadable wrapper to test PAM applications and PAM Modules
.SH "SYNOPSIS"
.sp
LD_PRELOAD=libpam_wrapper\&.so PAM_WRAPPER=1 PAM_WRAPPER_SERVICE_DIR=/path_to_config \fB\&./myapplication\fR
.SH "DESCRIPTION"
.sp
This tool allows you to either test your PAM application or module\&. For testing PAM applications we have written a simple PAM module called pam_matrix (see below)\&. If you plan to test a PAM module you can use the pamtest library we have implemented\&. It simplifies testing of modules\&. You can be combine it with the cmocka unit testing framework or you can use the provided Python bindings to write tests for your module in Python\&.
.SH "ENVIRONMENT VARIABLES"
.sp
pam_wrapper is activated and controlled by environment variables\&. You can set the following variables:
.PP
\fBPAM_WRAPPER\fR
.RS 4
If you load the pam_wrapper and enable it with setting PAM_WRAPPER=1 all PAM calls will be wrapped so you are able to specify a directory with the service files pam_wrapper should be using\&.
.RE
.PP
\fBPAM_WRAPPER_SERVICE_DIR\fR
.RS 4
The directory to read PAM service files from\&.
.RE
.sp
If you want to use pam_matrix (see below) or want to test your own PAM module you need to specify the absolute path to your module in the service files\&.
.PP
\fBPAM_WRAPPER_DEBUGLEVEL\fR
.RS 4
If you need to see what is going on in pam_wrapper itself or try to find a bug, you can enable logging support in pam_wrapper if you built it with debug symbols\&.
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
0 = ERROR
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
1 = WARNING
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
2 = DEBUG
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
3 = TRACE
.RE
.RE
.PP
\fBPAM_WRAPPER_USE_SYSLOG\fR
.RS 4
By default pam logs will go to the pam_wrapper DEBUG log level and will not be sent to the syslog\&. If you want to log to the syslog to you can set this variable to 1\&.
.RE
.PP
\fBPAM_WRAPPER_KEEP_DIR\fR
.RS 4
If this option is set to 1, then pam_wrapper won\(cqt delete its temporary directories\&. Mostly useful for pam_wrapper development\&.
.RE
.PP
\fBPAM_WRAPPER_DISABLE_DEEPBIND\fR
.RS 4
This allows you to disable deep binding in pam_wrapper\&. This is useful for running valgrind tools or sanitizers like (address, undefined, thread)\&.
.RE
.SH "EXAMPLE"
.sp
A service file for pam_wrapper should look like this:
.sp
.if n \{\
.RS 4
.\}
.nf
auth            required        /usr/lib/pam_wrapper/pam_matrix\&.so passdb=/path/to/pdb
account         required        /usr/lib/pam_wrapper/pam_matrix\&.so passdb=/path/to/pdb
password        required        /usr/lib/pam_wrapper/pam_matrix\&.so passdb=/path/to/pdb
session         required        /usr/lib/pam_wrapper/pam_matrix\&.so passdb=/path/to/pdb
.fi
.if n \{\
.RE
.\}
.sp
The name of the file should represent the service name used by your PAM application\&.
.sp
LD_PRELOAD=\&./libpam_wrapper\&.so PAM_WRAPPER=1 PAM_WRAPPER_SERVICE_DIR=\&./pam_services \&./my_pam_app
.SH "PAM_MATRIX"
.sp
We offer a module to make testing of PAM applications easier\&. You find more information in the pam_matrix(8) manpage\&.
.SH "AUTHOR"
.PP
\fBThe Samba Team\fR
.RS 4
Author.
.RE