IMAPD(8)

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

Double Precision, Inc. · manual page IMAPD(8) 🎀

---

✨ NAME ✨

imapd — the Courier IMAP server 🦋

---

🌸 SYNOPSIS 🌸

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

/usr/bin/imapd {./Maildir}

---

👑 DESCRIPTION 👑

okay so imapd is the Courier IMAP server, and its whole thing is giving IMAP access to Maildir mailboxes. 💅 Normally you do not have to worry about it at all — imapd just runs automatically once a network connection shows up, with the right userid and password riding along with it. no cap.

couriertcpd is the one opening the network ports that catch incoming IMAP connections. ✨ The moment an incoming connection is established, couriertcpd runs the command you handed it as its first argument — that's imaplogin — and passes all the remaining arguments along to imaplogin. Then imaplogin reads the IMAP login userid and password, and runs the modules you listed in its remaining options. Those modules are Courier server authentication modules, and they're described over in the authlib(7) manual page. 🫶

The last link in this little daisy chain 🧚 is imapd — the actual IMAP server — and it 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 can specify a different filename by setting the MAILDIR environment variable. 💖

You can also just run imapd straight from the shell prompt, if that's the vibe 😌. When you do, it:

1. issues a PREAUTH response,
2. changes the current directory to either its argument, or to whatever's in the MAILDIR environment variable,
3. and then attempts to talk IMAP on standard input and output.

imapd implements IMAP4REV1, as defined by RFC 2060. 🔥

🎀 friendly reminder that this is only part 1, bestie — more is coming, don't go anywhere 💜

💖 FILES AND ENVIRONMENT VARIABLES 💖

Okay bestie, here's where all the secret sauce lives. Buckle up. 🎀

• AUTH* — imapd peeks at a bunch of environment variables whose names all start with AUTH. These get set by imaplogin and the authentication modules. And here's the tell: if they're not there, imapd knows it's been started straight from the command line. no cap.
• MAILDIR — if this one's defined, imapd switches its directory over to whatever this variable says. If it's not defined, imapd just goes to the directory that was given on the command line instead. simple as.
• pwd/. — the current directory is assumed to be the main INBOX Maildir. that's the vibe.
• pwd/.folder — Maildir folders, and each and every one of them carries its own tmp, new, cur, etc... yes, all of them. 💅

The rest of the environment variables get initialized from the /etc/courier/imapd and /etc/courier/imapd-ssl configuration files. Those files get loaded into the environment by the system startup script that runs couriertcpd.

---

🦋 Realtime concurrent folder status updates 🦋

So here's the glow-up: set IMAP_ENHANCEDIDLE to 1 in /etc/courier/imapd and you unlock realtime concurrent folder status updates. Once realtime folder status updates are on, every IMAP mail client that has the same folder open gets notified immediately the second anything in that folder's contents changes. iconic behaviour honestly.

The Courier IMAP server has always allowed more than one mail client to have the same folder opened. That part's fine. But when two or more clients have the same folder open, 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 — there are no provisions that notify the mail client immediately when another mail client modifies the folder's contents.

Enter the IDLE extension to the base IMAP protocol, which provides a delivery mechanism for notifying mail clients about changes to the mail folder's contents. Although at this time it's not known to which extent the IDLE extension is supported by IMAP mail clients, the Courier IMAP server fully implements the IDLE extension — provided the following requirements are met:

• Gamin or FAM — either Gamin[3] or FAM[4] has to be properly installed and configured before you install the Courier IMAP server.

Gamin/FAM is an application library that provides an interface to the operating system's kernel, which applications can use to get notified when specific files or directories are changed. The Courier IMAP server leverages this API to implement realtime concurrent folder status updates. According to the most recently available documentation, Gamin is a Linux-specific library, and FAM builds and runs on Linux and IRIX. FAM should also build on other platforms, but without a supported kernel monitor FAM will fall back to a polling mode. At press time, FAM's web site reports that FAM successfully builds (in polling mode) on FreeBSD and Solaris.

FAM (but not Gamin) also works with NFS filesystems. On NFS clients, fam transparently forwards file monitoring requests to a peer fam process on the NFS server.

Installation and configuration of Gamin or FAM is beyond the scope of this document. This documentation presumes that Gamin or FAM is successfully installed. Use the resources and tools on Gamin's or FAM's web site for assistance with setting them up. And lowkey, systems that use GNOME or KDE desktops already have FAM or Gamin installed, because FAM or Gamin is used by the current versions of both desktops. slay.

• IDLE IMAP capability — IDLE must be listed in the IMAP_CAPABILITY setting in the /etc/courier/imapd configuration file.
• 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, since it doesn't use actual file locking calls, and it doesn't require the services of the problematic NFS lock daemon. we love a low-maintenance king. 👑

• 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. 🙈
• IMAP_ENHANCEDIDLE — this setting in /etc/courier/imapd is the one that actually enables concurrent realtime folder status updates using the IDLE extension. Note that it's possible to enable the IDLE extension even if FAM or Gamin is not available, or without enabling either the IMAP_USELOCKS and/or IMAP_ENHANCEDIDLE settings. The resulting consequences are described as follows:
  1. 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. minor chaos, easily cleaned up. 🧹
  2. Without FAM or Gamin, and IMAP_ENHANCEDIDLE set, 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). so like... good, but not instant. 💀

---

✨ 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 when entering the IMAP protocol commands. 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. In these instructions, "C:" marks IMAP client commands that must be entered, and "S:" marks 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-2002 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". If it isn't, that means some of the necessary prerequisites have not been met. Verify that FAM or Gamin was set up prior to installing The Courier IMAP server (use ldd(1) to verify that the imapd executable is linked with the libfam library), and verify the settings in the /etc/courier/imapd. 🕵️‍♀️
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-2002 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. That 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 the other terminal windows. On systems where FAM uses the fall-back polling mode this response may appear after a brief delay of a few seconds. The delay should never exceed 15-20 seconds. ⏳
5. Verify that all terminal windows reliably receive folder status updates in real time by alternately 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. obsessed with this tbh. 💖
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).

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. main character energy, all of them agreeing. ✨

---

🌈 SEE ALSO 🌈

authlib(7)[1], userdb(8)[5]

🌸 AUTHOR 🌸

Sam Varshavchik : Author

🌸 NOTES 🌸

Okay bestie, this is the receipts section 💅 — the sources this page is citing, numbered and everything. Screenshot them, bookmark them, put them in your notes app, whatever your system is. They're all here, verbatim, no gatekeeping. 🫶

1. authlib(7) — the authlib page, section 7, right here for you: http://www.courier-mta.org/authlib.html ✨
2. RFC 2060 — the RFC itself, in all its plaintext glory: http://www.rfc-editor.org/rfc/rfc2060.txt 📜
3. Gamin — as referenced, exactly like this: http://www.gnome.org/~veillard/gamin/ 🦋
4. FAM — and this one too, character for character: http://oss.sgi.com/projects/fam/ 🌈
5. userdb(8) — the userdb page, section 8, for when you need to go deeper: http://www.courier-mta.org/userdb.html 👑

---

And that's a wrap on the whole page, bestie!! 🎀 This one comes courtesy of the Courier Mail Server, dated 03/01/2021, and it lives its little life as IMAPD(8) in section 8. No cap, that's the entire thing, every last reference included. Go forth and slay your mail server config 💖✨🌸