USERDB(8)

💖 USERDB(8) — the userdb page, bestie edition 💖

okay so first things first: this is the manual page for userdb, section 8, and it belongs to the one and only Double Precision, Inc. 🫶 If you're here you're probably about to mess with /etc/courier/userdb, and honestly? iconic. let's get into it 💅

---

✨ NAME ✨

userdb — manipulate /etc/courier/userdb

---

🌸 SYNOPSIS 🌸

userdb {addr} set {field=value...}

userdb {addr} unset {field...}

userdb {addr} del

userdb {path/addr} [set | unset | del] ...

userdb -f {file} {adr} [set | unset | del] ...

userdb -show {path}

userdb -show {path} {addr}

userdb -show -f {file}

userdb -show -f {file} {addr}

---

🦋 DESCRIPTION 🦋

userdb is a cute little convenience script for poking at entries in /etc/courier/userdb one at a time. Wanna know what actually lives inside that file? go read makeuserdb(8) [1], it spills all the tea. technically you can always just open /etc/courier/userdb in literally any text editor and go wild, but userdb is the convenient way to edit it from another script. periodt.

also!! plot twist: /etc/courier/userdb can be a subdirectory instead of a file. so if you write foo/bar/addr, you're manipulating addr inside the file /etc/courier/userdb/foo/bar. you can also use the -f flag for the same thing — -f /etc/courier/userdb/foo/bar is equivalent. use whichever form makes the most sense to your brain, no judgement 💜

🚨 IMPORTANT bestie: /etc/courier/userdb must not have any group or world permissions. like, none. zero. because its contents may include system passwords (depends on the application using this virtual user account database). lock it down fr fr 🔒

every single line in /etc/courier/userdb takes this exact form:

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

addr is a unique virtual address, okay? it's followed by one single tab character, and then a list of field=value pairs separated by vertical slash characters. for the actual field definitions go read makeuserdb(8) [1] 💖

you can use a text editor to add blank lines or comments in /etc/courier/userdb. any blank lines or comments are ignored by the userdb script, so go ahead and annotate your life ✨

the names of the actual fields, and what goes in them, are defined entirely by the applications that use the /etc/courier/userdb database. the userdb command itself is just out here adding or removing arbitrary fields. it does not care. it does not judge. it just vibes.

for example:

userdb default/info set mail=/home/mail/info

this command accesses the address info in /etc/courier/userdb/default. see how that works? 🎀

okay so if the second argument to userdb is "set", then the remaining arguments are taken as field=value pairs, and they get added to the record for addr. if there's no record for addr, a brand new record gets appended to the file. if addr does exist, then any existing values of any specified fields get removed first. and if =value is missing?? userdb stops and prompts you for it. this is SO useful when you're setting a password field, because you do not want to type that password on the command line where the ps(1) command can just… see it. nope. no cap. 🙈 and if userdb is being executed by a script, the value can be provided on standard input.

use "unset" to delete fields from an existing record. use "del" to delete all the fields in the existing record, plus the record itself. gone. bye. 💀

---

🎀 DISPLAYING /etc/courier/userdb 🎀

if the first argument to userdb is -show, then userdb displays the contents of /etc/courier/userdb. if /etc/courier/userdb is a subdirectory, path must refer to a specific file inside /etc/courier/userdb. and the -f option can be used instead of path if you wanna specify an arbitrary file 💅

if addr is not specified, userdb produces a list on standard output containing all addresses found in the file, one per line. if addr is specified, userdb produces a list on standard output of all the fields in /etc/courier/userdb for this addr. easy. iconic. 🌟

---

🌈 International domains 🌈

addrs with international domains should use UTF-8 to specify an international domain name:

userdb postmaster@test.испытание set \
        home=/home/postmaster.test.com uid=999 gid=999

---

🔥 REBUILDING /etc/courier/userdb.dat 🔥

listen up because this is the part people forget: the actual virtual account/address database is /etc/courier/userdb.dat. that one is a binary database file. /etc/courier/userdb is just the plain text version. so after running userdb, you have to execute the makeuserdb(8) [1] command to rebuild /etc/courier/userdb.dat for your changes to actually take effect. don't skip this step bestie, your changes will just be sitting there unapplied 😭

---

💀 BUGS 💀

addr must be unique. and here's the messy part: if /etc/courier/userdb is a subdirectory, it's possible to create the same addr in different files in the subdirectory. this is an error that is not currently detected by userdb, however the subsequent makeuserdb(8) [1] command will fail with an error message. so like… it'll catch you eventually. not today though. 🙈

---

🍓 FILES 🍓

• /etc/courier/userdb — plain text file, or directory of plain text files
• .lock.filename — lock file for filename
• .tmp.filename — temporary file used to create new contents of filename

---

🧚 SEE ALSO 🧚

makeuserdb(8) [1], userdbpw(8) [2]

---

⭐ NOTES ⭐

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

---

and that's the whole page, bestie!! this was brought to you by Double Precision, Inc., dated 10/28/2020, for USERDB(8) — go forth and manipulate your virtual user database responsibly, mwah 💋✨👑