# turn into a manpage with the following command:
#
# pod2man -s 8 -c '' -r '' --stderr pam_cifscreds.pod > pam_cifscreds.8
#

=head1 NAME

pam_cifscreds - PAM module to manage NTLM credentials in kernel keyring

=head1 SYNOPSIS

Edit the PAM configuration files for the systems that you want to
automatically register NTLM credentials for, e.g. /etc/pam.d/login,
and modify as follows:

        ...
        auth       substack     system-auth
    +++ auth       optional     pam_cifscreds.so
        auth       include      postlogin
        ...

        ...
        session    include      system-auth
    +++ session    optional     pam_cifscreds.so domain=DOMAIN
        session    include      postlogin
        ...

Change DOMAIN to the name of you Windows domain, or use host= as
described below.

=head1 DESCRIPTION

The B<pam_cifscreds> PAM module is a tool for automatically adding
credentials (username and password) for the purpose of establishing
sessions in multiuser mounts.

When a cifs filesystem is mounted with the "multiuser" option, and does
not use krb5 authentication, it needs to be able to get the credentials
for each user from somewhere. The B<pam_cifscreds> module can be used
to provide these credentials to the kernel automatically at login.

In the session section of the PAM configuration file, the module can
either an NT domain name or a list of hostname or addresses.

=head1 OPTIONS

B<pam_cifscreds> supports a couple options which can be set in the PAM
configuration files.  You must have one (and only one) of domain= or
host=.

=over

=item B<debug>

Turns on some extra debug logging.

=item B<domain>=<NT domain name>

Credentials will be added for the specified NT domain name.

=item B<host>=<hostname or IP address>[,...]

Credentials will be added for the specified hostnames or IP addresses.

=back

=head1 NOTES

The pam_cifscreds PAM module requires a kernel built with support for
the B<login> key type. That key type was added in v3.3 in mainline Linux
kernels.

Since B<pam_cifscreds> adds keys to the session keyring, it is highly
recommended that one use B<pam_keyinit> to ensure that a session keyring
is established at login time.

=head1 SEE ALSO

cifscreds(1), pam_keyinit(8)

=head1 AUTHOR

The pam_cifscreds PAM module was developed by Orion Poplawski
<orion@nwra.com>.