== Summary ==
auth-client-config is a python script for modifying nsswitch.conf and pam configuration files to aid in authentication configuration. It can be used by distribution packages or system administers to quickly and easily deploy configurations for nsswitch.conf and pam.

== Profiles and Usage ==
auth-client-config uses a profiles database for storing different authentication profiles.  The profiles are text files, follow the .INI standard, and are stored in /etc/auth-client-config/profile.d. Files may be added to the profiles database directory to support custom authentication configurations. This is useful for a distribution maintainer to have his/her authentication package put an authentication profile into the profiles database, and then have his/her package use auth-client-config to update the system configuration. It also allows for an administrator to set up a single profile for site-wide network authentication roll-outs.

The files in the profiles database use the .INI configuration file standard, and the syntax is:
{{{
[example]
nss_passwd=nsswitch.conf entry for ’passwd’
nss_group=nsswitch.conf entry for ’group
nss_shadow=nsswitch.conf entry for ’shadow’
pam_auth=pam entry/entries for ’auth’
pam_account=pam entry/entries for ’account’
pam_password=pam entry/entries for ’password’
pam_session=pam entry/entries for ’session’
}}}
If you need to specify multiple entries for a specific type (which is often the case with PAM), then simply list additional entries on a newline preceded by a tab. For example, an entry for local configuration might be:
{{{
[example_local]
nss_passwd=passwd: files
nss_group=group: files
nss_shadow=shadow: files
pam_auth=auth required pam_unix.so nullok_secure debug
pam_account=account required pam_unix.so debug
pam_password=password required pam_unix.so nullok obscure min=4 max=8 md5 debug
pam_session=session required pam_unix.so debug
        session optional pam_foreground.so
}}}
Notice how in the above, pam_session has two entries.

To use the above entry with auth-client-config, create a file with the above entries in it and put the file into the profiles database directory (typically named after the profile or package that added it). Now call
auth-client-config with:
{{{
auth-client-config -a -p example_local
}}}

Other examples might be:

 * Set nsswitch.conf and pam to use the ’example_local’ profile:
{{{
auth-client-config -a -p example_local
}}}
 * Set only nsswitch.conf to use the ’example_local’ profile, but only if current nsswitch.conf entries exist in the profiles database:
{{{
auth-client-config -t nss -p example_local -d
}}}
 * Restore nsswitch.conf and pam to previous non-auth-client-config files:
{{{
auth-client-config -a -p example_local -r
}}}

Several other command line options exist.  See {{{man auth-client-config}}} or [[https://launchpad.net/auth-client-config|auth-client-config]] for details.

== Package Management ==
auth-client-config is new and has not been included in many packages yet.  It is hoped that it will serve as the base for many packages, such as [[https://wiki.ubuntu.com/LDAPAuthentication|LDAPAuthentication]], [[https://code.launchpad.net/~ubuntu-dev/+branch/network-authentication/authtool|authtool]], {{{libpam-runtime}}} and {{{base-files}}}.  As it stands, auth-client-config has several flags that will aid in packaging:

 * Exit with status '0' if current system configuration matches 'profile_name', otherwise exit status '1'
{{{
auth-client-config -p profile_name -a -s
}}}

 * Update system configuration with 'profile_name' only if the current system configuration exists in the profiles database (ie don't overwrite a user's custom configuration).
{{{
auth-client-config -p profile_name -a -d
}}}

 * if a previous state exists, reset it to previous state if the current system configuration matches 'profile_name' (don't undo another package's settings, but allow this package to remove its own).
{{{
auth-client-config -p profile_name -a -r
}}}

'''TODO''' A policy should be developed for distributions using auth-client-config so that user changes or package configuration changes will not be overwritten on upgrades.

== Source Code ==
auth-client-config has moved to Bazaar in Launchpad, and can be found at [[https://code.launchpad.net/auth-client-config/trunk|https://code.launchpad.net/auth-client-config/trunk]]