Table of Contents
authpwd authentication moduleauthshadow authentication moduleauthpam authentication moduleauthpipe authentication moduleauthpipe protocolauthuserdb 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 moduleauthsqlite authentication moduleauthldap authentication moduleauthcustomThis 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 @@ -17,7 +17,7 @@ to either one of these two functions. The library contains several alternative authentication modules to choose from, described below.
The configuration file @authdaemonrc@ contains several
-settings. The most important of them are:
+settings. The most important of them are:
A list of authentication modules to activate. By default, this list includes all available authentication modules, even if some are not actually installed at the moment. @@ -31,13 +31,14 @@ optional sub-packages. Installing the sub-package is the only action needed to make use of it.
The only time the list of authentication modules need to be adjusted is when an available authentication module must be disabled for some reason. -This should only be needed in the most unusual circumstances.
+This should only be needed in the most unusual circumstances.
Number of authentication processes. The default setting is to start five authentication processes, which should be sufficient for normal usage. Try increasing this setting if its taking too long to log into an account, and you have determined that this is not due to a bottleneck in the whatever -authentication database you're using (LDAP, MySQL, or PostgreSQL).
+authentication database you're using (LDAP, MySQL, SQLite, +or PostgreSQL).
An authentication request must be completed within thirty seconds, otherwise it gets rejected. When authentication requests come in faster than all five authentication @@ -45,17 +46,17 @@ processes can get to them, delays build up, and the timer is ticking. If all the activity maxes out the CPU or I/O bandwidth, nothing can be done about it, short of getting another server. However if there's plenty of available CPU and -I/O, increasing the number of processes will do the trick.
This modules obtains account information and passwords from the
/etc/passwd file.
This module doesn't actually read the /etc/passwd
file, it uses the C library's getpw() functions.
The C library implementation could use any mechanism to obtain the equivalent
-information.
This module is a version of the authpwd module that
reads passwords
from /etc/shadow (the C library's getsp()
-functions).
This modules uses the system's PAM library
(pluggable authentication modules) for authentication.
This is, essentially, a way to use existing PAM modules for authentication.
@@ -68,7 +69,7 @@ functions, like pam_krb5 will not work with Courier
Additional configuration steps will be required to set up
the PAM library to authenticate Courier's services.
Courier's IMAP and POP3 servers, for example, require that the
-âimapâ and âpop3â PAM service to be
+âimapâ and âpop3â PAM service to be
configured.
The specific configuration steps differ from system to system.
Consult the system documentation for more information.
@@ -118,7 +119,7 @@ pop3 account required pam_unix.so
Some PAM libraries use
pam_pwdb.so instead of
pam_unix.so; consult the PAM library's
-documentation for more information.
This is a generic plug-in module that runs an external script, or a program, in response to authentication requests.
The external program reads from stdin and writes to stdout. It can be persistent and handle many authentication requests. Only one request will be sent to it at a time; each authdaemon process starts its own copy of @@ -126,13 +127,13 @@ the external script.
The location of the external program is set by the
--with-pipeprog configure option,
which defaults to
@sysconfdir@/authlib/authProg. A sample program
-is included in the courier-authlib source.
authpipe uses the same protocol as authdaemon clients use to communicate with authdaemond.
There are four possible requests: PRE,
AUTH, PASSWD and
ENUMERATE. Apart from AUTH, each
request is a single line terminated by newline.
-
authservice username <newline>Look up data for an account. +
authservice username <newline>Look up data for an account.
authservice identifies the service the
user is trying to use - e.g. pop3, imap, webmail etc.
If the account exists, return the account data as a series of ATTR=value newline-terminated lines, followed by a @@ -206,7 +207,7 @@ request is a single line terminated by newline. such as a database being down or an error occuring mid-way through returning account data, authProg should terminate before sending the terminating period. -
This module
uses a GDBM or a DB-based
userdb(8) database.
@@ -243,7 +244,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,7 +252,7 @@ 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
@@ -264,7 +265,7 @@ 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
one system account to be used for uid/gid purposes. Let's call this system
-account "vmail".
This approach should be used if you do not have many virtual mailboxes. It's very simple, but quickly becomes cumbersome if you administer many virtual mailboxes.
Create an empty @userdb@ file:
@@ -318,8 +319,8 @@ $ exit You may need to specify a full path to your maildirmake program. The end result is that you created$HOME/john-examplein vmail's account, which -can be thought of as a âvirtual home directoryâ for -âjohn@example.comâ, that contains the account's maildir +can be thought of as a âvirtual home directoryâ for +âjohn@example.comâ, that contains the account's maildir mailbox.Now, let's connect the dots here, and create an entry in
@userdb@forjohn@example.com:@@ -330,7 +331,7 @@ This command runs the script nameduserdb, which installed, by default in@sbindir@. Replace UUU and GGG with the userid and groupid of the vmail account. If you now look in@userdb@, you will see that a new record for -âjohn@example.comâ +âjohn@example.comâ has been appended to the end of the file.One more detail: we need to set the IMAP password for this mailbox:
@@ -361,7 +362,7 @@ Courier reads@userdb@.datand@userdb@shadow.datonly. 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. @@ -404,29 +405,36 @@ $ userdbpw | userdb "example-com/john@example.com" set imappwThis sets the IMAP access password for this account. Finally:
$ makeuserdb -
userdb is a simple, straightforward solution that scales
to a couple of thousand of mail accounts, depending on the hardware.
Beyond that, one of database-based modules will need to be used,
such as
authldap,
authmysql,
+authsqlite,
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 reads
the list of mail accounts and passwords from a table in a
MySQL database.
The @authmysqlrc@ configuration file defines the
particular details regarding the MySQL database and the schema of the
-mail account table.
This module reads
the list of mail accounts and passwords from a table in a
PostgreSQL database.
The @authpgsqlrc@ configuration file defines the
particular details regarding the PostgreSQL database and the schema of the
-mail account table.
+This module reads
+the list of mail accounts and passwords from a table in a
+SQLite database file.
+The @authsqliterc@ configuration file defines the
+particular details regarding the SQLite database file and the schema of the
+mail account table.
This module reads
the list of mail accounts and passwords from an LDAP directory.
The @authldaprc@ configuration file defines the
@@ -434,28 +442,28 @@ particular details regarding the LDAP directory layout.
A suggested LDAP schema can be found in the file
authldap.schema,
which is included in Courier authentication library's source code, and
-may be installed on your system.
This is a do-nothing module where custom authentication code can be added. This authentication module is just a stub that doesn't really do anything. It's purpose is to serve as a placeholder where custom authentication code -can be easily implement.
The authentication library has a facility for keep arbitrary
-âname=valueâ-type settings,
-called âoptionsâ, for individual accounts. This feature is
+âname=valueâ-type settings,
+called âoptionsâ, for individual accounts. This feature is
only available with
userdb,
-LDAP, MySQL, and
+LDAP, MySQL, SQLite and
PostgresSQL
modules. Individual account options are not supported with
system-based authentication modules (password/shadow files, or PAM).
-See the +See 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+following manner:
userdb
Use the userdb command to set a field called
"options". Example:
userdb user1@example.com set options=disableimap=1,sharedgroup=44
@@ -479,21 +487,24 @@ of LDAP attributes to account settings. A LDAP_AUXOPTIONS<
of "shared=sharedgroup,disableimap" means that the LDAP attribute
called "shared" contains the "sharedgroup" setting, as described
previously; and an LDAP attribute of disableimap contains the setting
-of the same name.- MySQL, and PostgreSQL
-Account options are defined by MYSQL_AUXOPTIONS_FIELD
+of the same name.
- MySQL,
+SQLite, and PostgreSQL
+Account options are defined by MYSQL_AUXOPTIONS_FIELD,
+SQLITE_AUXOPTIONS_FIELD,
or POSTGRESQL_AUXOPTIONS_FIELD, in its corresponding
configuration file. In the most simplest case, add a character field to
the database, and put the field name into the
-MYSQL_AUXOPTIONS_FIELD or
+MYSQL_AUXOPTIONS_FIELD,
+SQLITE_AUXOPTIONS_FIELD, or
POSTGRESQL_AUXOPTIONS_FIELD configuration file setting.
For each account, the character field should contain the literal option
string. Yes, you'll just put "shared=sharedgroup,disableimap"
literally, in that field.
Fortunately, there is a cleaner way to do this, which avoid driving
a database designer batty. Keep in mind that the contents of
-MYSQL_AUXOPTIONS_FIELD/POSTGRESQL_AUXOPTIONS_FIELD
+MYSQL_AUXOPTIONS_FIELD/SQLITE_AUXOPTIONS_FIELD/POSTGRESQL_AUXOPTIONS_FIELD
are simply inserted directly into the SQL query that fetches the
-account information. Both MySQL and PostgreSQL have a rich SQL that can
+account information. MySQL, SQLite, and PostgreSQL have a rich SQL that can
be used to manufacture a suitable option string from plain,
garden-variety, database fields. That is, you may define individual
table fields like "disableimap", and "disablepop3", then provide a
@@ -501,7 +512,41 @@ 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 following list of account options is a combined list of implemented +options supported by Courier, Courier-IMAP, and +SqWebMail packages. Some of the following information is obviously +not applicable for a particular package. +The inapplicable bits should be obvious.
+The following options are recognized by the various Courier +packages:
disableimap=n+If "n" is 1, IMAP access to this account should be disabled.
disablepop3=n+If "n" is 1, POP3 access to this account should be disabled.
disableinsecureimap=n+If "n" is 1, unencrypted IMAP access to this account should be disabled.
disableinsecurepop3=n+If "n" is 1, unencrypted POP3 access to this account should be disabled.
disablewebmail=n+If "n" is 1, webmail access to this account should be disabled.
disableshared=n+If "n" is 1, this account should not have access to shared folders or be able +to share its own folders with other people.
group=name
+This option is used by Courier-IMAP in calculating access control lists.
+This option places the account as a member of access group
+name.
+Instead of granting access rights on individual mail folders to individual
+accounts, the access rights can be granted to an access group
+ânameâ, and all members of this group get the specified access
+rights.
+The access group name âadministratorsâ is a reserved group.
+All accounts in the administrators group automatically
+receive all rights to all accessible folders.
+This option may be specified multiple times to specify that the account +belongs to multiple account groups.
sharedgroup=name+Another option used by Courier-IMAP. +Append "name" to the name of the top level virtual shared folder +index file. This setting restricts which virtual shared folders this +account could possibly access (and that's on top of whatever else the +access control lists say). See the virtual shared folder documentation +for more information.
+For technical reasons, group names may not include comma, tab, "/" or "|" +characters.
The authtest command may be used to verify that the authentication library is working:
authtest userid @@ -525,8 +570,10 @@ The three argument form of the 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.htmlfor more information.For the virtual domain modules (
authldap, -authmysql,authpgsqland friends) changing the +SeeREADME.authdebug.htmlfor more information.For the virtual domain modules (
authldap, +authmysql, +authsqlite, +authpgsqland friends) changing the login is a no-brainer. The tricky situation is when SqWebMail uses system passwords to log in (theauthpwd,authshadow, orauthpamauthentication module). Different systems use different @@ -566,8 +613,8 @@ 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
/usr/local/libexec/courier-authlib/authsystem.passwd-(assuming default options to the configure script).-The following structure describes an authentication module:
+The following structure describes an authentication module:
Example 1. struct authstaticinfo
struct authstaticinfo { const char *auth_name; int (*auth_func)(const char *, const char *, char *, int, @@ -596,14 +643,14 @@ struct authstaticinfo {An authentication module is a shared library that defines a single function called -âcourier_auth_
NAME_initâ, where -âNAMEâ is the name of the authentication module. +âcourier_auth_NAME_initâ, where +âNAMEâ is the name of the authentication module. The shared library does not need to export any other symbols, this is the only function that needs to be exported. The function returns a pointer to the authstaticinfo structure. For example, the relevant code from theauthmysqlmodule is: -Example 2. authmysql
+Example 2. authmysql
static struct authstaticinfo authmysql_info={ "authmysql", auth_mysql, @@ -620,24 +667,24 @@ struct authstaticinfo *courier_authmysql_init() }
auth_funcpoints to a function that handles an -authentication request. The function is invoked as follows:Example 3. auth_func
+authentication request. The function is invoked as follows:Example 3. auth_func
int result=auth_func(const char *service, const char *authtype, const char *authdata, int (*callback_func)(struct authinfo *, void *), void *callback_arg);-âserviceâ is the name of the service being authenticated, -such as â
imapâ or -âpop3â. -âauthtypeâ defines the authentication format, -and âauthdataâ is the actual authentication request.+âserviceâ is the name of the service being authenticated, +such as â
imapâ or +âpop3â. +âauthtypeâ defines the authentication format, +and âauthdataâ is the actual authentication request.Two authentication formats are defined at this time. -The âauthtypeâ string is set to one of the following -strings:
- âloginâ
+The âauthtypeâ string is set to one of the following +strings:
- âloginâ
Tradition userid/password authentication.
authdatapoints to a string that consists of: the userid; a newline character; the password; a final newline -character.- âcram-md5â, or âcram-sha1â
+character.
- âcram-md5â, or âcram-sha1â
Challenge/response authentication.
authdatapoints to a string that consists of: the base64-encoded challenge; a newline character; @@ -669,11 +716,11 @@ The authentication module is responsible for allocating this structure. After the callback function returns this structure can be deallocated. The authentication module initializes the following fields:
auth_pre_funcpoints to a function that obtains -account information. The function is invoked as follows:Example 4. auth_pre_func
+account information. The function is invoked as follows:Example 4. auth_pre_func
int auth_pre_func(const char *user, const char *service, int (*callback)(struct authinfo *, void *), void *arg);-This function does the same thing as âauth_funcâ except that +This function does the same thing as âauth_funcâ except that the password is not actually verified. If the account exists, the callback function is invoked with the same callback arguments.
@@ -687,12 +734,12 @@ connections, so that they do not get shut down by the server, for inactivity, resulting in an error the next time an authentication request is received.
auth_changepwdpoints to a function that will be -invoked to change a password on an account, as follows.Example 5. auth_changepwd
+invoked to change a password on an account, as follows.Example 5. auth_changepwd
int auth_changepwd(const char *service, const char *user, const char *oldpw, const char *newpw);
serviceis the name of the service whose password is to -be changed (such as âimapâ or âpop3â). +be changed (such as âimapâ or âpop3â).auth_changepwdshould return 0 if the password was changed succesfully, a negative value ifuseris invalid (the next authentication module will be tried), or a positive value if @@ -709,11 +756,12 @@ After enumerating all login IDsauth_enumeratecal 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_enumerateterminates 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+
@authsqliterc@- authsqlite configuration file+
@authpgsqlrc@- authpgsql configuration file