X-Git-Url: https://git.hcoop.net/hcoop/debian/courier-authlib.git/blobdiff_plain/432ecdf4a9444ffeee98178829d51fc588911cdd..0fde1ce3109f2259ded7e8bff8d2b1c984252bc0:/README_authlib.html.in diff --git a/README_authlib.html.in b/README_authlib.html.in index 9661970..26c8db3 100644 --- a/README_authlib.html.in +++ b/README_authlib.html.in @@ -1,10 +1,10 @@ -
Table of Contents
authpwd
authentication moduleauthshadow
authentication moduleauthpam
authentication moduleauthpipe
authentication moduleauthpipe
protocolauthuserdb
authentication moduleauthvchkpw
authentication moduleauthmysql
authentication moduleauthpgsql
authentication moduleauthldap
authentication moduleauthcustom
+-->
Table of Contents
authpwd
authentication moduleauthshadow
authentication moduleauthpam
authentication moduleauthpipe
authentication moduleauthpipe
protocolauthuserdb
authentication moduleauthmysql
authentication moduleauthpgsql
authentication moduleauthldap
authentication moduleauthcustom
This library is used for two purposes:
1. Read the name of a mail account. Determine the local account's home directory, and system userid and @@ -209,7 +209,7 @@ request is a single line terminated by newline.
This module
uses a GDBM or a DB-based
-userdb(8) database.
+userdb(8) database.
This module also incorporates userdb-based challenge-response authentication
implementation that was done by a separate authcram
module
in previous versions of the Courier authentication library.
@@ -219,7 +219,7 @@ The file contains a list of account names, and their pertinent information.
@sysconfdir@/authlib/userdb
may alternatively be a
directory containing plain text files, which are effectively concatenated
together to form the actual list of accounts.
-The makeuserdb script compiles the account information
+The makeuserdb script compiles the account information
into a GDBM or DB database file, which can be quickly looked up.
@sysconfdir@/authlib/userdb
is loosely equivalent in
function to /etc/passwd
and
@@ -243,7 +243,7 @@ scan /etc/passwd
in order to look up an account.
Instead, a fast database lookup can retrieve the same information from the
database file.
Review the included manual pages, starting with
-userdb(8), for more information.
+userdb(8), for more information.
userdb
is a way to implement many virtual mailboxes - many
mailboxes that do not have to have a separate system userid allocated for
each one, and there is no system login associated with each mailbox.
@@ -251,15 +251,15 @@ each one, and there is no system login associated with each mailbox.
maildirs. It should be scalable to thousands of mailboxes. It can also be
used to replace linear searches of /etc/passwd
with a database
lookup, see
-pw2userdb(8).
Note - you still MUST use some valid system userid and groupid that is shared by all virtual mailboxes. Instead of allocating a single userid and groupid per each mailbox, the same userid and groupid is used for all of them.
This is a rough overview of using userdb. For additional information, read
-userdb(8)
+userdb(8)
and
-makeuserdb(8). All the scripts will
+makeuserdb(8). All the scripts will
be installed in @sbindir@
, so look for them there.
The best way to describe how userdb
works is to try to create
one virtual mail account. As mentioned before, virtual mailboxes still need
@@ -272,7 +272,7 @@ virtual mailboxes.
Create an empty @userdb@
# chmod 700 @userdb@
@userdb@
must have 700 permissions,
since it will contain passwords.
-Now, run the script pw2userdb, as root.
+Now, run the script pw2userdb, as root.
This script converts the
contents of /etc/passwd
to the @userdb@
format
@@ -287,17 +287,17 @@ use a fast
of /etc/passwd
in order to look up system accounts. However, you probably don't want to
use this feature right now, so what you want to do is take the output
-of pw2userdb, and find the entry for the vmail account
+of pw2userdb, and find the entry for the vmail account
that you
created earlier. Look for a line that starts with 'vmail' followed by tab,
followed by familiar fields from /etc/passwd
. Save the
output of
-pw2userdb in a temporary file, edit it, and remove
+pw2userdb in a temporary file, edit it, and remove
everything
except the line containing vmail, and the very next line, which is a special
entry that maps vmail's userid back to the vmail record.
Here's what you might find in the output of -pw2userdb:
+pw2userdb:vmail uid=1012|gid=1012|home=/home/vmail|systempw=* 1012= vmailThe actual numerical values and the home directory location may vary. @@ -315,7 +315,7 @@ $ maildirmake john-example/Maildir $ exit #
-You may need to specify a full path to your maildirmake
+You may need to specify a full path to your maildirmake
program. The end result is that you created
$HOME/john-example
in vmail's account, which
can be thought of as a âvirtual home directoryâ for
@@ -336,7 +336,7 @@ One more detail: we need to set the IMAP password for this
mailbox:
# userdbpw | userdb "john@example.com" set imappw
On most modern Linux and BSD distributions, you can specify the -md5
-option to userdbpw, in order to use MD5 password hashes,
+option to userdbpw, in order to use MD5 password hashes,
instead of crypt. The traditional password function allows passwords only
up to 8 characters long; everything in excess is ignored.
The newer MD5 passwords, now supported by most modern systems, allow
@@ -361,7 +361,7 @@ Courier reads @userdb@.dat
and
@userdb@shadow.dat
only. The plain text source,
@userdb@
is not read by Courier itself. Changes take
effect
-only when makeuserdb runs.
The previous approach used a single flat file, @userdb@
.
This
will work for up to a couple of hundred accounts.
@@ -394,7 +394,7 @@ $ userdb "example-com/john@example.com" set \
home=/home/vmail/domains/example-com/john \
uid=UUU gid=GGG
This creates the file @userdb@/example-com
(the first
-parameter to the userdb command), and appends a record named
+parameter to the userdb command), and appends a record named
"john@example.com". You will store all userdb
entries for
@example.com
in the file
@userdb@/example-com
. All
@@ -414,9 +414,7 @@ such as
authpgsql
.
Since userdb
is maintained as plain text files that
are easily parsed by a script, migrating data from userdb will not be
-difficult.
-This module uses
-the vpopmail/vchkpw
library for authentication.
This module reads the list of mail accounts and passwords from a table in a MySQL database. @@ -452,13 +450,13 @@ only available with modules. Individual account options are not supported with system-based authentication modules (password/shadow files, or PAM).
See the -auth_generic(3) +auth_generic(3) for a description of option names used by various Courier packages. Other applications can make up names for their own settings, and use them in the same way.
Account options are specified via the authentication modules in the following manner:
userdb
-Use the userdb command to set a field called
+Use the userdb command to set a field called
"options
". Example:
userdb user1@example.com set options=disableimap=1,sharedgroup=44 makeuserdb @@ -503,31 +501,31 @@ suitable (albeit ugly) SQL fragment that combines them together into the expected option string. An example of such an SQL string is provided in the comments portion of the configuration file.Note
When using the alternative custom query option, the option string - is the last field that the custom SQL query should return.
+The authtest command may be used to verify that the authentication library is working:
authtest userid authtest userid password authtest userid password newpassword authenumerate
Running -authtest +authtest with one argument should display the selected account's home directory, userid, groupid, and other related data. The second argument to -authtest, +authtest, if supplied, specifies the account's password. The two argument form of -authtest +authtest validates the password, and displays an indication whether the given password is valid, or not. The three argument form of the -authtest +authtest command attemps to change the account's password. The second argument is the old password, the third argument is the new password.
-See README.authdebug.html
for more information.
For the virtual domain modules (authldap
,
+See README.authdebug.html
for more information.
For the virtual domain modules (authldap
,
authmysql
, authpgsql
and friends) changing the
login is a no-brainer. The tricky situation is when SqWebMail uses system
passwords to log in (the authpwd
, authshadow
, or
@@ -537,14 +535,14 @@ ways to keep login passwords. Many systems use the traditional
use a binary database; other systems use NIS. And on some systems the
password file lookup library is a wrapper that goes against an external LDAP
directory, or a database. For maximum compatibility, SqWebMail changes login
-passwords by running the passwd command. This is the traditinal
-*nix command that changes login passwords. passwd is an
+passwords by running the passwd command. This is the traditinal
+*nix command that changes login passwords. passwd is an
interactive command. It's normally run from a terminal.
SqWebMail uses an
-expect script - as mentioned in
+expect script - as mentioned in
the introduction - to answer interactive
-prompts from passwd. The expect script expects to
-get a plain, garden-variety, passwd command, which acts
+prompts from passwd. The expect script expects to
+get a plain, garden-variety, passwd command, which acts
something like this:
# passwd Changing password for luser @@ -554,21 +552,21 @@ something like this:-Systems that use a passwd command with very different prompts -may find that the default expect script will fail. In which case -it will be necessary to tweak the expect script to match the -prompts from the system's passwd command.
-Modern systems use a passwd command that rejects "bad" +Systems that use a passwd command with very different prompts +may find that the default expect script will fail. In which case +it will be necessary to tweak the expect script to match the +prompts from the system's passwd command.
+Modern systems use a passwd command that rejects "bad" passwords - passwords that are based on dictionary words, are too short, or are obvious for other reasons. When testing the ability to change system passwords be sure to use randomly-generated gibberish for the test -passwords. Otherwise, the default expect script will +passwords. Otherwise, the default expect script will actually be working, but you won't be the wiser. For security reasons, the actual -messages from passwd will not be shown by.
-The expect script is installed as +messages from passwd will not be shown by.
+The expect script is installed as
/usr/local/libexec/courier-authlib/authsystem.passwd
-(assuming default options to the configure script).
The following structure describes an authentication module:
+userdb(8)Example 1. struct authstaticinfo
struct authstaticinfo { const char *auth_name; @@ -665,7 +663,7 @@ to the callback function as a second argument. The first argument is a pointer to the authinfo structure, which is described in detail in the -auth_generic(3) +auth_generic(3) manual page. The authentication module is responsible for allocating this structure. After the callback function returns this structure can be deallocated. @@ -712,10 +710,10 @@ the callback function one last time, with a NULL pointer for the login ID, then returns. If an error is encountered while enumerating the login IDs,auth_enumerate
terminates without invoking the callback function with a NULL login ID.-
@authdaemonrc@
- authdaemond configuration file-
@authldaprc@
- authldap configuration file-
@authmysqlrc@
- authmysql configuration file-
@authpgsqlrc@
- authpgsql configuration file-courier(8), +
@authdaemonrc@
- authdaemond configuration file+
@authldaprc@
- authldap configuration file+
@authmysqlrc@
- authmysql configuration file+
@authpgsqlrc@
- authpgsql configuration file