Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages


home | help
MAKEUSERDB(8)		    Double Precision, Inc.		 MAKEUSERDB(8)

       makeuserdb - create /usr/local/etc/userdb

       makeuserdb [-f filename]


       vchkpw2userdb [--vpopmailhome=dir] [--todir=dir]

       makeuserdb creates /usr/local/etc/userdb.dat from the contents of
       /usr/local/etc/userdb.  /usr/local/etc/userdb's contents	are described
       later in	this document.	Maildrop, Courier, and other applications use
       /usr/local/etc/userdb.dat as a substitute/complement for	your system
       password	file. The usual	purpose	for /usr/local/etc/userdb.dat is to
       specify "virtual" accounts - accounts that do not have an associated
       system login. Usually (but not necessarily) all virtual accounts	share
       the same	system userid.	/usr/local/etc/userdb.dat may also replace
       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	@userdb.dat@, which is a binary	database, instead of a
       flat text file that the system password file usually is.

       The makeuserdb command can be safely executed during normal system

       The -f option creates filename.dat from filename, instead of the
       default /usr/local/etc/userdb.dat from /usr/local/etc/userdb.

   Format of /usr/local/etc/userdb
       /usr/local/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
       properties of a single "account", one line per account.
       /usr/local/etc/userdb may be a directory	instead	of a plain file. In
       that case all files in /usr/local/etc/userdb are	essentially
       concatenated, and are treated as	a single file. Each line takes the
       following format:


       name is the account name.  name MUST contain only lowercase characters
       If Courier is configured	to treat lowercase and uppercase account names
       as identical, name is followed by exactly one tab character, then a
       list of field/value pairs separated by vertical slashes.	 field is the
       name of the field, value	is the field value. Fields and values themself
       cannot contain slashes or control characters. Fields may	be specified
       in any order. Here are all the currently	defined	fields.	Note that not
       every field is used by every application	that reads

       uid - value is a	(possibly) unique numerical user ID for	this account.

       gid - value is a	(possibly) unique numerical group ID for this account.

       home - value is the account's home directory.

       shell - value is	the account's default login shell.

       systempw	- value	is the account's password. See userdbpw(8)[1] for
       details on how to set up	this field.

       pop3pw, esmtppw,	imappw...  - value specifies a separate	password used
       only for	authenticating access using a specific service,	such as	POP3,
       IMAP, or	anything else. If not defined, systempw	is always used.	This
       allows access to	an account to be restricted only to certain services,
       such as POP3, even if other services are	also enabled on	the server.

       mail - value specifies the location of the account's Maildir mailbox.
       This is an optional field that is normally used when userdb is used to
       provide aliases for other mail accounts.	For example, one particular
       multi-domain E-mail service configuration that's	used by	both Qmail and
       Courier servers is to deliver mail for a	mailbox	in a virtual domain,
       such as "", to a	local mailbox called "example-user".
       Instead of requiring the	E-mail account holder to log in	as
       "example-user" to download mail from this account, a userdb entry for
       "" is set up with mail set to the location of
       example-user's Maildir mailbox, thus hiding the internal	mail
       configuration from the E-mail account holder's view.

       quota - value specifies the maildir quota for the account's Maildir.
       This has	nothing	to do with actual filesystem quotas.  Courier has a
       software-based Maildir quota enforcement	mechanism which	requires
       additional setup	and configuration. See maildirquota(7)[2] for
       additional information.

       All fields whose	name ends with 'pw' will NOT copied to
       /usr/local/etc/userdb.dat. These	fields will be copied to
       /usr/local/etc/userdbshadow.dat.	 makeuserdb creates
       /usr/local/etc/userdbshadow.dat without any group and world
       permissions. Note that makeuserdb reports an error if
       /usr/local/etc/userdb has any group or world permissions.

   CONVERTING /etc/passwd and vpopmail to /usr/local/etc/userdb	format
       pw2userdb reads the /etc/passwd and /etc/shadow files and converts all
       entries to the /usr/local/etc/userdb format, printing the result	on
       standard	output.	The output of pw2userdb	can be saved as
       /usr/local/etc/userdb (or as some file in this subdirectory). Linear
       searches	of /etc/passwd can be very slow	when you have tens of
       thousands of accounts. Programs like maildrop always look in
       /usr/local/etc/userdb first. By saving the system password file in
       /usr/local/etc/userdb it	is possible to significantly reduce the	amount
       of time it takes	to look	up this	information.

       After saving the	output of pw2userdb, you must still run	makeuserdb to
       create /usr/local/etc/userdb.dat.

       vchkpw2userdb converts a	vpopmail-style directory hierarchy to the
       /usr/local/etc/userdb format. This is an	external virtual domain
       management package that's often used with Qmail servers.

       Generally, an account named 'vpopmail' is reserved for this purpose. In
       that account the	file users/vpasswd has the same	layout as /etc/passwd,
       and performs a similar function,	except that all	userid in
       users/vpasswd have the same userid. Additionally, the domains
       subdirectory stores virtual accounts for	multiple domains. For example,
       domains/ has the passwd file for the domain Some systems also have a soft link,	domains/default, that
       points to a domain that's considered a "default"	domain.

       The vchkpw2userdb reads all this	information, and tries to convert it
       into the	/usr/local/etc/userdb format. The --vpopmailhost option
       specifies the top level directory, if it	is not the home	directory of
       the vpopmail account.

       The vchkpw2userdb script	prints the results on standard output. If
       specified, the --todir option tries to convert all vpasswd files	one at
       a time, saving each one individually in dir. For	example:

	   mkdir /usr/local/etc/userdb
	   vchkpw2userdb --todir=/usr/local/etc/userdb/vpopmail

       It is still necessary to	run makeuserdb,	of course, to create the
       binary database file /usr/local/etc/userdb.dat

       NOTE: You are still required to create the /usr/local/etc/userdb	entry
       which maps system userids back to accounts, "uid=<TAB>name", if that's
       applicable.  vchkpw2userdb will not do it for you.

       NOTE: makeuserdb	may complain about duplicate entries, if your
       "default" entries in users/vpasswd or domains/default/vpasswd are the
       same as anything	in any other /usr/local/etc/userdb file. It is also
       likely that you'll end up with duplicate, but distinct, entries for
       every account in	the default domain. For	example, if your default
       domain is, you'll end up with duplicate entries - you'll
       have entries for	both user and

       If you intend to	maintain the master set	of accounts using
       vchkpw/vpopmail,	in order to avoid cleaning this	up every time, you
       might want to consider doing the	following: run vchkpw2userdb once,
       using the --todir option. Then, go into the resulting directory,	and
       replace one of the redundant files with a soft link to /dev/null. This
       allows you to run vchkpw2userdb without having to go in and cleaning up
       again, afterwards.

	   /usr/local/etc/userdb.tmp - temporary file
	   /usr/local/etc/userdbshadow.tmp - temporary file

       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.

       userdb(8)[3], maildrop(8)[4], courier(8)[5], maildirquota(7)[2].

	1. userdbpw(8)
	   [set	$man.base.url.for.relative.links]/userdbpw.html

	2. maildirquota(7)
	   [set	$man.base.url.for.relative.links]/maildirquota.html

	3. userdb(8)
	   [set	$man.base.url.for.relative.links]/userdb.html

	4. maildrop(8)
	   [set	$man.base.url.for.relative.links]/maildrop.html

	5. courier(8)
	   [set	$man.base.url.for.relative.links]/courier.html

Double Precision, Inc.		  06/20/2015			 MAKEUSERDB(8)


Want to link to this manual page? Use this URL:

home | help