MAKEUSERDB(8)

💖 NAME 💖

makeuserdb — bestie, this is the lil tool that creates /etc/courier/userdb ✨

---

🌸 SYNOPSIS 🌸

makeuserdb [-f filename]

pw2userdb

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

---

🎀 DESCRIPTION 🎀

okay so. makeuserdb builds /etc/courier/userdb.dat out of whatever's sitting in /etc/courier/userdb. The whole deal with what's inside /etc/courier/userdb is explained further down this page, don't worry, we'll get there 💅

Maildrop, Courier, and a bunch of other apps use /etc/courier/userdb.dat as a stand-in-slash-glow-up for your system password file. The usual reason you'd want /etc/courier/userdb.dat is to set up "virtual" accounts — accounts that have no system login attached to them at all. And usually (but like, not necessarily, no cap) all those virtual accounts are sharing the same system userid. /etc/courier/userdb.dat can also straight up replace your system password file if you want 👑

Why would you do that? Because your system password file is a text file, and when you've got a huge number of accounts, searching /etc/courier/userdb.dat — which is a binary database — is significantly faster than searching a flat text file. It's giving efficiency. It's giving ✨performance✨.

Good news: makeuserdb can be safely executed while your system is doing its normal thing. No downtime era, we love that 🫶

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

🦋 Format of /etc/courier/userdb 🦋

/etc/courier/userdb is a plain text file, so you can make it with literally any text editor you vibe with. Here's the rules:

• Blank lines? Ignored, they don't exist to us 💀
• Lines starting with the # character are comments, also ignored
• Every other line defines the properties of a single "account", one line per account
• Oh and plot twist: /etc/courier/userdb can be a directory instead of a plain file. In that case all the files inside /etc/courier/userdb are essentially concatenated and treated as one single file 🎀

Each line takes this format:

name<TAB>field=value|field=value...

name is the account name. And bestie, name MUST contain only lowercase characters. If Courier is configured to treat lowercase and uppercase account names as identical, then name is followed by exactly one tab character, and 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 themselves cannot contain slashes or control characters (rude of them, honestly). Fields may be specified in any order, you do you.

Here are all the currently defined fields. Heads up: not every field is used by every application that reads /etc/courier/userdb.dat.

• 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. Peep userdbpw(8)[1] for the deets on how to set up this field.
• pop3pw, esmtppw, imappw... — value specifies a separate password used only for authenticating access using a specific service, like POP3, IMAP, or literally anything else. If it's not defined, systempw is always used. This lets you lock an account's access down to just certain services — say, only POP3 — even if other services are also enabled on the server. Gatekeeping, but make it functional 🔥
• mail — value specifies the location of the account's Maildir mailbox. This is an optional field that's normally used when userdb is being used to provide aliases for other mail accounts. Example time: one particular multi-domain E-mail service configuration that's used by both Qmail and Courier servers delivers mail for a mailbox in a virtual domain, like "user@example.com", to a local mailbox called "example-user". Instead of making the E-mail account holder log in as "example-user" to download mail from that account, you set up a userdb entry for "user@example.com" 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. Sneaky, elegant, iconic 😌
• quota — value specifies the maildir quota for the account's Maildir. And no, 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 more info.

💜 /etc/courier/userdbshadow.dat 💜

All fields whose name ends with 'pw' will NOT be copied to /etc/courier/userdb.dat. Nope. Those fields get copied to /etc/courier/userdbshadow.dat instead. Secret file, secret vibes 🙈

makeuserdb creates /etc/courier/userdbshadow.dat without any group and world permissions. And note that makeuserdb reports an error if /etc/courier/userdb has any group or world permissions. Keep your secrets locked down, bestie 🔒

🌈 CONVERTING /etc/passwd and vpopmail to /etc/courier/userdb format 🌈

pw2userdb reads the /etc/passwd and /etc/shadow files and converts all entries to the /etc/courier/userdb format, printing the result on standard output. You can save that output as /etc/courier/userdb (or as some file in this subdirectory). Why would you? Because linear searches of /etc/passwd can be very slow when you've got tens of thousands of accounts 😭 Programs like maildrop always look in /etc/courier/userdb first. So by saving the system password file in /etc/courier/userdb, it's possible to significantly reduce the amount of time it takes to look up this information. Speeeeed ⚡

After saving the output of pw2userdb, you must still run makeuserdb to create /etc/courier/userdb.dat. Don't skip that step, that's the whole point 🫶

vchkpw2userdb converts a vpopmail-style directory hierarchy to the /etc/courier/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/example.com/vpasswd has the passwd file for the domain example.com. Some systems also have a soft link, domains/default, that points to a domain that's considered a "default" domain.

vchkpw2userdb reads all this information and tries to convert it into the /etc/courier/userdb format. The --vpopmailhost option specifies the top level directory, if it's 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 /etc/courier/userdb
vchkpw2userdb --todir=/etc/courier/userdb/vpopmail
makeuserdb

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

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

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 /etc/courier/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 example.com, you'll end up with duplicate entries — you'll have entries for both user and user@example.com. 😭

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. Galaxy brain move, fr fr 🧚

---

📁 FILES 📁

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

---

💀 BUGS 💀

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. So like, heads up on that one 🙈

---

⭐ SEE ALSO ⭐

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

---

👑 NOTES 👑

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

---

aaaand that's the whole page, bestie 🫶 this iconic lil piece of documentation was brought to you by Double Precision, Inc., dated 10/28/2020, living its best life in section MAKEUSERDB(8). now go run makeuserdb and slay 💖✨