12 Steps to qmail List Bliss
or, How to Use the qmail Mailing List Effectively
by Charles Cazabon
Version 3.10 Last updated 24 December 2007.
Contents
- Introduction
- Acknowledgements
-
The 12 Steps
- Don't consider posting to the qmail list your first line of defence
- Consider the urgency of your issue.
- Try to narrow down the scope of your problem, and formulate a clear question
- See if your question or problem has been answered before by the list
- Read the mailing list
- So you're going to ask the qmail mailing list a question...
- Include your clear, precise description of the problem
- Ensure your question is really about qmail
- Include other information the list will need to help you
- Ensure your message is readable
- Send your message to the list
- Wait for responses
Introduction
The mailing list for qmail (subscription address: qmail-subscribe@list.cr.yp.to) can be a great support and reference resource. However, it's only valuable if you learn to use it effectively. Here's a general guide of things to do or not do to make the most of the list. Every time you violate one of these guidelines, you reduce the effectiveness of the list both for you, and for others.
Acknowledgements
I'm grateful to the following people for their valuable feedback about this document.
- Peter Green
- Virginia Chism
- Mark Delany
- Erwin Hoffmann
- Paul Theodoropoulos
- Jay Taylor
- Robin Socha
- Jesse Cablek
- Tom Goulet
- Paul Theodoropoulos
- Roger Merchberger
If you have suggestions for this document, please send them to the author at the following email address: <qmaillistbliss at discworld.dyndns.org>.
Note -- CSS not supported in this browser
The presentational aspects of this document are presented with the aid of Cascading Style Sheets; the HTML (XHTML, in fact) is purely structural, as it should be.
However, the web browser you are currently viewing this document with does not appear to understand CSS stylesheets. This document will therefore appear quite plain. Mozilla-based browsers (among others) are quite adept at supporting CSS.
Step 1 - Don't consider posting to the qmail list your first line of defence
Posting a question to the qmail mailing list should be one of your last resorts for information or help. In general, there are other places to obtain most of the information you need about qmail. Using one of those other resources will generally get you the answer faster, and does not use up the bandwidth and time of the other members of the qmail list.
You should be familiar with, and have read, all of the following items, preferably before you try to install qmail for the first time.
-
All of the documentation included in the qmail tar file. This includes the following:
- BLURB* files
- PIC* files
- FAQ
- README
- All of qmail's author's online documentation, starting at http://cr.yp.to/qmail.html . Be especially sure to read the online FAQ, as it contains information not included in the tar file.
-
All of the man pages included in the tar file. Read `man qmail-control`, and then read every other man page referenced from there (i.e. `man qmail-send`, `man qmail-smtpd`, etc). Read the man pages several times, as the information contained in them is very dense and difficult to understand completely on first reading.
Note that the man pages are normally installed under /var/qmail/man/ . You'll have to configure your MANPATH environment variable or other system-dependant method of locating man pages. This procedure is beyond the scope of this document; if you're stuck, most man commands will work properly if you give an explicit path to the file in question (e.g. man /var/qmail/man/.../qmail-command.8).
- All of qmail's author's online documentation for daemontools (http://cr.yp.to/daemontools.html) and ucspi-tcp (http://cr.yp.to/ucspi-tcp.html).
- "Life with qmail" (http://lifewithqmail.org/), the online guide by Dave Sill.
- If possible, also read Dave Sill's book, The qmail Handbook.
- Check the qmail knowledge base at http://qmail.faqts.com/.
-
Have a look at Russell Nelson's excellent qmail community site, located at http://qmail.org/ .
In particular, look at all the entries in the following sections:
- Recommended patches
- User-Contributed Documentation
- Author's Enhancement Software for qmail
- Living with qmail
Read anything that appears to relate to your problem or question.
Have you finished all your reading? No? Then don't go on. Running an MTA on the public Internet is complex; if you're not willing to put in the effort to do it correctly, then you're not ready for the responsibility of running an MTA.
If you post a question to the qmail mailing list which could have been answered by reading any of the above items, you should not be surprised when members of the list react negatively to your efforts to waste their time.
If you've reached this point and still have a question or problem, continue to the next section. If your question was a very general one (e.g. How do I install qmail?) or a FAQ (e.g. SMTP is slow …), you should have all the information needed by this point.
Step 2 - Consider the urgency of your issue
Are your remaining issues or problems with qmail so urgent that you cannot afford to wait a week for a solution? Are you using qmail to generate income, or to support a business? Do you feel a need to be secretive about your configuration data (domain or hostnames, IP addresses, control file contents), or other information?
If the answer to any one of those questions is "yes", don't bother the mailing list. It is impossible for the mailing list to help you under these circumstances, and the knowledgable members of the list will generally ignore your question because of this.
In these cases, you can hire a professional qmail consultant to answer your question or solve your problem for you. See the Commercial Support section at qmail.org for a list of available qmail consultants, or simply hire Russell Nelson.
Step 3 - Try to narrow down the scope of your problem, and formulate a clear question
Try to explain, to yourself, exactly what problem you are facing, as specifically as possible. Email isn't working is a useless statement. Local delivery works, and mail from my private network is accepted and delivered, but mail from public hosts on the internet to the domain handled by my server bounces is much better. Actually including a copy of the bounce message is even better.
Never, ever use the phrase it doesn't work in a problem report.. Instead, show us:
- What you did
- What you expected the computer to do
- What the computer actually did
Explaining your problem to yourself first will help you clarify the problem in your mind before trying to explain the problem to someone else.
Be careful that you don't formulate a useless or misleading question. Read http://homepages.tesco.net/~J.deBoynePollard/FGA/questions-with-yes-or-no-answers.html for more information on this.
One mistake many people make is to describe only their intended solution to their problem, and not the problem itself. For instance, some people in the past have encountered a problem (say, they find their outgoing messages don't have the "wibble" flag set). They decide that they need to change qmail-remote (the program that performs remote deliveries) to manually set this flag on every outgoing message, but they're not sure how to do so. So they ask the list "How do I change qmail-remote to set the wibble flag?", resulting in responses such as "qmail-remote doesn't have anything to do with message content" or "What problem are you trying to solve?".
Perhaps there's a better solution than the one you've thought of; we won't be able to tell you unless we know what the actual problem is. In this example, if you actually asked "My messages don't have the wibble flag set; how do I fix that?", you might have immediately got a response like "Use the -w option to qmail-inject when you inject the message" and have the problem fixed in seconds.
For a pretty good general (i.e. non-qmail) discussion on good questions versus stupid questions, please read http://perl.plover.com/Questions.html.
Step 4 - See if your question or problem has been answered before
If you've reached this step, and read everything you're supposed to have read by now, the question or problem you're facing must not be handled by the available documentation. However, very few problems in the world are new; it's almost certain that someone else has already encountered (and likely solved) the same issue you're facing.
You need to search two places for answers to your question before posting it to the mailing list:
-
the archives of the qmail mailing list
Using keywords from the specific question or statement you formulated in step 3 above, search the mailing list archives for related discussions. See the searchable list archives at one of the following URLs:
-
the web (ie STFW)
Use Google or another search engine to search for anything related to your question or problem. Use the word "qmail" and your problem's keywords to search for answers. Don't just scan the first few results; visit and read every page in the results.
Don't whine "But there's too many results to read them all!" All that means is you haven't formulated a clear enough question in step 3 above. Try again.
Step 5 - Read the mailing list
At this point, you should make sure you are subscribed to the mailing list, and that you've been reading it for least several weeks. In that time, you may see someone else ask a question about the problem you are having, and will likely see answers or suggestions for further diagnosis.
In addition, reading the list for a period of time will help you get a feel for the tone and content of the list. You will gain a greater understanding of what is expected of people asking questions, and learn to differentiate between good advice and bad advice from various people on the mailing list. If you're not sure whether advice you have received is trustworthy, try searching for other postings from that person in one of the mailing list archives; that might give you some sense of its value.
If you can't wait this long, go back to step 2 above.
Step 6 - So you're going to ask the qmail mailing list a question...
If you've reached this step, then you have a problem with qmail that you have been unable to resolve. You've read all the documentation, including that written by other members of the qmail user community. You've decided that your problem isn't critical enough to warrant commercial qmail support, and that you can wait a week or more for a final solution. You've come up with a clear, precise description of your problem. You've searched the qmail mailing list archives for similar problems, and you haven't found a solution that works for you.
The next step is to start preparing your submission to the qmail mailing list. Don't expect to bang off a quick message in three minutes; you need to put some thought and effort into this.
Follow the rest of these steps with care.
Step 7 - Include your clear, precise description of the problem
Make sure this is one of the very first things you put in your message to the qmail mailing list. If you ramble on about other things first, your problem will likely be missed by those members of the list who scan messages briefly.
Also be sure to include an actual question. If you describe (for example) how messages to given subset of your users appear to be bouncing, and that you've eliminated all the known common causes of this from consideration, ask how you can further diagnose the problem. Not including a question may make it difficult for others to know exactly what you expect in response. If your post is going to be more than a few paragraphs, consider posting your actual question as a one-sentence abstract to start your message.
Tell us what similar problems you found in your search of the various support resources, and why the solutions to those problems do not apply or do not work in your case.
Step 8 - Ensure your question is really about qmail
Once you've formulated a clear description of the problem, and included an actual question, perhaps you will realize your question is really about a different package such as qmail-ldap, VMailMgr, vpopmail, procmail, maildrop, getmail, or something else.
Or perhaps you will realize your question is really about your OS and its included utilities, or is a general Unix administration question, or is a general technical question (How does SMTP work?).
Questions like these are not appropriate for the qmail mailing list. There are other resources and mailing lists for such questions; please don't clutter the qmail list with them.
Step 9 - Include other information the list will need to help you
The mailing list members will need much other information to be able to help you. At a minimum, include the following information:
- a concise description of how you installed and configured qmail (e.g. I installed precisely according to the Life with qmail installation, with the exception that I modified conf-split to be 53, and I changed the number of log files kept by multilog for qmail-send to 30. ). Be sure to mention if you're using any patches or add-on packages; give us the name of each package or patch, its version number, and the URL from which you obtained it.
- the OS, version, and architecture you are using. i.e., don't write I installed qmail on my Linux system.... Instead, write I installed qmail 1.03 on my RedHat Linux 6.2 system, which has been updated with all of the released errata packages....
- the unedited output of the qmail-showctl command.
- the host and domain names, and IP addresses, of the host or hosts that are involved in the problem. Don't try to obscure these; we need the real host names, and the real IP addresses, to be able to diagnose many problems. If you cannot include the real information in your message, go back and reconsider step 2 above. Please read http://homepages.tesco.net/~J.deBoynePollard/FGA/dont-obscure-your-dns-data.html for more information about why obscuring your DNS information prevents the list from helping you.
- any bounce messages, console error messages, or log entries which occur due to the problem. We need to see the exact contents of these; don't snip the included headers from the bounce message. Don't change the email addresses in the bounce message or log entries. If the log entries are large, put them on a publicly-accessible web server and include the URL in your message. Don't re-type anything; use your system's copy-and-paste features to ensure you don't send versions with missing or added typos.
- if your problem is related to using any scripts (for example, to start or stop services), include exact copies of those scripts in your message.
Step 10 - Ensure your message is readable
Please follow all of these guidelines to ensure that the list members can read your message. If your message is more difficult to read than it needs to be, many list members will simply delete it.
-
make sure that your MUA is configured to send your message as
plain-text, not HTML, multipart/alternative, quoted-printable
(sometimes called quoted-unreadable for good reason), base64, or some
other encoding.
If you don't know how to configure your MUA to not send HTML in messages, I have a copy of a document Gerald E. Boyd wrote with instructions for configuring many common MUAs. - Don't include a stupid email disclaimer in your message to the list; in many cases, these corporate disclaimers contain boilerplate text that actually forbids the list members from responding to (or even reading) your message.
- compose your message by telling your MUA to send a new message to the list submission address. Do not reply to an unrelated list message and remove the previous subject, etc — doing this leaves other bits of the previous message headers in your new message, and makes it look to the rest of the list that you're trying to add something to a previous discussion.
- don't type your message in all-caps; it makes you appear to be shouting, and is considered rude.
- include relevant information in the body of your message. Don't assume that putting it in the Subject: header field is sufficient. Don't include your qmail-showctl output as a MIME attachment.
- Configure your MUA to wrap lines at 72 characters or so; long lines make for unreadable messages in some clients. Also make sure that your MUA doesn't automatically send useless attachments (vcards and such) with every message; it's a waste of bandwidth.
- If you need to supply a large amount of information to explain your problem clearly (i.e., you want the list to see several hundred lines of log entries), put the information on a web or FTP site and include the URL in your message instead of sending it as an attachment.
- Don't include graphic files or other large attachments with your message. If something about your problem requires graphic presentation, put it on a web or FTP site and include the URL in your list message.
- Don't assume that list members all have the same operating system and other software that you do. If your problem seems related to your use of the Schnitzelgruber Corporation's E-Mail Pro Mangler and MS Virus Wrangler™, don't refer to it in your message simply as "mangler". Chances are many of us won't know what software you're talking about. Call it by its full name, including the publisher's name.
-
Make sure your message is in clear, concise, and correct English. If
English is not your first language, that's fine. The members of the
list will do their best to understand your message. However, if your
message is unclear simply because you cannot be bothered to ensure
that it is free of gross spelling or grammatical errors, it may be
ignored completely. To be more explicit:
do not use any of the following in your message:
- Abbreviations
- Misspellings (including "leet"-speak and other abominations of English)
- Lack of punctuation or capitalization
- Incorrect punctuation or capitalization
-
Note that ensuring your spelling is correct includes spelling qmail correctly. It is not any of the following:
- Qmail
- QMAIL
- Q-mail
- q-mail
The correct spelling is qmail. It doesn't matter whether you like this or not; it is the author who gets to choose how it is spelled, and the author has chosen qmail.
-
If you post a followup message (replying to someone else's request for clarification or additional information, or answering specific questions), please do so sensibly:
- Quote only what is necessary. Trim everything else.
- Attribute quotes properly.
-
Post new material underneath older material. Don't top-post!
This bears repeating:
Do not top-post in your replies to the mailing list!
Do not top-post in your replies to the mailing list!
Do not top-post in your replies to the mailing list!
Top-posting makes the list archives un-readable. Top-posting to our mailing list is like dumping excrement in our homes; if you do it, you'll likely not be happy with the response.
Some MUAs, such as Microsoft Outlook and Microsoft Outlook Express, encourage top-posting by their default configuration, or even make it needlessly difficult to quote correctly. If you use one of these broken MUAs and must continue to use it, the following free add-ons can apparently fix them for you:
Outlook Express: http://home.in.tum.de/~jain/software/oe-quotefix/
Outlook: http://home.in.tum.de/~jain/software/outlook-quotefix/
If you don't know what top-posting is, or don't already understand common Usenet and mailing list etiquette, please read the following documents which explain proper quoting style:
Step 11 - Send your message to the list
Send your message using a competent MUA (don't use Outlook Express or a free webmail portal) as either a non-MIME 7-bit text message, or as a single-part text/plain MIME message with a content-transfer-encoding of either "7bit" or "8bit".
Do not send your message in HTML format, or in multipart/alternative, or using base64 or quoted-printable encodings. Doing any of these makes the list harder to read, and is likely to get your message ignored completely by the experts on the list.
Step 12 - Wait for responses
If you've followed all of these steps properly, chances are that the members of the list will be able to read your question and immediately suggest either a solution to your problem or further steps to take to diagnose the cause of the problem. You should see responses like this within a day or two of posting your question to the list.
On the other hand, you may not have included all the necessary information to solve your problem, or you may have stated an ambiguous or otherwise unclear question. In this case, you should expect the responses to mainly be asking you for additional information. Read all the responses carefully. If you follow up on the question, include all the additional information that people have requested.
When your problem is solved, send a summary back to the list, describing the problem, and the solution that you arrived at. This will help others who have similar problems in the future when they search the qmail list archives for solutions to their problem.
Under no circumstances should you post the same question to the list again. If you don't get any responses, it's because of one or more of the following reasons:
- You haven't waited long enough for a response. Be prepared to wait at least several days. The list members are volunteers and are usually busy people.
- You've asked a question which is answered in the documentation or FAQ.
- You asked a very general question, and have not included any information that would help the list members diagnose it.
- Your question wasn't readable enough. People are already being generous by answering your question for free; do not expect them to expend extra effort trying to decipher your spelling mistakes, typos, abbreviations, or vague problem description.
- Your question is off topic or otherwise unsuitable for the qmail list.
When you receive responses (either answers or requests for further information or diagnostic steps):
- Don't brush off questions like Are you sure you typed the script contents correctly? -- it doesn't mean the responder thinks you're an idiot. They are usually asking from experience.
- Don't summarize. If a person asks you for information, don't summarize, re-type, re- word, censor, fold, spindle, or otherwise mutilate it -- give us the exact text that you see.
- Don't become hostile, defensive, or abusive to any of the responders. Most of the long-time members of the list respect the other long-time members; being disrespectful to one may prevent the others from answering your question.
-
Don't ignore any of the responses to your question. The experienced members of the list can frequently glance at your question and answer it in very short form (e.g. /etc/tcp.smtp.cdb or "`man qmail-send`"). If you don't understand the answer, that's fine; ask for clarification. Do not simply ignore their response, as you are likely to receive future responses of "So-and-so already answered that; why didn't that work for you?"
If you appear to be wasting everyone's time by ignoring the answers given to you, you will stop receiving answers. It's that simple.
Doing any of these things is likely to get you ignored, or worse.