makeuserdb - Create /etc/userdb.dat

SYNOPSIS

   makeuserdb

   pw2userdb

DESCRIPTION

This command creates binary database file, /etc/userdb.dat, based on the contents of /etc/userdb. /etc/userdb.dat is used by maildrop and Courier as either a substitute for your system password file, or as a complement to your system password file. It is possible to use /etc/userdb.dat to specify "virtual" accounts, accounts that do not have an associated login. Typically all virtual accounts share the same system userid. /etc/userdb.dat can also be used as a substitute for your system password file. Because the system password file is a text file, when there's a large number of accounts it will be significantly faster to search a binary database file, instead of a text file.

The makeuserdb command creates /etc/userdb.dat based on the contents of /etc/userdb. This can be either a plain text file, or a directory. If it is a directory, the contents of all the files in the directory are combined into one file, before being used to create /etc/userdb.dat.

makeuserdb command can be safely executed during normal system operations.

Format of `/etc/userdb`

/etc/userdb is a plain text file that can be created using any text editor. Blank lines are ignored. Lines that start with the # character are comments, and are also ignored. Other lines define the properties of a single account on the local system, one line per account. Each line takes the following format:

name<TAB>field=value|field=value

name is the account name. If Courier is configured to treat lowercase and uppercase account names as identical, name MUST contain lowercase characters only. name is followed by exactly one tab character, then a list of field/value pairs separated by vertical slash characters. field is the name of the field, value is the field value. The field value itself cannot contain commas. Fields can be specified in any order. Here are the currently defined fields. Note that not every field is used by every application that uses /etc/userdb.dat.

uid - value specifies a unique numerical user ID for this account.
gid - value specifies a unique numerical group ID for this account.
home - value specifies the account's home directory.
shell - value specifies the account's default shell.
systempw - value specifies the account's system password. If this field is missing, the password is looked up in the system's default password file.
pop3pw - value specifies the account's POP3 password. If missing, systempw is used.
mail - value specifies the location of the account's Maildir mailbox. If missing, the account's Maildir is expected to be present in the default location for system accounts.
quota - value specifies the quota for the account's Maildir. See maildirquota(8) for more information.

The uid, gid, and home fields MUST be specified. The remaining fields are optional. If missing, system defaults will be used.

=uid<TAB>name

This entry is used to specify reverse mapping from userids to names. uid specifies the UNIX userid, name specifies the UNIX username. name must point to another record in userdb.

/etc/userdbshadow.dat

All fields whose name ends with 'pw' will NOT copied to /etc/userdb.dat. These fields will be copied to /etc/userdbshadow.dat. makeuserdb will turn off all group and world permissions on /etc/userdbshadow.dat. makeuserdb will also fail if /etc/userdb has any group or world permissions.

CONVERTING /etc/passwd to /etc/userdb format

The pw2userdb script reads /etc/passwd and /etc/shadow and converts all accounts to /etc/userdb format, printing the result on standard output. The output can be redirected to /etc/userdb, or to a file in this subdirectory. Linerar searches of /etc/passwd can be very slow when you have tens of thousands of accounts. Programs like maildrop always look in /etc/userdb first, so by having the system password file in the /etc/userdb it is possible to significantly reduce the amount of time it takes to look it up.

After saving the output of pw2userdb, you must still run makeuserdb to convert it to a binary database format.

FILES

/etc/userdb
/etc/userdb.dat
/etc/userdbshadow.dat
/etc/userdb.tmp - temporary file
/etc/userdbshadow.tmp - temporary file

BUGS

No errors will be reported if the same account name appears more than once.

systempw and pop3pw must be encrypted via crypt.

makeuserdb is a Perl script, and uses Perl's portable locking. Perl's documentation notes that certain combinations of locking options may not work with some networks.