IMAPD(8)

💌 IMAPD(8) — the Courier IMAP server, bestie edition ✨

okay so real talk, this is imapd(8), a page from the Double Precision, Inc. corner of the universe, and it's literally the manual for the Courier IMAP server. buckle up 🎀

---

🌸 NAME 🌸

imapd — the Courier IMAP server. that's the whole name section, she's brief and iconic 💅

---

✨ SYNOPSIS ✨

/usr/lib/courier-imap/couriertcpd {couriertcpd options}
                                  {/usr/sbin/imaplogin} [modules...]
                                  {/usr/sbin/imapd} {./Maildir}

/usr/sbin/imapd {./Maildir}

like, two whole ways to summon her, pick your fighter 🫶

---

💖 DESCRIPTION 💖

imapd is the Courier IMAP server, and her whole job is giving IMAP access to Maildir mailboxes. normally you do not have to worry about her at all, because imapd runs automatically after a network connection comes in, accompanied by the appropriate userid and password. she just shows up, does her thing, no notes 💅

couriertcpd opens the network ports that receive incoming IMAP connections. after an incoming network connection is established, couriertcpd runs the command specified by its first argument, which is imaplogin, passing the remaining arguments to imaplogin. then imaplogin reads the IMAP login userid and password, and runs the modules specified by its remaining options — those are Courier server authentication modules, described in the authlib(7) manual page (link's down in NOTES, iykyk).

the last daisy-chained command is imapd, which is the actual IMAP server, and she gets started from the logged-in account's home directory. the sole argument to imapd is the pathname to the default IMAP mailbox, which is usually ./Maildir. some authentication modules are capable of specifying a different filename, by setting the MAILDIR environment variable. slay, flexible queen 👑

imapd may also be invoked from the shell prompt, in which case she issues a PREAUTH response, then changes the current directory to either her argument, or the contents of the MAILDIR environment variable, then attempts to talk IMAP on standard input and output. main character energy, honestly 🌟

imapd implements IMAP4REV1, as defined by RFC 2060 (link in NOTES, bestie 🔗).

---

🦋 FILES AND ENVIRONMENT VARIABLES 🦋

• AUTH* — imapd examines several environment variables whose names start with AUTH; these are set by imaplogin and the authentication modules. their absence is literally how imapd knows she's running from the command line. detective behavior 🔍
• MAILDIR — if defined, imapd changes her directory to the one specified by this environment variable. otherwise she changes her directory to the one specified on the command line.
• pwd/. — the current directory is assumed to be the main INBOX Maildir. that's the whole vibe.
• pwd/.folder — Maildir folders, each one containing their own tmp, new, cur, etc... yes each one gets the full set, no sharing 🎀

other environment variables are initialized from the /etc/courier/imapd and /etc/courier/imapd-ssl configuration files. these files get loaded into the environment by the system startup script that runs couriertcpd. teamwork makes the dream work 🫶

---

🔥 Realtime concurrent folder status updates 🔥

the Courier IMAP server always allows more than one mail client to have the same folder opened. like, always, no cap. but — and this is the plot twist — when two or more clients have the same folder opened, the mail clients may not necessarily know when another client added or removed messages from the folder. the base IMAP protocol specification requires IMAP mail clients to explicitly check for any changes to the folder's contents, and there are no provisions to notify the mail client immediately when the folder's contents are modified by another mail client. rude, but that's the spec 😭

the IDLE extension to the base IMAP protocol provides a delivery mechanism for notifying mail clients of changes to the mail folder's contents. this is the glow-up ✨

⭐ IDLE IMAP capability ⭐

• IDLE must be listed in the IMAP_CAPABILITY setting in the /etc/courier/imapd configuration file. no listing, no vibes.
• IMAP_USELOCKS — this setting in /etc/courier/imapd must be enabled. it uses dot-lock files to synchronize updates to folder indexes between multiple IMAP clients that have the same folder opened.

this setting is safe to use with NFS, because it does not use actual file locking calls, and does not require the services of the problematic NFS lock daemon. we love a low-maintenance icon 💅

• An IMAP mail client that fully supports the IDLE protocol extension. — of course, an IMAP client that supports the IDLE protocol extension is required. at press time the status and extent of IDLE support in most IMAP mail clients is not known. so like... good luck, check your client 🙈

without IMAP_USERLOCKS there exists a small possibility that multiple mail clients will receive a slightly inconsistent folder index if both clients try to update the contents of the folder at the same time. usually, the worst case result is that some clients will eventually end up downloading the same message twice from the server, and caching it incorrectly in the local cache (if the IMAP client caches message contents). clearing the local message cache will quickly eliminate any residual confusion that results from this situation. drama resolved, moving on 💀

without the inotify kernel interface, the Courier IMAP server will manually check for changes to the folder's contents every 60 seconds, in IDLE mode (instead of in real time). sixty whole seconds. an eternity. but she's doing her best 🕰️

---

🧚 Verifying realtime concurrent folder status updates 🧚

use the following procedure to verify that realtime concurrent folder status updates are properly working. it's helpful to be familiar with the IMAP protocol — if that's not the case, just be extra careful in entering the IMAP protocol commands, fr fr. the following instructions describe the procedure for connecting to the IMAP server, and manually issuing IMAP protocol commands, as if they originate from an IMAP client. the instructions use "C:" to indicate IMAP client commands that must be entered, and "S:" to indicate the expected replies from the server.

Note 📌 the actual replies from the server may differ slightly, due to the actual server configuration, and other minor factors. the following examples have long lines wrapped for readability. slight observed differences from the expected replies are normal, but they should still be substantively the same.

1. prepare a test account with a couple of messages. open two or three terminal windows. in each window, connect to the IMAP server, and enter IDLE mode:

S:* OK Courier-IMAP ready. Copyright 1998-2021 Double Precision, Inc.
  See COPYING for distribution information.
C:a login userid password
S:a OK LOGIN Ok.
C:a SELECT INBOX
S:* FLAGS (\Draft \Answered \Flagged \Deleted \Seen \Recent)
  * OK [PERMANENTFLAGS (\Draft \Answered \Flagged \Deleted \Seen)]
    Limited
  * 2 EXISTS
  * 0 RECENT
  * OK [UIDVALIDITY 939609418] Ok
  a OK [READ-WRITE] Ok
C:a IDLE
S:+ entering ENHANCED idle mode

Note 📌 the default Courier IMAP server configuration permits a maximum of four connections from the same IP address. it may be necessary to adjust this setting in /etc/courier/imapd for the duration of this test.

2. the last message from the server must be "entering ENHANCED idle mode". otherwise, it means that some of the necessary prerequisites have not been met. check the list above, bestie ✅
3. open another terminal window, connect to the server, and modify the flags of one of the messages:

S:* OK Courier-IMAP ready. Copyright 1998-2021 Double Precision, Inc.
  See COPYING for distribution information.
C:a login userid password
S:a OK LOGIN Ok.
C:a SELECT INBOX
S:* FLAGS (\Draft \Answered \Flagged \Deleted \Seen \Recent)
  * OK [PERMANENTFLAGS (\Draft \Answered \Flagged \Deleted \Seen)]
    Limited
  * 2 EXISTS
  * 0 RECENT
  * OK [UIDVALIDITY 939609418] Ok
  a OK [READ-WRITE] Ok
C:STORE 1 +FLAGS (\Deleted)
* 1 FETCH (FLAGS (\Deleted))
a OK STORE completed.

4. the last command sets the \Deleted flag on the first message in the folder. immediately after entering the last command, "* 1 FETCH (FLAGS (\Deleted))" should also appear in all other terminal windows. all of them. simultaneously. that's the whole point 🔥
5. verify that all terminal windows reliably receive folder status updates in real time by alternatively entering the commands "a STORE 1 -FLAGS (\Deleted)" and "a STORE 1 +FLAGS (\Deleted)", to toggle the deleted flag on the first message. observe that the message is received by all terminal windows quickly, and reliably. toggle toggle toggle, watch her go 🎀
6. with the \Deleted flag set on the first message, enter the EXPUNGE command, which removes the deleted message from the folder:

C:a EXPUNGE
S:* 1 EXPUNGE
  * 2 EXISTS
  * 0 RECENT
S:a OK EXPUNGE completed

the lines that begin with the "*" character should also appear in all other terminal windows (depending on the initial folder state one of the terminal windows may have a different RECENT message, which is fine). not everything has to match, we're chill about that one 🌈

7. use a mail client to create and send a test message to the test account. as soon as the mail server delivers the message, the following messages should appear in every terminal window:

* 3 EXISTS
* 0 RECENT
* 3 FETCH (FLAGS ())

the numbers in these messages may be different, depending upon the initial contents of the test mail folder. one of the terminal windows should have a different RECENT count, and one of the terminal windows should include a \Recent flag in the untagged FLAGS message. these differences are acceptable; the important thing is to make sure that all terminal windows have the same EXISTS message. that's the vibe check and she passed 👑

---

💀 SEE ALSO 💀

authlib(7), userdb(8) — full links in NOTES below, don't worry 🫶

---

👑 AUTHOR 👑

Sam Varshavchik Author

like, that's the author. we stan 🎀

---

📝 NOTES 📝

1. authlib(7) http://www.courier-mta.org/authlib.html
2. RFC 2060 http://www.rfc-editor.org/rfc/rfc2060.txt
3. userdb(8) http://www.courier-mta.org/userdb.html

---

okay that's the whole page, you made it, proud of you 🥹💖 this edition came from the Courier Mail Server, dated 03/02/2021, and it answers to the name IMAPD(8) — mwah, go configure something 💅✨🌈