dot-qmail(5) dot-qmail(5) NNAAMMEE dot-qmail - control the delivery of mail messages DDEESSCCRRIIPPTTIIOONN Normally the qqmmaaiill--llooccaall program delivers each incoming message to your system mailbox, _h_o_m_e_d_i_r//MMaaiillbbooxx, where _h_o_m_e_d_i_r is your home directory. It can instead write the mail to a different file or directory, forward it to another address, distribute it to a mailing list, or even execute programs, all under your control. TTHHEE QQMMAAIILL FFIILLEE To change qqmmaaiill--llooccaall’s behavior, set up a ..qqmmaaiill file in your home directory. ..qqmmaaiill contains one or more lines. Each line is a delivery instruc- tion. qqmmaaiill--llooccaall follows each instruction in turn. There are five types of delivery instructions: (1) comment; (2) program; (3) forward; (4) mbox; (5) maildir. (1) A comment line begins with a number sign: # this is a comment qqmmaaiill--llooccaall ignores the line. (2) A program line begins with a vertical bar: |preline /usr/ucb/vacation djb qqmmaaiill--llooccaall takes the rest of the line as a command to supply to sshh. See qqmmaaiill--ccoommmmaanndd((88)) for further information. (3) A forward line begins with an ampersand: &me@new.job.com qqmmaaiill--llooccaall takes the rest of the line as a mail address; it uses qqmmaaiill--qquueeuuee to forward the message to that address. The address must contain a fully qualified domain name; it must not contain extra spaces, angle brackets, or comments: # the following examples are WRONG &me@new & & me@new.job.com &me@new.job.com (New Address) If the address begins with a letter or number, you may leave out the ampersand: me@new.job.com Note that qqmmaaiill--llooccaall omits its new RReettuurrnn--PPaatthh line when forward- ing messages. (4) An _m_b_o_x line begins with a slash or dot, and does not end with a slash: /home/djb/Mailbox.sos qqmmaaiill--llooccaall takes the entire line as a filename. It appends the mail message to that file, using fflloocckk-style file locking if pos- sible. qqmmaaiill--llooccaall stores the mail message in _m_b_o_x format, as described in mmbbooxx((55)). WWAARRNNIINNGG:: On many systems, anyone who can read a file can fflloocckk it, and thus hold up qqmmaaiill--llooccaall’s delivery forever. Do not deliver mail to a publicly accessible file! If qqmmaaiill--llooccaall is able to lock the file, but has trouble writing to it (because, for example, the disk is full), it will truncate the file back to its original length. However, it cannot prevent mailbox corruption if the system crashes during delivery. (5) A _m_a_i_l_d_i_r line begins with a slash or dot, and ends with a slash: /home/djb/Maildir/ qqmmaaiill--llooccaall takes the entire line as the name of a directory in _m_a_i_l_d_i_r format. It reliably stores the incoming message in that directory. See mmaaiillddiirr((55)) for more details. If ..qqmmaaiill has the execute bit set, it must not contain any program lines, _m_b_o_x lines, or _m_a_i_l_d_i_r lines. If qqmmaaiill--llooccaall sees any such lines, it will stop and indicate a temporary failure. If ..qqmmaaiill is completely empty (0 bytes long), or does not exist, qqmmaaiill-- llooccaall follows the _d_e_f_a_u_l_t_d_e_l_i_v_e_r_y instructions set by your system administrator; normally _d_e_f_a_u_l_t_d_e_l_i_v_e_r_y is ..//MMaaiillbbooxx, so qqmmaaiill--llooccaall appends the mail message to MMaaiillbbooxx in _m_b_o_x format. ..qqmmaaiill may contain extra spaces and tabs at the end of a line. Blank lines are allowed, but not for the first line of ..qqmmaaiill. If ..qqmmaaiill is world-writable or group-writable, qqmmaaiill--llooccaall stops and indicates a temporary failure. SSAAFFEE QQMMAAIILL EEDDIITTIINNGG Incoming messages can arrive at any moment. If you want to safely edit your ..qqmmaaiill file, first set the sticky bit on your home directory: chmod +t $HOME qqmmaaiill--llooccaall will temporarily defer delivery of any message to you if your home directory is sticky (or group-writable or other-writable, which should never happen). Make sure to chmod -t $HOME when you are done! It’s a good idea to test your new ..qqmmaaiill file as follows: qmail-local -n $USER ~ $USER ’’ ’’ ’’ ’’ ./Mailbox EEXXTTEENNSSIIOONN AADDDDRREESSSSEESS In the qqmmaaiill system, you control all local addresses of the form _u_s_e_r-- _a_n_y_t_h_i_n_g, as well as the address _u_s_e_r itself, where _u_s_e_r is your account name. Delivery to _u_s_e_r--_a_n_y_t_h_i_n_g is controlled by the file _h_o_m_e_d_i_r_/..qqmmaaiill--_a_n_y_t_h_i_n_g. (These rules may be changed by the system administrator; see qqmmaaiill--uusseerrss(5).) The aalliiaass user controls all other addresses. Delivery to _l_o_c_a_l is con- trolled by the file _h_o_m_e_d_i_r_/..qqmmaaiill--_l_o_c_a_l, where _h_o_m_e_d_i_r is aalliiaass’s home directory. In the following description, qqmmaaiill--llooccaall is handling a message addressed to _l_o_c_a_l_@_d_o_m_a_i_n, where _l_o_c_a_l is controlled by ..qqmmaaiill--_e_x_t. Here is what it does. If ..qqmmaaiill--_e_x_t is completely empty, qqmmaaiill--llooccaall follows the _d_e_f_a_u_l_t_d_e_- _l_i_v_e_r_y instructions set by your system administrator. If ..qqmmaaiill--_e_x_t doesn’t exist, qqmmaaiill--llooccaall will try some default ..qqmmaaiill files. For example, if _e_x_t is ffoooo--bbaarr, qqmmaaiill--llooccaall will try first ..qqmmaaiill--ffoooo--bbaarr, then ..qqmmaaiill--ffoooo--ddeeffaauulltt, and finally ..qqmmaaiill--ddeeffaauulltt. If none of these exist, qqmmaaiill--llooccaall will bounce the message. (Excep- tion: for the basic _u_s_e_r address, qqmmaaiill--llooccaall treats a nonexistent ..qqmmaaiill the same as an empty ..qqmmaaiill.) WWAARRNNIINNGG:: For security, qqmmaaiill--llooccaall replaces any dots in _e_x_t with colons before checking ..qqmmaaiill--_e_x_t. For convenience, qqmmaaiill--llooccaall converts any uppercase letters in _e_x_t to lowercase. When qqmmaaiill--llooccaall forwards a message as instructed in ..qqmmaaiill--_e_x_t (or ..qqmmaaiill--ddeeffaauulltt), it checks whether ..qqmmaaiill--_e_x_t--oowwnneerr exists. If so, it uses _l_o_c_a_l--oowwnneerr@@_d_o_m_a_i_n as the envelope sender for the forwarded mes- sage. Otherwise it retains the envelope sender of the original mes- sage. Exception: qqmmaaiill--llooccaall always retains the original envelope sender if it is the empty address or ##@@[[]], i.e., if this is a bounce message. qqmmaaiill--llooccaall also supports vvaarriiaabbllee eennvveellooppee rreettuurrnn ppaatthhss (VERPs): if ..qqmmaaiill--_e_x_t--oowwnneerr and ..qqmmaaiill--_e_x_t--oowwnneerr--ddeeffaauulltt both exist, it uses _l_o_c_a_l--oowwnneerr--@@_d_o_m_a_i_n--@@[[]] as the envelope sender. This will cause a recipient _r_e_c_i_p@@_r_e_c_i_p_h_o_s_t to see an envelope sender of _l_o_c_a_l--oowwnneerr--_r_e_c_i_p==_r_e_c_i_p_h_o_s_t@@_d_o_m_a_i_n. EERRRROORR HHAANNDDLLIINNGG If a delivery instruction fails, qqmmaaiill--llooccaall stops immediately and reports failure. qqmmaaiill--llooccaall handles forwarding after all other instructions, so any error in another type of delivery will prevent all forwarding. If a program returns exit code 99, qqmmaaiill--llooccaall ignores all succeeding lines in ..qqmmaaiill, but it still pays attention to previous forward lines. To set up independent instructions, where a temporary or permanent failure in one instruction does not affect the others, move each instruction into a separate ..qqmmaaiill--_e_x_t file, and set up a central ..qqmmaaiill file that forwards to all of the ..qqmmaaiill--_e_x_ts. Note that qqmmaaiill-- llooccaall can handle any number of forward lines simultaneously. SSEEEE AALLSSOO envelopes(5), maildir(5), mbox(5), qmail-users(5), qmail-local(8), qmail-command(8), qmail-queue(8), qmail-lspawn(8) dot-qmail(5)