diff options
Diffstat (limited to 'doc/OLD/HTML')
| -rw-r--r-- | doc/OLD/HTML/bincimap-faq.html | 926 | ||||
| -rw-r--r-- | doc/OLD/HTML/bincimap-goals.html | 160 | ||||
| -rw-r--r-- | doc/OLD/HTML/bincimap-imapdir.html | 257 | ||||
| -rw-r--r-- | doc/OLD/HTML/bincimap-tech.html | 503 | ||||
| -rw-r--r-- | doc/OLD/HTML/bincimap.css | 8 |
5 files changed, 1854 insertions, 0 deletions
diff --git a/doc/OLD/HTML/bincimap-faq.html b/doc/OLD/HTML/bincimap-faq.html new file mode 100644 index 0000000..61e7129 --- /dev/null +++ b/doc/OLD/HTML/bincimap-faq.html @@ -0,0 +1,926 @@ +<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd"> +<HTML> + +<HEAD> + <META HTTP-EQUIV="Content-Type" CONTENT="text/html; charset=iso-8859-1"> + <META HTTP-EQUIV="Content-Language" CONTENT="en"> + + <TITLE>Binc IMAP - FAQ</TITLE> + <META NAME="revisit-after" CONTENT="14 days"> + <META NAME="keywords" CONTENT="Binc IMAP FAQ checkpassword daemontools tcpserver xinetd Maildir qmail"> + <META NAME="description" CONTENT="Andreas Aardal Hanssen"> + <META NAME="copyright" CONTENT="Copyright Andreas Aardal Hanssen 2002, 2003"> + <META NAME="distribution" CONTENT="global"> + <META NAME="author" CONTENT="Andreas Aardal Hanssen"> + <LINK REL="stylesheet" HREF="bincimap.css" TYPE="text/css"> + <LINK REL="icon" HREF="/favicon.ico" TYPE="image/ico"> + <LINK REL="shortcut icon" HREF="/favicon.ico"> + +</HEAD> + +<BODY BGCOLOR="#000000"> + +<TABLE WIDTH="95%" ALIGN="CENTER" CELLSPACING="0" CELLPADDING="4"> +<TR> +<TD BGCOLOR="#004444"> + +<TABLE WIDTH="99%" ALIGN="CENTER" CELLSPACING="0" CELLPADDING="4"> + <TR> + <TD CLASS="headtext" BGCOLOR="#226666" ALIGN="LEFT"> + <TABLE> + <TR> + <TD ALIGN="center" VALIGN="middle"><IMG ALT="Binc IMAP logo" SRC="b-button64.png" BORDER="0"></TD> + <TD ALIGN="center" VALIGN="middle">Binc IMAP - FAQ</TD> + </TR> + </TABLE> + </TD> + <TD CLASS="bodytext" BGCOLOR="#226666" ALIGN="RIGHT"> + <A HREF="http://www.gnu.org/licenses/gpl.html">GNU General Public License</A><BR> + Andreas Aardal Hanssen <andreas@hanssen.name> + </TD> + </TR> + <TR> + <TD CLASS="bodytext" BGCOLOR="#FFFFFF" COLSPAN="2"></TD> + </TR> +</TABLE> + +<DIV CLASS="bodytext"> + +<UL> + <LI>General questions + <BLOCKQUOTE> + <P><A HREF="#q1">Q: Why did you start writing Binc IMAP?</A></P> + <P><A HREF="#q2">Q: What is "Binc"?</A></P> + </BLOCKQUOTE> + </LI> + <LI>About Binc IMAP + <BLOCKQUOTE> + <P><A HREF="#q3">Q: What are the advantages of Binc IMAP?</A></P> + <P><A HREF="#q4">Q: So Binc IMAP doesn't focus on security?</A></P> + <P><A HREF="#q5">Q: Is Binc IMAP <I>fast</I>?</A></P> + <P><A HREF="#q6">Q: Is Binc IMAP a stable, secure server?</A></P> + </BLOCKQUOTE> + </LI> + <LI>Configuration + <BLOCKQUOTE> + <P><A HREF="#q7">Q: Which configuration files are used by Binc IMAP?</A></P> + <P><A HREF="#q12">Q: How can I tell Binc IMAP where my mailboxes/folders are?</A></P> + <P><A HREF="#q13">Q: How can I get SSL to work?</A></P> + </BLOCKQUOTE> + </LI> + <LI>Usage + <BLOCKQUOTE> + <P><A HREF="#q14">Q: How do I find my folders in Binc IMAP?</A></P> + </BLOCKQUOTE> + </LI> + <LI>Authentication + <BLOCKQUOTE> + <P><A HREF="#q8">Q: How does Binc IMAP authentication work?</A></P> + </BLOCKQUOTE> + </LI> + <LI>Compiling + <BLOCKQUOTE> + <P><A HREF="#q15">Q: How do I fix this: "Unable to find required function getopt_long"?</A></P> + <P><A HREF="#q16">Q: How do I fix this: "Unable to find the crypto library which is part of OpenSSL"?</A></P> + <P><A HREF="#q17">Q: How do I fix this: "Unable to find the ssl library which is part of OpenSSL"?</A></P> + </BLOCKQUOTE> + </LI> + <LI>Installing + <BLOCKQUOTE> + <P><A HREF="#q10">Q: How do I install Binc IMAP?</A></P> + <P><A HREF="#q11">Q: Why does Binc IMAP (RPM) install under /opt?</A></P> + </BLOCKQUOTE> + </LI> +</UL> + +<HR> + +<A NAME="q1"> +<B><U>Q: Why did you start writing Binc IMAP?</U></B> +</A> + +<BLOCKQUOTE> +<P>First of all, I work a lot with qmail servers, and there haven't +really been many Maildir capable IMAP4rev1 servers around. I used +Courier-IMAP for years, but after loads of abuse from the Courier +community and its author, I found that earth had room for one more +IMAP4rev1 server.</P> + +<P>Enjoying the simplicity of qmail-pop3d, I decided to create an IMAP +server that was equally simple to install and use, and that could work +side-by-side with qmail-pop3d to provide IMAP service to qmail +users.</P> + +<P>I had already written an IMAP server for proxying POP3-accounts at +work, and I had so many good experiences from that project that I +beleived that I could really write a great IMAP server.</P> + +<P>Well, it's up to you to determine how great it is, but I swear it has +it's advantages over the existing Maildir capable IMAP servers out +there.</P> +</BLOCKQUOTE> + +<HR> + +<A NAME="q2"> +<B><U>Q: What is "Binc"?</U></B> +</A> + +<BLOCKQUOTE> + +<P>This should be quite obvious: Binc Is Not Courier-IMAP :-).</P> + +</BLOCKQUOTE> + +<HR> + +<A NAME="q3"> +<B><U>Q: What are the advantages of Binc IMAP?</U></B> +</A> + +<BLOCKQUOTE> + +<P>Binc IMAP is a <I>light weight alternative</I> to existing IMAP +servers. It's easier to install, easier to maintain, and it's easy to +integrate into existing (perhaps legacy) authentication +environments.</P> + +<P>Binc IMAP is small and simple. The total number of lines of source +code is much smaller in Binc than in the other servers. Version +1.0.24-1 of Binc IMAP has about 18000 lines of code. There are only +17000 lines of hand written code, including comments. Few lines in +itself does <I>not</I> imply that the code is better, but it's +certainly much easier to maintain.</P> + +<P>It is also written in C++, using standard C++ data components. If +this server crashes, it'll most likely abort, and not suffer a +segmentation fault, which is the most common reason for exploits.</P> + +<P>Binc IMAP uses an object oriented design all the way. A modular, +simple design with few lines of code means that it's easier to uncover +bugs, and it's easier to fix them without disturbing the rest of the +source code.</P> + +</BLOCKQUOTE> + +<HR> + +<A NAME="q4"> +<B><U>Q: So Binc IMAP doesn't focus on security?</U></B> +</A> + +<UL> + <LI>Security comes naturally with a service with a clean, correct + design and no bugs</LI> + + <LI>Security can not be claimed. To prove that a server is not + secure, one must simply find a way to exploit it. <I>Claiming</I> + that a server is secure is like claiming that nobody can find a way + to break it.</LI> + + <LI>The only true argument is to <I>prove</I> that it's secure. And + that's almost impossible.</LI> + + <LI>Binc IMAP focuses on creating a service with a clean, correct + design with no bugs. Time and experience will tell wether it's a + secure server or not.</LI> +</UL> + +<HR> + +<A NAME="q5"> +<B><U>Q: Is Binc IMAP <I>fast</I>?</U></B> +</A> + +<P>Binc IMAP focuses its optimizations on the type of activity that +dominates the lifetime of an IMAP connection, which is idle time.</P> + + <UL> + <LI>Pending updates: When a client issues NOOP, CHECK or similar, + the server must give the latest changes to the depository. If no + changes have been made, this operation will with Binc IMAP + consist of only two stat-calls, which is extremely fast.</LI> + + <LI>FETCH: Multiple subsequent operations on the same message + will never cause the message to be parsed more than twice - once + for header-only operations and once for full message info.</LI> + + <LI>STATUS: The status command is typically used to check for + new messages in all subscribed mailboxes. If no changes have been + made to a mailbox, the status command in Binc IMAP consists of + only two stat calls, which is extremely fast.</LI> + + <LI>SEARCH: The search keys are weighted, and the search query is + sorted with lightest-search first. This prevents unnecessary + processing of slow search keys if the light search keys do not + match the message set.</LI> + </UL> + +<P>Some activity is not optimal in Binc IMAP, and searching for random +text in particular is no faster than a sequential search using +standard UNIX tools such as <I>grep</I>. Searching for text in a large +mailbox is quite rare, however, compared to the random activity of +close-to-idle clients.</P> + +<HR> + +<A NAME="q6"> +<B><U>Q: Is Binc IMAP a stable, secure server?</U></B> +</A> + +<BLOCKQUOTE> +<P>It's hard to write bug free programs, especially with a complex +protocol like IMAP4rev1. Any attempts to verify code usually comes +down to the limitations in the author's experience with +verification. Or as +<A HREF="http://www-cs-faculty.stanford.edu/~knuth/">Donald Knuth</A> +said (my favorite quote):</P> + +<P><I>"Beware of bugs in the above code; I have only proved it correct, + not tried it."</I></P> + +<P>Knuth teaches that it can be easy to prove that your code is +correct, but who's going to prove that your <I>proof</I> is correct? +Proving your proof might turn out to be close to impossle. What you +can have, is conventions and principles that prevent bugs from showing +up in your programs. Here are mine:</P> + +<UL> + <LI>Don't reinvent the wheel. Unless absolutely necessary, write + code that doesn't exist already.</LI> + <LI>Spend your time on making it work as simple as possible, + then start making optimizations.</LI> + <LI>Don't let optimization obfuscate your source code.</LI> + <LI>Find a better algorithm, or if you can't get the speed that you + want, change to a more efficient programming language.</LI> + <LI>Handle all error conditions.</LI> + <LI>Avoid buffers altogether.</LI> + <LI>Don't hand write parsers unless strictly necessary - they are + hard to get right.</LI> + <LI>For G's sake, be compliant! If the standard has flaws, then + <I>help fix the flaws</I> - don't break the standard.</LI> +</UL> + +<P>Now I don't pay $2.56^n where n equals the total number of +bugs discovered in Binc IMAP, but I will certainly give you +many pats on the back if I get the chance. :-)</P> + +<P>I could go on and on, but the point is that I have tried my best to +perform all the expected tasks in the most logical and obvious way +possible, using all my C++ security experience to aid me. But at the +time of writing, the server is young, the community small, and we are +only in Beta. So time will have to tell how stable and secure we +are.</P> + +</BLOCKQUOTE> + +<HR> + +<A NAME="q7"> +<B><U>Q: Which configuration files are used by Binc IMAP?</U></B> +</A> + +<BLOCKQUOTE> +<UL> + <LI>/etc/opt/bincimap/supervise/imap/run</LI> + <LI>/etc/opt/bincimap/supervise/imaps/run</LI> + <LI>/etc/opt/bincimap/xinetd/imap</LI> + <LI>/etc/opt/bincimap/xinetd/imaps</LI> +</UL> + +<P>These files are for administrators. You can set up Binc IMAP's +authentication method here.</P> + +<UL> +<LI>/etc/opt/bincimap/bincimap.conf</LI> +</UL> + +<P>This first file is for setting global administrator settings, such +as paths to the host's SSL certificate, timeouts for idle clients and +so on. It need not be readable for anyone but root.</P> + +<UL> +<LI>$HOME/.bincimap</LI> +</UL> + +<P>This file is for individual settings, such as what the exact path +is to this user's depository, which default Mailbox type to use and +which type of depository the user uses.</P> + +</BLOCKQUOTE> + +<HR> + +<A NAME="q12"> +<B><U>Q: How can I tell Binc IMAP where my mailboxes/folders are?</U></B> +</A> + +<BLOCKQUOTE> + +<P>The configuration file has a section called <B>Mailbox</B>. You can +set the <B>path</B> to your users' mail depository there, relative to +the users' home areas.</P> + +<P>If your depository is not is users' homeareas, for instance if your +depository has a <B>/var/mail/user/</B> structure, you can safely set +<B>path</B> to <B>"."</B> or <B>""</B>. Your authenticator must then +change to the full path of the depository, <B>/var/mail/user/</B>, +before invoking bincimapd.</P> + +<P>For a <B>Maildir++</B> depository under standard home areas, with +the mailbox path set to "Maildir" in bincimap.conf, your structure +would typically look something like this:</P> + +<TABLE ALIGN="center" CELLSPACING="5" CELLPADDING="5"> + <TR> + <TH BGCOLOR="#555555">File system + </TH> + <TH BGCOLOR="#555555">IMAP + </TH> + <TH BGCOLOR="#555555">Description + </TH> + </TR> + <TR> + <TD BGCOLOR="#555555"> + <PRE> +~/Maildir/ +~/Maildir/.Sent/ + </PRE> + </TD> + <TD BGCOLOR="#555555"> + <PRE> +"INBOX" +"INBOX/Sent" + </PRE> + </TD> + <TD BGCOLOR="#555555"> + <PRE> +The main mailbox, the INBOX. +A user created mailbox. + </PRE> + </TD> + </TR> +</TABLE> + +<P>If you use IMAPdir (setting depot="IMAPdir" and for instance +path="IMAPdir"), the structure would be slightly different:</P> + +<TABLE ALIGN="center" CELLSPACING="5" CELLPADDING="5"> + <TR> + <TH BGCOLOR="#555555">File system + </TH> + <TH BGCOLOR="#555555">IMAP + </TH> + <TH BGCOLOR="#555555">Description + </TH> + </TR> + <TR> + <TD BGCOLOR="#555555"> + <PRE> +~/IMAPdir/INBOX -> ../Maildir +~/IMAPdir/Sent/ +~/IMAPdir/Sent.2003/ +~/Maildir/ + </PRE> + </TD> + <TD BGCOLOR="#555555"> + <PRE> +"INBOX" +"Sent" +"Sent/2003" +<zip> + </PRE> + </TD> + <TD BGCOLOR="#555555"> + <PRE> +The main mailbox symlink, the INBOX. +A user created mailbox. +A sublevel user created mailbox. +Invisible. + </PRE> + </TD> + </TR> +</TABLE> + +<P>With no seperate directory for the mail depository, your structure +would be like this with IMAPdir, and similar with Maildir++ <I>(the +prefix folder is simply dropped, and INBOX itself is a Maildir, note +that the MTA must be instructed to deliver to INBOX and not +Maildir)</I>:</P> + +<TABLE ALIGN="center" CELLSPACING="5" CELLPADDING="5"> + <TR> + <TH BGCOLOR="#555555">File system + </TH> + <TH BGCOLOR="#555555">IMAP + </TH> + <TH BGCOLOR="#555555">Description + </TH> + </TR> + <TR> + <TD BGCOLOR="#555555"> + <PRE> +~/INBOX +~/Sent/ +~/Sent.2003/ + </PRE> + </TD> + <TD BGCOLOR="#555555"> + <PRE> +"INBOX" +"Sent" +"Sent/2003" + </PRE> + </TD> + <TD BGCOLOR="#555555"> + <PRE> +The main mailbox, the INBOX, a Maildir. +A user created mailbox. +A sublevel user created mailbox. + </PRE> + </TD> + </TR> +</TABLE> + +</BLOCKQUOTE> + +<HR> + +<A NAME="q13"> +<B><U>Q: How can I get SSL to work?</U></B> +</A> + +<BLOCKQUOTE> + +<P>SSL in Binc IMAP is quite simple to set up. First you need a PEM +encoded certificate file. In some distributions, you can generate this +file by changing to /usr/share/ssl/certs and running "make". A script +will give you the option to build a PEM file.</P> + +<P>When you have a PEM file, edit <B>bincimap.conf</B> in the SSL +section . You need to add an item called <B>pem file</B> and set it to +point to your PEM certificate. The path name must be absolute. For +example:</P> + +<PRE> + SSL { + pem file = "/usr/share/ssl/certs/mypemfile.pem", + ca file = "", + cipher list = "!ADH:RC4+RSA:HIGH:MEDIUM:LOW:EXP:+SSLv2:+EXP", + verify peer = "no" + } +</PRE> + +<P>The item <B>ca file</B> in <B>bincimap.conf</B> tells Binc IMAP +which file on your system contains a bundle of <B>certificate +authorities</B>.</P> + +<P>Next comes the item called <B>cipher list</B>. It tells Binc IMAP +about which ciphers you want your server to support. This depends on +what version of OpenSSL you're running.</P> + +<P>Last comes an option called <B>verify peer</B>. This tells Binc +IMAP wether to attempt to verify the client's identity.</P> + +<P>Visit <A +HREF="http://httpd.apache.org/docs-2.0/ssl/ssl_intro.html">this link +at the Apache.org website</A> to read more about SSL and TLS +principles.</P> + +</BLOCKQUOTE> + +<HR> + +<A NAME="q14"> +<B><U>Q: How do I find my folders in Binc IMAP?</U></B> +</A> + +<BLOCKQUOTE> + +<P>Binc IMAP can be configured to use two types of depositories: +Maildir++ and IMAPdir.</P> + +<P>Using Maildir++, all folders in Binc IMAP must be subfolders of +INBOX. This is the default setting.</P> + +<P>This means that if you want to create a folder called <B>work</B>, +you have to create <B>INBOX.work</B> or <B>INBOX/work</B>.</P> + +<P>For some graphical IMAP clients like <B>Outlook</B> (look out!) or +<B>Mozilla Mail</B>, this means you need to <I>right click</I> on +<B>INBOX</B> and select "Create subfolder".</P> + +<P>Using IMAPdir, folders can be created in any levels. See also <A +HREF="#q12">this question</A>.</P> + +</BLOCKQUOTE> + +<HR> + +<A NAME="q8"> +<B><U>Q: How does Binc IMAP authentication work?</U></B> +</A> + +<BLOCKQUOTE> +<P>Binc IMAP is spawned by xinetd, tcpserver or any other TCP wrapper +running as root.</P> + +<P>It immediately goes into pre-authentication mode, where it expects +the client to enter STARTTLS if the client is not already running an +SSL connection. When in TLS/SSL mode, it will accept clear text +authentication.</P> + +<P>Binc IMAP uses the same authentication method as +<U>qmail-pop3d</U>, checkpassword. The pre-authentication stub invokes +the checkpassword compatible authenticator, which if the password is +correct in turn invokes the main Binc IMAP daemon.</P> + +<P>The <A HREF="http://cr.yp.to/checkpwd.html">checkpassword documentation</A> is +required reading for everyone running Binc IMAP.</P> + +</BLOCKQUOTE> + +<HR> + +<A NAME="q15"> +<B><U>Q: How do I fix this: "Unable to find required function getopt_long"?</U></B> +</A> + +<BLOCKQUOTE> + +<P>The <U>getopt_long</U> function is a GNU extension to the POSIX.2 <U>getopt</U> +function. It allows long arguments such as <B>--enable-ssl</B>.</P> + +<P>Unfortunately, this function is not defined on all +platforms. Specifically, it is known to not exist on FreeBSD.</P> + +<P>For FreeBSD users, install <U>gnugetopt</U> from ports. Otherwise, +post this problem with as much relevant info as you can provide, to +the mailing list.</P> + +</BLOCKQUOTE> + +<HR> + +<A NAME="q16"> +<B><U>Q: How do I fix this: "Unable to find the crypto library which is part of OpenSSL"?</U></B> +</A> + +<BLOCKQUOTE> + +<P>The <U>crypto</U> library is a part of <A HREF="http://www.openssl.org">OpenSSL</A>. This +library is required for Binc IMAP to compile.</P> + +<P>If you can not get Binc IMAP to compile with OpenSSL, there should +be a <A HREF="dl/RPMS">static RPM package</A> available for download.</P> + +</BLOCKQUOTE> + +<HR> + +<A NAME="q17"> +<B><U>Q: How do I fix this: "Unable to find the ssl library which is part of OpenSSL"?</U></B> +</A> + +<BLOCKQUOTE> + +<P>The <U>crypto</U> library is a part of <A HREF="http://www.openssl.org">OpenSSL</A>. This +library is required for Binc IMAP to compile.</P> + +<P>If you can not get Binc IMAP to compile with OpenSSL, there should +be a <A HREF="dl/RPMS">static RPM package</A> available for download.</P> + +</BLOCKQUOTE> + +<HR> + +<A NAME="q10"> +<B><U>Q: How do I install Binc IMAP?</U></B> +</A> + +<BLOCKQUOTE> + +<P>The <I>easiest</I> way to install Binc IMAP on your server is to +follow these instructions:</P> + +<UL> + <LI>Download the RPM from <A HREF="dl/RPMS">http://www.bincimap.andreas.hanssen.name/dl/RPMS</A></LI> + <LI>Install the RPM</LI> + <LI>Copy, edit and perhaps symlink the configuration files: + <UL> + <LI>with daemontools: + <UL> + <LI>ln -s /etc/opt/bincimap/supervise/imap /service/imap</LI> + <LI>ln -s /etc/opt/bincimap/supervise/imaps /service/imaps</LI> + </UL> + </LI> + <LI>with xinetd: + <UL> + <LI>ln -s /etc/opt/bincimap/xinetd/imap /etc/xinetd.d/imap</LI> + <LI>ln -s /etc/opt/bincimap/xinetd/imaps /etc/xinetd.d/imaps</LI> + <LI>service xinetd restart</LI> + </UL> + </LI> + </UL> + </LI> + <LI>Check that the service is up by connecting using a standard IMAP client</LI> +</UL> + +<P>If you want to build Binc IMAP from source, there's a <B>README</B> +file that gives you the instructions step by step, inside the +tarball. You can also get some clues by inspecting the bundled +<B>bincimap-spec</B> file's <B>install</B> section.</P> + +</BLOCKQUOTE> + +<HR> + +<A NAME="q11"> +<B><U>Q: Why does Binc IMAP (RPM) install under /opt?</U></B> +</A> + +<BLOCKQUOTE> + +<P>The reason for this is that I have tried my best to follow the <A +HREF="http://www.pathname.com/fhs/">File System Hierarchy +Standard</A>.</P> + +<P>Binaries go under <B>/opt/bincimap/bin</B></P> + +<P>Host specific configuration goes under <B>/etc/opt/bincimap</B></P> + +<P>If you want your files elsewhere, there's always the option to build +the project from source. :-)</P> + +</BLOCKQUOTE> + +<HR> + +<TABLE WIDTH="99%" ALIGN="CENTER" CELLSPACING="0" CELLPADDING="4"> + <TR> + <TD CLASS="bodytext" BGCOLOR="#FFFFFF"></TD> + </TR> + <TR> + <TD CLASS="headtext" BGCOLOR="#226666"> + <A HREF="http://validator.w3.org/check/referer"> + <IMG BORDER="0" SRC="http://www.w3.org/Icons/valid-html401" + ALT="Valid HTML 4.01!" HEIGHT="31" WIDTH="88"> + </A> + <A HREF="http://cr.yp.to/djbdns.html"><IMG BORDER="0" WIDTH="88" + HEIGHT="31" SRC="djbdns.jpg" ALT="Powered by djbdns!"></A> + <IMG BORDER="0" WIDTH="88" HEIGHT="30" SRC="binclogo.gif" + ALT="Powered by Binc IMAP"> + </TD> + </TR> +</TABLE> + +</DIV> +</TD> +</TR> +</TABLE> +<BR><BR><BR><BR><BR><BR><BR><BR><BR><BR><BR><BR><BR><BR><BR><BR><BR><BR><BR> +<BR><BR><BR><BR><BR><BR><BR><BR><BR><BR><BR><BR><BR><BR><BR><BR><BR><BR><BR> + +</BODY> +</HTML> ++FLAGS \Flagged +* FETCH (FLAGS (\Seen \Flagged)) +8 OK STORE completed + </PRE> + </LI> + </UL> +</P> + +<P>If all these tests work fine, try connecting with an IMAP client +such as Mozilla, Outlook, Eudora, Netscape, Mutt or Pine.</P> + +</BLOCKQUOTE> + +<HR> + +<A NAME="q14"> +<B><U>Q: How do I find my folders in Binc IMAP?</U></B> +</A> + +<BLOCKQUOTE> + +<P>Binc IMAP can be configured to use two types of depositories: +Maildir++ and IMAPdir.</P> + +<P>Using Maildir++, all folders in Binc IMAP must be subfolders of +INBOX. This is the default setting.</P> + +<P>This means that if you want to create a folder called <B>work</B>, +you have to create <B>INBOX.work</B> or <B>INBOX/work</B>.</P> + +<P>For some graphical IMAP clients like <B>Outlook</B> (look out!) or +<B>Mozilla Mail</B>, this means you need to <I>right click</I> on +<B>INBOX</B> and select "Create subfolder".</P> + +<P>Using IMAPdir, folders can be created in any levels. See also <A +HREF="#q12">this question</A>.</P> + +</BLOCKQUOTE> + +<HR> + +<A NAME="q8"> +<B><U>Q: How does Binc IMAP authentication work?</U></B> +</A> + +<BLOCKQUOTE> +<P>Binc IMAP is spawned by xinetd, tcpserver or any other TCP wrapper +running as root.</P> + +<P>It immediately goes into pre-authentication mode, where it expects +the client to enter STARTTLS if the client is not already running an +SSL connection. When in TLS/SSL mode, it will accept clear text +authentication.</P> + +<P>Binc IMAP uses the same authentication method as +<U>qmail-pop3d</U>, checkpassword. The pre-authentication stub invokes +the checkpassword compatible authenticator, which if the password is +correct in turn invokes the main Binc IMAP daemon.</P> + +<P>The <A HREF="http://cr.yp.to/checkpwd.html">checkpassword documentation</A> is +required reading for everyone running Binc IMAP.</P> + +</BLOCKQUOTE> + +<HR> + +<A NAME="q19"> +<B><U>Q: What does this mean: "Server broke for <userid>, /bin/checkpassword returned 111 (internal error)"?</U></B> +</A> + +<BLOCKQUOTE> + +<P>This log line is printed by <U>bincimap-up</U>, and reflects how +confusing checkpassword can be at times. Most often, though, the +problem is easy to solve.</P> + +<P>Log in as the user who tried to log in. If you are using a virtual +mail account system like vpopmail, become the user that mail accounts +are stored as.</P> + +<P>Try running the bincimapd daemon manually. If you can execute the +binary, there will be no output and the server will simply exit. Most +often, however, you will get an error such as "command not found" or +"permission denied". This should explain quite easily what the problem +is. Note that the bincimapd binary must have read and execute +permissions for all users (755).</P> + +<P>If this didn't solve your problem, please post to the mailing list +a stack trace. To create a stacktrace, attach to tcpserver/xinetd +using "strace -s 1024 -f -p <pid> 2>&1 >dump". Log in to reproduce the +error. Then interrupt the strace program and email the "dump" file to +the mailing list. <B>Note:</B> It is likely that the dump file +contains passwords in plain text.</P> + +</BLOCKQUOTE> + +<HR> + +<A NAME="q15"> +<B><U>Q: How do I fix this: "Unable to find required function getopt_long"?</U></B> +</A> + +<BLOCKQUOTE> + +<P>Note: This only applies to versions 1.1.6 or older.</P> + +<P>The <U>getopt_long</U> function is a GNU extension to the POSIX.2 <U>getopt</U> +function. It allows long arguments such as <B>--enable-ssl</B>.</P> + +<P>Unfortunately, this function is not defined on all +platforms. Specifically, it is known to not exist on FreeBSD.</P> + +<P>For FreeBSD users, install <U>gnugetopt</U> from ports. Otherwise, +post this problem with as much relevant info as you can provide, to +the mailing list.</P> + +</BLOCKQUOTE> + +<HR> + +<A NAME="q16"> +<B><U>Q: How do I fix this: "Unable to find the crypto library which is part of OpenSSL"?</U></B> +</A> + +<BLOCKQUOTE> + +<P>The <U>crypto</U> library is a part of <A HREF="http://www.openssl.org">OpenSSL</A>. This +library is required for Binc IMAP to compile.</P> + +<P>If you can not get Binc IMAP to compile with OpenSSL, there should +be a <A HREF="dl/RPMS">static RPM package</A> available for download.</P> + +</BLOCKQUOTE> + +<HR> + +<A NAME="q17"> +<B><U>Q: How do I fix this: "Unable to find the ssl library which is part of OpenSSL"?</U></B> +</A> + +<BLOCKQUOTE> + +<P>The <U>crypto</U> library is a part of <A HREF="http://www.openssl.org">OpenSSL</A>. This +library is required for Binc IMAP to compile.</P> + +<P>If you can not get Binc IMAP to compile with OpenSSL, there should +be a <A HREF="dl/RPMS">static RPM package</A> available for download.</P> + +</BLOCKQUOTE> + +<HR> + +<A NAME="q10"> +<B><U>Q: How do I install Binc IMAP?</U></B> +</A> + +<BLOCKQUOTE> + +<P>The <I>easiest</I> way to install Binc IMAP on your server is to +follow these instructions:</P> + +<UL> + <LI>Download the RPM from <A HREF="dl/RPMS">http://www.bincimap.andreas.hanssen.name/dl/RPMS</A></LI> + <LI>Install the RPM</LI> + <LI>Copy, edit and perhaps symlink the configuration files: + <UL> + <LI>with daemontools: + <UL> + <LI>ln -s /etc/opt/bincimap/supervise/imap /service/imap</LI> + <LI>ln -s /etc/opt/bincimap/supervise/imaps /service/imaps</LI> + </UL> + </LI> + <LI>with xinetd: + <UL> + <LI>ln -s /etc/opt/bincimap/xinetd/imap /etc/xinetd.d/imap</LI> + <LI>ln -s /etc/opt/bincimap/xinetd/imaps /etc/xinetd.d/imaps</LI> + <LI>service xinetd restart</LI> + </UL> + </LI> + </UL> + </LI> + <LI>Check that the service is up by connecting using a standard IMAP client</LI> +</UL> + +<P>If you want to build Binc IMAP from source, there's a <B>README</B> +file that gives you the instructions step by step, inside the +tarball. You can also get some clues by inspecting the bundled +<B>bincimap-spec</B> file's <B>install</B> section.</P> + +</BLOCKQUOTE> + +<HR> + +<A NAME="q11"> +<B><U>Q: Why does Binc IMAP (RPM) install under /opt?</U></B> +</A> + +<BLOCKQUOTE> + +<P>The reason for this is that I have tried my best to follow the <A +HREF="http://www.pathname.com/fhs/">File System Hierarchy +Standard</A>.</P> + +<P>Binaries go under <B>/opt/bincimap/bin</B></P> + +<P>Host specific configuration goes under <B>/etc/opt/bincimap</B></P> + +<P>If you want your files elsewhere, there's always the option to build +the project from source. :-)</P> + +</BLOCKQUOTE> + +<HR> + +<TABLE WIDTH="99%" ALIGN="CENTER" CELLSPACING="0" CELLPADDING="4"> + <TR> + <TD CLASS="bodytext" BGCOLOR="#FFFFFF"></TD> + </TR> + <TR> + <TD CLASS="headtext" BGCOLOR="#226666"> + <A HREF="http://validator.w3.org/check/referer"> + <IMG BORDER="0" SRC="http://www.w3.org/Icons/valid-html401" + ALT="Valid HTML 4.01!" HEIGHT="31" WIDTH="88"> + </A> + <A HREF="http://cr.yp.to/djbdns.html"><IMG BORDER="0" WIDTH="88" + HEIGHT="31" SRC="djbdns.jpg" ALT="Powered by djbdns!"></A> + <IMG BORDER="0" WIDTH="88" HEIGHT="30" SRC="binclogo.gif" + ALT="Powered by Binc IMAP"> + </TD> + </TR> +</TABLE> + +</DIV> +</TD> +</TR> +</TABLE> +<BR><BR><BR><BR><BR><BR><BR><BR><BR><BR><BR><BR><BR><BR><BR><BR><BR><BR><BR> +<BR><BR><BR><BR><BR><BR><BR><BR><BR><BR><BR><BR><BR><BR><BR><BR><BR><BR><BR> + +</BODY> +</HTML> diff --git a/doc/OLD/HTML/bincimap-goals.html b/doc/OLD/HTML/bincimap-goals.html new file mode 100644 index 0000000..fd387e8 --- /dev/null +++ b/doc/OLD/HTML/bincimap-goals.html @@ -0,0 +1,160 @@ +<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd"> +<HTML> + +<HEAD> + <META HTTP-EQUIV="Content-Type" CONTENT="text/html; charset=iso-8859-1"> + <META HTTP-EQUIV="Content-Language" CONTENT="en"> + + <TITLE>Binc IMAP - Goals</TITLE> + <META NAME="revisit-after" CONTENT="14 days"> + <META NAME="keywords" CONTENT="Binc IMAP Goals checkpassword daemontools tcpserver xinetd Maildir qmail"> + <META NAME="description" CONTENT="Andreas Aardal Hanssen"> + <META NAME="copyright" CONTENT="Copyright Andreas Aardal Hanssen 2002, 2003"> + <META NAME="distribution" CONTENT="global"> + <META NAME="author" CONTENT="Andreas Aardal Hanssen"> + <LINK REL="stylesheet" HREF="bincimap.css" TYPE="text/css"> + <LINK REL="icon" HREF="/favicon.ico" TYPE="image/ico"> + <LINK REL="shortcut icon" HREF="/favicon.ico"> + +</HEAD> + +<BODY BGCOLOR="#000000"> + +<TABLE WIDTH="95%" ALIGN="CENTER" CELLSPACING="0" CELLPADDING="4"> +<TR> +<TD BGCOLOR="#004444"> + +<TABLE WIDTH="99%" ALIGN="CENTER" CELLSPACING="0" CELLPADDING="4"> + <TR> + <TD CLASS="headtext" BGCOLOR="#226666" ALIGN="LEFT"> + <TABLE> + <TR> + <TD ALIGN="center" VALIGN="middle"><IMG ALT="Binc IMAP logo" SRC="b-button64.png" BORDER="0"></TD> + <TD ALIGN="center" VALIGN="middle">Binc IMAP - Goals</TD> + </TR> + </TABLE> + </TD> + <TD CLASS="bodytext" BGCOLOR="#226666" ALIGN="RIGHT"> + <A HREF="http://www.gnu.org/licenses/gpl.html">GNU General Public License</A><BR> + Andreas Aardal Hanssen <andreas@hanssen.name> + </TD> + </TR> + <TR> + <TD CLASS="bodytext" BGCOLOR="#FFFFFF" COLSPAN="2"></TD> + </TR> +</TABLE> + +<BLOCKQUOTE> + +The Binc IMAP project is more than programming. This is a list of the main goals and visions +that the author of Binc IMAP has put to ground. + +<UL> +<LI>Helpful, hospitable community + <UL> + <LI>Although it is expected that users of Binc IMAP do their homework before posting, the server author + and community of the Binc IMAP mailing list will be friendly and will approach everyone with respect. + The same is expected from those who post to the list.</LI> + <LI>There will be no RTFM on the project's mailing list. Flaming and personal insults on the project's mailing list will result in banning of the originator.</LI> + <LI>The community is encouraged to pay back to the project's contributors by <B>sharing</B> their own + contributions to Binc IMAP through the GPL license.</LI> + </UL> +</LI> +<LI>Security through good design + <UL> + <LI>A well designed server is <U>less exposed to bugs</U> than a poorly designed server.</LI> + <LI>The server will strive to use <U>every kind of security enhancing feature</U>, while + keeping the implementation details as simple as possible.</LI> + <LI><U>The source is open</U> and downloadable. Potential bugs and/or nasty pieces of + code are easily uncovered when the whole community is able to study every line of + code in detail. Bugs should always be reported to the project's mailing list.</LI> + </UL> +</LI> +<LI>No competition + <UL> + <LI>Under no circumstance will this project be in market driven competition with other + IMAP servers.</LI> + <LI>Binc IMAP is first and foremost a <U>quality driven project</U>.</LI> + <LI>This project is meant to <U><I>influence</I> the community</U> of authors of + network protocols and servers, and hopes to increase the general quality + of software that is used all over the globe and beyond.</LI> + </UL> +</LI> +<LI>Modularity + <UL> + <LI><B>Binary modularity</B> + <P><U>Pluggable extension support.</U> Modules that are loaded into Binc can change a + great deal of Binc's behavior. Adding your own extension or altering Binc + IMAP's behavior should be as easy as it can get, and it should not require a + recompile of the Binc IMAP core.</P> + <P><U>Pluggable authentication support.</U> By supporting <B>checkpassword</B> + compatible authentication modules, Binc IMAP clients can authenticate against great + number of authorities.</P> + </LI> + <LI><B>Source modularity</B> + <P>With a modular and simple yet advanced object oriented design, it should be + easy to quickly understand what every method and function does. This will + increase third party developers' ability to write extensions and modifications fast.</P> + <P>Development of the design and implementation of Binc IMAP will focus on + <U>extensibility, robustness and speed</U>. + </LI> + + </UL> +</LI> +<LI>Quality over quantity + <UL> + <LI>Binc IMAP's releases are milestones. We strive for perfection.</LI> + <LI>Work on improving the existing design and extensibility will always go ahead of + adding new features.</LI> + <LI>Through extensive module support, the community is encouraged to contribute + to the adding and testing of new features. Core design and implementation will + always focus on quality.</LI> + </UL> +</LI> +</UL> + +<HR> +Last updated: 2003-03-24 + + +</BLOCKQUOTE> + +<TABLE WIDTH="99%" ALIGN="CENTER" CELLSPACING="0" CELLPADDING="4"> + <TR> + <TD CLASS="bodytext" BGCOLOR="#FFFFFF"></TD> + </TR> + <TR> + <TD CLASS="headtext" BGCOLOR="#226666"> + <A HREF="http://validator.w3.org/check/referer"> + <IMG BORDER="0" SRC="http://www.w3.org/Icons/valid-html401" + ALT="Valid HTML 4.01!" HEIGHT="31" WIDTH="88"> + </A> + <A HREF="http://cr.yp.to/djbdns.html"><IMG BORDER="0" WIDTH="88" + HEIGHT="31" SRC="djbdns.jpg" ALT="Powered by djbdns!"></A> + <IMG BORDER="0" WIDTH="88" HEIGHT="30" SRC="binclogo.gif" + ALT="Powered by Binc IMAP"> + </TD> + </TR> +</TABLE> + +</TD> +</TR> +</TABLE> +<BR><BR><BR><BR><BR><BR><BR><BR><BR><BR><BR><BR><BR><BR><BR><BR><BR><BR><BR> +<BR><BR><BR><BR><BR><BR><BR><BR><BR><BR><BR><BR><BR><BR><BR><BR><BR><BR><BR> + +</BODY> +</HTML> +"> + </TD> + </TR> +</TABLE> + +</TD> +</TR> +</TABLE> +<BR><BR><BR><BR><BR><BR><BR><BR><BR><BR><BR><BR><BR><BR><BR><BR><BR><BR><BR> +<BR><BR><BR><BR><BR><BR><BR><BR><BR><BR><BR><BR><BR><BR><BR><BR><BR><BR><BR> + +</BODY> +</HTML> diff --git a/doc/OLD/HTML/bincimap-imapdir.html b/doc/OLD/HTML/bincimap-imapdir.html new file mode 100644 index 0000000..2309a0d --- /dev/null +++ b/doc/OLD/HTML/bincimap-imapdir.html @@ -0,0 +1,257 @@ +<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd"> +<HTML> + +<HEAD> + <META HTTP-EQUIV="Content-Type" CONTENT="text/html; charset=iso-8859-1"> + <META HTTP-EQUIV="Content-Language" CONTENT="en"> + + <TITLE>Binc IMAP - IMAPdir</TITLE> + <META NAME="revisit-after" CONTENT="14 days"> + <META NAME="keywords" CONTENT="Binc IMAP imapdir checkpassword daemontools tcpserver xinetd Maildir qmail"> + <META NAME="description" CONTENT="Andreas Aardal Hanssen"> + <META NAME="copyright" CONTENT="Copyright Andreas Aardal Hanssen 2002, 2003"> + <META NAME="distribution" CONTENT="global"> + <META NAME="author" CONTENT="Andreas Aardal Hanssen"> + <LINK REL="stylesheet" HREF="bincimap.css" TYPE="text/css"> + <LINK REL="icon" HREF="/favicon.ico" TYPE="image/ico"> + <LINK REL="shortcut icon" HREF="/favicon.ico"> + +</HEAD> + +<BODY BGCOLOR="#000000"> + +<TABLE WIDTH="95%" ALIGN="CENTER" CELLSPACING="0" CELLPADDING="4"> +<TR> +<TD BGCOLOR="#004444"> + +<TABLE WIDTH="99%" ALIGN="CENTER" CELLSPACING="0" CELLPADDING="4"> + <TR> + <TD CLASS="headtext" BGCOLOR="#226666" ALIGN="LEFT"> + <TABLE> + <TR> + <TD ALIGN="center" VALIGN="middle"><IMG ALT="Binc IMAP logo" SRC="b-button64.png" BORDER="0"></TD> + <TD ALIGN="center" VALIGN="middle">Binc IMAP - IMAPdir</TD> + </TR> + </TABLE> + </TD> + <TD CLASS="bodytext" BGCOLOR="#226666" ALIGN="RIGHT"> + <A HREF="http://www.gnu.org/licenses/gpl.html">GNU General Public License</A><BR> + Andreas Aardal Hanssen <andreas@hanssen.name> + </TD> + </TR> + <TR> + <TD CLASS="bodytext" BGCOLOR="#FFFFFF" COLSPAN="2"></TD> + </TR> +</TABLE> + +<DIV CLASS="bodytext"> + +<BLOCKQUOTE> + +<P>This document describes the generic mail folder structure +<B>IMAPdir</B>.</P> + +<P>The goal of the work behind this specification is to provide the +community with an unambiguous representation of a mailbox hierarchy +where a mailbox name has a one-to-one match against a file system +representation. The hierarchy and naming style is inspired by the +IMAP4 protocol.</P> + +<P>Rather than being a completely new mailbox format, this specification +sets conventions on how to represent a mailbox hierarchy on a file +system, using existing mailbox formats. <B>IMAPdir</B> is not bound to +any protocol.</P> + +<P><B>IMAPdir</B> works with any mailbox format where one mailbox can +be identified by a file, a directory or a symbolic link. One entry in +an <B>IMAPdir</B> folder is a candidate for a mailbox. If the +<B>IMAPdir</B> client can not identify a directory entry as a +selectable mailbox, then the client must either skip the entry or +mark it as invalid (in IMAP, marked as \NoSelect).</P> + +<UL> +<LI>There is no limitation to the type of file system or the number of +file systems represented inside an <B>IMAPdir</B>.</LI> +<LI>There are no reserved ordinary folder +names such as "Sent", "Draft" or "Trash".</LI> +<LI>Clients of the mailboxes inside an <B>IMAPdir</B> +folder <I>must</I> follow the respective format and protocol conventions +strictly.</LI> +</UL> + +<P>The format of a mailbox representation in <B>IMAPdir</B> is a +sequence of one or more US-ASCII characters (32-126), encoded using +the following rules:</P> + +<UL> +<LI>A dot '.' character represents a soft hierarchy delimiter with two exceptions: + <UL> + <LI>A leading dot represents the dot itself.</LI> + <LI>A dot '.' preceded by a backslash '\' represents the dot '.' itself.</LI> + </UL> +</LI> +<LI>A backslash '\' preceded by a backslash '\' represents the backslash '\' itself. For all other cases than before a dot '.' or a backslash '\', a stray backslash '\' character is considered an error.</LI> +<LI>A backslash '\' as the first character of an entry is considered an error.</LI> +<LI>All other characters represent themselves.</LI> +</UL> + +Note that the protocol used to fetch the mailbox using the +structuring <B>IMAPdir</B> convention may restrict the character set +allowed. The clients <I>must</I> in those cases translate the mailbox +names to a selectable format. + +<P>As with <A +HREF="http://www.inter7.com/courierimap/README.maildirquota.html">Maildir++</A>, +submailboxes can not be represented in a recursive fashion in the file +system. The mailbox' representation name will contain the soft +hierarchy delimiter character dot '.', and all mailboxes must reside +in the same root level directory.</P> + +<P>The following example shows the typical content of an +<B>IMAPdir</B> stored under the directory <B>mail/</B>. The <B>file +system</B> column displays the contents as viewed by the UNIX command +'ls -al -F'.</P> + +<TABLE ALIGN="center" CELLSPACING="5" CELLPADDING="5"> + <TR> + <TH BGCOLOR="#555555">File system + </TH> + <TH BGCOLOR="#555555">IMAP + </TH> + <TH BGCOLOR="#555555">Description + </TH> + </TR> + <TR> + <TD BGCOLOR="#555555"> + <PRE> +mail/INBOX -> /var/mail/paul +mail/INBOX.old/ -> ../Maildir/ +mail/INBOX.outbox/ +mail/work +mail/3rd\. of July +mail/Sent.2003.Jan/ +mail/Sent.2003.Feb/ +mail/Sent.2003.Mar/ +mail/.foo + </PRE> + </TD> + <TD BGCOLOR="#555555"> + <PRE> +"INBOX" +"INBOX/old" +"INBOX/outbox" +"work" +"3rd. of July" +"Sent/2003/Jan" +"Sent/2003/Feb" +"Sent/2003/Mar" +".foo" + </PRE> + </TD> + <TD BGCOLOR="#555555"> + <PRE> +Symbolic link to mbox +Symbolic link to Maildir +Maildir +mbox +mbox +Maildir +Maildir +Maildir +mbox + </PRE> + </TD> + </TR> +</TABLE> + +<P>In other multi level mailbox formats, <B>INBOX</B> is treated as a +special case.</P> + +<BLOCKQUOTE> + <P><U><B>Maildir++</B></U></P> + + <UL> + <LI><A + HREF="http://www.inter7.com/courierimap/README.maildirquota.html">Maildir++</A> + defines the mail directory itself as + <B>INBOX</B>. Any subdirectories inside starting with a single dot + '.', and containing the file <B>maildirfolder</B> are interpreted as + a <A + HREF="http://www.inter7.com/courierimap/README.maildirquota.html">Maildir++</A> + submailbox. + + <LI><P>A <A HREF="http://cr.yp.to/proto/maildir.html">Maildir</A> is by + Dan J. Bernstein's definition identified by a directory that + contains the subdirectories <B>cur</B>, + <B>new</B> and <B>tmp</B> and nothing else.</LI> + + <LI>The <A + HREF="http://www.inter7.com/courierimap/README.maildirquota.html">Maildir++</A> + definition follows naturally from <A + HREF="http://www.inter7.com/courierimap/README.maildirquota.html">Maildir++</A> + being an extension to Dan J. Bernstein's <A + HREF="http://cr.yp.to/proto/maildir.html">Maildir</A> + format. However, although the directory ~/Maildir/ itself is a + standard representation of INBOX for <A + HREF="http://cr.yp.to/proto/maildir.html">Maildir</A> clients, it is + not standard for other mailbox formats. With <A + HREF="http://www.inter7.com/courierimap/README.maildirquota.html">Maildir++</A>, + your mailboxes and INBOX in particular must be a <A + HREF="http://cr.yp.to/proto/maildir.html">Maildir</A>. + </UL> + + <P><U><B>mbox</B></U></P> + + <UL> + <LI>When using the <B>mbox</B> storage format, the user's INBOX is typically + stored at /var/spool/mail/<username>.</LI> + + <LI>Using this format, the mail depository client must both have the + path to the user's INBOX <I>and</I> the path to the user's local + mailbox depository, typically <B>mail/</B>.</LI> + </UL> + +</BLOCKQUOTE> + +<P>Note that although <B>IMAPdir</B> has no restrictions with regards +to mailbox names, the protocol that uses <B>IMAPdir</B> might. For +example, IMAP servers will require the mailbox <B>INBOX</B> to be +present.</P> + +<HR> + +<P>Last updated on <B>2003-03-20</B>.</P> + +<P>Please direct comments to <B>IMAPdir</B> or this document to the +<A HREF="/#mailinglist">Binc IMAP mailing list</A>. Remember to <I>search the archives</I> +first.</P> + +</BLOCKQUOTE> + +<TABLE WIDTH="99%" ALIGN="CENTER" CELLSPACING="0" CELLPADDING="4"> + <TR> + <TD CLASS="bodytext" BGCOLOR="#FFFFFF"></TD> + </TR> + <TR> + <TD CLASS="headtext" BGCOLOR="#226666"> + <A HREF="http://validator.w3.org/check/referer"> + <IMG BORDER="0" SRC="http://www.w3.org/Icons/valid-html401" + ALT="Valid HTML 4.01!" HEIGHT="31" WIDTH="88"> + </A> + <A HREF="http://cr.yp.to/djbdns.html"><IMG BORDER="0" WIDTH="88" + HEIGHT="31" SRC="djbdns.jpg" ALT="Powered by djbdns!"></A> + <IMG BORDER="0" WIDTH="88" HEIGHT="30" SRC="binclogo.gif" + ALT="Powered by Binc IMAP"> + </TD> + </TR> +</TABLE> + +</DIV> +</TD> +</TR> +</TABLE> +<BR><BR><BR><BR><BR><BR><BR><BR><BR><BR><BR><BR><BR><BR><BR><BR><BR><BR><BR> +<BR><BR><BR><BR><BR><BR><BR><BR><BR><BR><BR><BR><BR><BR><BR><BR><BR><BR><BR> + +</BODY> +</HTML> diff --git a/doc/OLD/HTML/bincimap-tech.html b/doc/OLD/HTML/bincimap-tech.html new file mode 100644 index 0000000..e5fce32 --- /dev/null +++ b/doc/OLD/HTML/bincimap-tech.html @@ -0,0 +1,503 @@ +<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd"> +<HTML> + +<HEAD> + <META HTTP-EQUIV="Content-Type" CONTENT="text/html; charset=iso-8859-1"> + <META HTTP-EQUIV="Content-Language" CONTENT="en"> + + <TITLE>Binc IMAP - Technical Documentation</TITLE> + <META NAME="revisit-after" CONTENT="14 days"> + <META NAME="keywords" CONTENT="Binc IMAP technical documentation checkpassword daemontools tcpserver xinetd Maildir qmail"> + <META NAME="description" CONTENT="Andreas Aardal Hanssen"> + <META NAME="copyright" CONTENT="Copyright Andreas Aardal Hanssen 2002, 2003"> + <META NAME="distribution" CONTENT="global"> + <META NAME="author" CONTENT="Andreas Aardal Hanssen"> + <LINK REL="stylesheet" HREF="bincimap.css" TYPE="text/css"> + <LINK REL="icon" HREF="/favicon.ico" TYPE="image/ico"> + <LINK REL="shortcut icon" HREF="/favicon.ico"> + +</HEAD> + +<BODY BGCOLOR="#000000"> + +<TABLE WIDTH="95%" ALIGN="CENTER" CELLSPACING="0" CELLPADDING="4"> +<TR> +<TD BGCOLOR="#004444"> + +<TABLE WIDTH="99%" ALIGN="CENTER" CELLSPACING="0" CELLPADDING="4"> + <TR> + <TD CLASS="headtext" BGCOLOR="#226666" ALIGN="LEFT"> + <TABLE> + <TR> + <TD ALIGN="center" VALIGN="middle"><IMG ALT="Binc IMAP logo" SRC="b-button64.png" BORDER="0"></TD> + <TD ALIGN="center" VALIGN="middle">Binc IMAP - Technical Documentation</TD> + </TR> + </TABLE> + </TD> + <TD CLASS="bodytext" BGCOLOR="#226666" ALIGN="RIGHT"> + <A HREF="http://www.gnu.org/licenses/gpl.html">GNU General Public License</A><BR> + Andreas Aardal Hanssen <andreas@hanssen.name> + </TD> + </TR> + <TR> + <TD CLASS="bodytext" BGCOLOR="#FFFFFF" COLSPAN="2"></TD> + </TR> +</TABLE> + +<DIV CLASS="bodytext"> + +<P><U><B>Binc in my home area, IMAPdir and cousins</B></U></P> + +<BLOCKQUOTE> + +<P>Binc IMAP uses either <A +HREF="http://www.inter7.com/courierimap/README.maildirquota.html">Maildir++</A> +or a structure called <A HREF="bincimap-imapdir.html">IMAPdir</A> to +store its set of mailboxes. <A +HREF="bincimap-imapdir.html">IMAPdir</A> is more or less similar to <A +HREF="http://www.inter7.com/courierimap/README.maildirquota.html">Maildir++</A>, +but it provides more flexibility with regards to mailbox names and +hierarchy structure.</P> + +<P>In a sense, <A HREF="bincimap-imapdir.html">IMAPdir</A> takes all +the goods from <A +HREF="http://cr.yp.to/proto/maildir.html">Maildir</A> and adds root +level mailboxes, submailboxes both of regular root level mailboxes and +of the special mailbox INBOX, mail in mailboxes of any level, and with +no restrictions.</P> + +<P>In the root of the <A HREF="bincimap-imapdir.html">IMAPdir</A> +structure, Binc IMAP stores the list of a user's subscribed folders in +a file called +<B>bincimap-subscribed</B>. This file should only be edited manually +if you are confident with <B>Binc::Storage</B>. Normally the +administrator and the IMAP user will leave this to Binc IMAP.</P> + +<P>Binc IMAP's <A +HREF="http://cr.yp.to/proto/maildir.html">Maildir</A> backend +(default) will temporarily create a lock file called +<B>bincimap-scan-lock</B> inside a <A +HREF="http://cr.yp.to/proto/maildir.html">Maildir</A> when it is +scanning for mailbox changes and delegating unique message +identifiers. This is to ensure that UIDs are delegated exactly once to +every message that has been detected by any one Binc IMAP server +instance.</P> + +<P>Inside each <A +HREF="http://cr.yp.to/proto/maildir.html">Maildir</A>, Binc IMAP +stores two files that allow multiple instances of the server to +communicate the state and changes of the mailbox: +<B>bincimap-uidvalidity</B> and +<B>bincimap-cache</B>. These files are safe to delete, although that +will trigger UIDVALIDITY to bounce and clients may have to +resynchronize their local state.</P> + +</BLOCKQUOTE> + +<P><U><B>Object Oriented Design: Brokers, Depots, Operators.</B></U></P> + +<BLOCKQUOTE> + +<TABLE WIDTH="100%"> + <TR> + <TD VALIGN="TOP"> + <P>Binc IMAP's design is <I>simple</I> and <I>modular</I>. This + makes it <I>easy</I> to maintain and extend.</P> + + <P>Although the IMAP protocol is relatively complex, you will + find that Binc IMAP's solution is surprisingly easy to + grasp.</P> + + <P>At the heart of Binc IMAP's implementation lies the basic + functionality for Object Oriented Design provided by the ISO C++ + standard and general knowledge in the area of standard Design + Patterns.</P> + + <P>The main components are:</P> + + <UL> + <LI>The <A HREF="#Broker">Broker</A></LI> + <LI>The <A HREF="#BrokerFactory">BrokerFactory</A></LI> + <LI>The <A HREF="#Command">Command</A></LI> + <LI>The <A HREF="#Depot">Depot</A></LI> + <LI>The <A HREF="#DepotFactory">DepotFactory</A></LI> + <LI>The <A HREF="#Mailbox">Mailbox</A></LI> + <LI>The <A HREF="#Operator">Operator</A></LI> + <LI>The <A HREF="#Session">Session</A></LI> + <LI>The <A HREF="#IO">IO</A></LI> + </UL> + </TD> + <TD> + <IMG BORDER="0" SRC="bincimap-design-tiny.png" ALT="Binc IMAP, Object Oriented Design"> + </TD> + </TR> +</TABLE> + +<HR> +<A NAME="Broker"><B>Broker</B></A> + + <P>One <A HREF="#Broker">Broker</A> holds a set of <A + HREF="#Operator">Operators</A>. For each + <I>state</I> Binc IMAP is in, the <A + HREF="#BrokerFactory">BrokerFactory</A> delegates exactly one <A + HREF="#Broker">Broker</A> to hold the relevant <A + HREF="#Operator">Operator</A> objects.</P> + + <P>Typically, an <A HREF="#Operator">Operator</A> can be assigned to + more than one <A HREF="#Broker">Broker</A>. For example, the <A + HREF="#Operator">Operator</A> that serves the IMAP command "NOOP" (a + command that is available in all three IMAP <I>states</I>), + <B>NoopOperator</B>, is available in all <A + HREF="#Broker">Broker</A> objects.</P> + + <P>The <A HREF="#Broker">Broker</A> is responsible for first passing + the <A HREF="#Depot">Depot</A> and the <A HREF="#IO">IO</A> + singleton to the appropriate <A HREF="#Operator">Operator</A>, + generating a <A HREF="#Command">Command</A> object.</P> + + <P>The <A HREF="#Broker">Broker</A> is also responsible for passing + the resulting <A HREF="#Command">Command</A> object to the <A + HREF="#Operator">Operator</A> together with the <A + HREF="#Depot">Depot</A>, generating the <I>untagged responses</I> + that come as a result of the processing.</P> + + <BR> + <TABLE> + <TR> + <TD BGCOLOR="#555555"> + <PRE> +Broker *broker = BrokerFactory.getBroker(STATE_SELECTED); +if (broker != NULL) + throw CriticalException("no broker for selected state"); + +Command command; + +try { + broker.parse(com, command); + broker.process(depot, command); +} catch (... + </PRE> + </TD> + </TR> + </TABLE> + +<HR> +<A NAME="BrokerFactory"><B>BrokerFactory</B></A> + + <P>The <A HREF="#BrokerFactory">BrokerFactory</A> manages the <A + HREF="#Broker">Broker</A> objects.</P> + + <P>Given a <I>state</I>, the <A + HREF="#BrokerFactory">BrokerFactory</A> provides a <A + HREF="#Broker">Broker</A> that holds all the <A + HREF="#Operator">Operator</A> objects available to the client.</P> + + <P>This provides a modular and safe separation of the priviledges + available at the different <I>states</I> in the IMAP session.</P> + + <P>The <I>preauthenticate stub</I> has a <A + HREF="#BrokerFactory">BrokerFactory</A> that can only generate <A + HREF="#Broker">Broker</A> objects for the <I>non-authenticated</I> + state.</P> + +<HR> +<A NAME="Command"><B>Command</B></A> + + <P>A <A HREF="#Command">Command</A> object holds all information + that was passed to the <A HREF="#Operator">Operator</A> that served + a specific IMAP command.</P> + + <P><A HREF="#Command">Command</A> objects are named. Examples of + such names are "CHECK", "SUBSCRIBE" and "LOGOUT".</P> + + <P>For the name "FETCH", the <A HREF="#Command">Command</A> object + is decorated with + <I>sequence set</I>, optionally a <I>section</I> and so on. The + <B>parse()</B> method in each <A HREF="#Operator">Operator</A> is + responsible for decorating the <A HREF="#Command">Command</A> + object.</P> + + <P>The <A HREF="#Command">Command</A> object is + <I>short-lived</I>. It is created, decorated, passed on to the <A + HREF="#Operator">Operator</A>, then discarded.</P> + +<HR> +<A NAME="Depot"><B>Depot</B></A> + + <P>A <A HREF="#Depot">Depot</A> is responsible for handling the + different <A HREF="#Mailbox">Mailbox</A> objects, and it is the + mailbox structure authority.</P> + + <P>Given an IMAP mailbox path as input, a <A HREF="#Depot">Depot</A> + can give the caller a corresponding <A HREF="#Mailbox">Mailbox</A> + object if it finds one that successfully identifies the type of <A + HREF="#Mailbox">Mailbox</A>. + + <P>The <A HREF="#Depot">Depot</A> is also aware of what the + <I>default</I> <A HREF="#Mailbox">Mailbox</A> type object is. This + <A HREF="#Mailbox">Mailbox</A> object is used when creating new IMAP + mailboxes.</P> + + <P>Finally, the <A HREF="#Depot">Depot</A> is used to translate + mailbox names to a representation on the file system and back. There + are currently two specializations of the <A HREF="#Depot">Depot</A> + object available: one for <A + HREF="http://www.inter7.com/courierimap/README.maildirquota.html">Maildir++</A> + and one for <A HREF="bincimap-imapdir.html">IMAPdir</A>. Each has + its own characteristics in how do translate the mailbox hierarchy to + the file system.</P> + + <TABLE> + <TR> + <TD BGCOLOR="#555555"> + <PRE> +Mailbox *mailbox = depot.getDefaultMailbox(); +if (mailbox == NULL) + throw CriticalException("no default mailbox provided"); + +try { + mailbox->imapCreate("work/2003/07/todo"); +} catch (... + </PRE> + </TD> + </TR> + </TABLE> + +<HR> +<A NAME="DepotFactory"><B>DepotFactory</B></A> + + <P>The <A NAME="DepotFactory">DepotFactory</A> manages the <A + HREF="#Depot">Depot</A> objects.</P> + + <P>New <A HREF="#Depot">Depot</A> objects are assigned to the <A + NAME="DepotFactory">DepotFactory</A> in runtime. This makes it easy + to add new <A HREF="#Depot">Depot</A> objects using loadable + modules. The <A HREF="#Depot">Depot</A> objects are registered and + accessed via their <I>names</I>, such as "<A + HREF="http://www.inter7.com/courierimap/README.maildirquota.html">Maildir++</A>" + or "<A HREF="bincimap-imapdir.html">IMAPdir</A>".</P> + + <P>The <A NAME="DepotFactory">DepotFactory</A> gives individual + users of Binc IMAP the option to choose the <A + HREF="#Depot">Depot</A> object that suits their needs the best.</P> + +<HR> +<A NAME="IO"><B>IO</B></A> + + <P>The <A HREF="#IO">IO</A> is a <I>global</I>. It consists of two instances - + <U>com</U> and <U>logger</U>.</P> + + <P><U>com</U> reads and writes characters to and from the client, + and hides the optional SSL encryption.</P> + + <P><U>logger</U> writes characters to Binc IMAP's log files. It + hides the method used to log data. Currently it supports logging to + stderr and syslog.</P> + +<HR> +<A NAME="Mailbox"><B>Mailbox</B></A> + + <P>The <A HREF="#Mailbox">Mailbox</A> is an abstract for Binc IMAP's different + <I>backends</I>. Bundled with Binc is a backend for <A + HREF="http://cr.yp.to/proto/maildir.html">Maildir</A>. The class + Maildir <I>inherits</I> <A HREF="#Mailbox">Mailbox</A>.</P> + + <P>In short, a <A HREF="#Mailbox">Mailbox</A> contains all methods needed for Binc + IMAP to serve a specific backend. It also holds a method to identify + a <A HREF="#Mailbox">Mailbox</A> of its own kind.</P> + + <P>All registered <A HREF="#Mailbox">Mailbox</A> objects are held by the + <A HREF="#Depot">Depot</A>.</P> + + <BR> + <TABLE> + <TR> + <TD BGCOLOR="#555555"> + <PRE> +Mailbox *mailbox = depot.getSelectedMailbox(); +if (mailbox == NULL) + throw CriticalException("no selected mailbox in selected state"); + +mailbox->imapExpunge(); +mailbox->imapClose(); + </PRE> + </TD> + </TR> + </TABLE> + +<HR> +<A NAME="Operator"><B>Operator</B></A> + + <P>An <A HREF="#Operator">Operator</A> is associated with an IMAP command such as + "SEARCH" or "AUTHENTICATE". In short, the <A HREF="#Operator">Operator</A> is used to + perform an arbitrary operation on a <A HREF="#Mailbox">Mailbox</A>.<P> + + <P>Typically, an <A HREF="#Operator">Operator</A> can be assigned to one or more + <A HREF="#Broker">Broker</A> objects. + + <P>Operators contain, among others, the two public methods: + <B>parse()</B> and <B>process()</B>.</P> + + <P>When given the <B>IO singleton</B> as input, the <B>parse()</B> + method generates a <A HREF="#Command">Command</A> object. This object can then be + fed to <B>process()</B> together with a <A HREF="#Depot">Depot</A>.</P> + + <P>When processing its command, an <A HREF="#Operator">Operator</A> is allowed to + generate <I>untagged responses</I> and it can also update the + <I>state</I> of a <A HREF="#Mailbox">Mailbox</A>, the <A HREF="#Depot">Depot</A> or the + <A HREF="#Session">Session</A> singleton.</P> + + <P><A HREF="#Operator">Operator</A> objects are assigned + <I>dynamically</I> to each <A HREF="#Broker">Broker</A>, making it + very easy to write + <I>extensions</I> that add or replace existing <A + HREF="#Operator">Operator</A> objects using Binc IMAP's <I>loadable + module support.</I></P> + +<HR> +<A NAME="Session"><B>Session</B></A> + + <P>The <A HREF="#Session">Session</A> is a <I>singleton</I> object that holds + information that is relevant to the current IMAP session.</P> + + <P>Currently, the <A HREF="#Session">Session</A> contains information about:</P> + + <UL> + <LI>Global configuration (administrator settings)</LI> + <LI>Local configuration (user settings)</LI> + <LI>Command line arguments</LI> + <LI>Folder subscription list</LI> + </UL> + +<HR> + +<P>Last updated on <B>2003-03-20</B>.</P> + +<P>Please direct comments on this document to the <A +HREF="/#mailinglist">Binc IMAP mailing list</A>. Remember to <I>search +the archives</I> first.</P> + +</BLOCKQUOTE> + +<TABLE WIDTH="99%" ALIGN="CENTER" CELLSPACING="0" CELLPADDING="4"> + <TR> + <TD CLASS="bodytext" BGCOLOR="#FFFFFF"></TD> + </TR> + <TR> + <TD CLASS="headtext" BGCOLOR="#226666"> + <A HREF="http://validator.w3.org/check/referer"> + <IMG BORDER="0" SRC="http://www.w3.org/Icons/valid-html401" + ALT="Valid HTML 4.01!" HEIGHT="31" WIDTH="88"> + </A> + <A HREF="http://cr.yp.to/djbdns.html"><IMG BORDER="0" WIDTH="88" + HEIGHT="31" SRC="djbdns.jpg" ALT="Powered by djbdns!"></A> + <IMG BORDER="0" WIDTH="88" HEIGHT="30" SRC="binclogo.gif" + ALT="Powered by Binc IMAP"> + </TD> + </TR> +</TABLE> + +</DIV> +</TD> +</TR> +</TABLE> +<BR><BR><BR><BR><BR><BR><BR><BR><BR><BR><BR><BR><BR><BR><BR><BR><BR><BR><BR> +<BR><BR><BR><BR><BR><BR><BR><BR><BR><BR><BR><BR><BR><BR><BR><BR><BR><BR><BR> + +</BODY> +</HTML> +style with only LF. The MaildirMessage is an + implementation of Message used in Maildir. When using a Maildir + mailbox, Mailbox::iterator will return a reference to a + MaildirMessage. MaildirMessage also uses a MaildirMessageCache + singleton to handle cacheing of messages.</P> + + <P>Although the inside of MaildirMessage both deals with files, + cacheing and MIME, the Operator needs not think about this.</P> + +</BLOCKQUOTE> + +<HR> +<A NAME="Operator"><B>Operator</B></A> +<BLOCKQUOTE> + + <P>An <A HREF="#Operator">Operator</A> is associated with an IMAP command such as + "SEARCH" or "AUTHENTICATE". In short, the <A HREF="#Operator">Operator</A> is used to + perform an arbitrary operation on a <A HREF="#Mailbox">Mailbox</A>.<P> + + <P>Typically, an <A HREF="#Operator">Operator</A> can be assigned to one or more + <A HREF="#Broker">Broker</A> objects. + + <P>Operators contain, among others, the two public methods: + <B>parse()</B> and <B>process()</B>.</P> + + <P>The <B>parse()</B> method decorates a <A + HREF="#Request">Request</A> object. This object can then be fed to + <B>process()</B> together with a <A HREF="#Depot">Depot</A>.</P> + + <P>When processing its request, an <A HREF="#Operator">Operator</A> + is allowed to generate <I>untagged responses</I> and it can also + update the <I>state</I> of a <A HREF="#Mailbox">Mailbox</A>, the <A + HREF="#Depot">Depot</A> or the <A HREF="#Session">Session</A> + singleton.</P> + + <P><A HREF="#Operator">Operator</A> objects are assigned + <I>dynamically</I> to each <A HREF="#Broker">Broker</A>, making it + very easy to write <I>extensions</I> that add or replace existing <A + HREF="#Operator">Operator</A> objects using Binc IMAP's <I>loadable + module support.</I></P> +</BLOCKQUOTE> + +<HR> +<A NAME="Session"><B>Session</B></A> +<BLOCKQUOTE> + <P>The <A HREF="#Session">Session</A> is a <I>singleton</I> object that holds + information that is relevant to the current IMAP session.</P> + + <P>Currently, the <A HREF="#Session">Session</A> contains information about:</P> + + <UL> + <LI>Global configuration (administrator settings)</LI> + <LI>Local configuration (user settings)</LI> + <LI>Command line arguments</LI> + <LI>Folder subscription list</LI> + </UL> +</BLOCKQUOTE> + +<HR> + +<P>Last updated on <B>2003-07-31</B>.</P> + +<P>Please direct comments on this document to the <A +HREF="/#mailinglist">Binc IMAP mailing list</A>. Remember to <I>search +the archives</I> first.</P> + +</BLOCKQUOTE> + +<TABLE WIDTH="99%" ALIGN="CENTER" CELLSPACING="0" CELLPADDING="4"> + <TR> + <TD CLASS="bodytext" BGCOLOR="#FFFFFF"></TD> + </TR> + <TR> + <TD CLASS="headtext" BGCOLOR="#226666"> + <A HREF="http://validator.w3.org/check/referer"> + <IMG BORDER="0" SRC="http://www.w3.org/Icons/valid-html401" + ALT="Valid HTML 4.01!" HEIGHT="31" WIDTH="88"> + </A> + <A HREF="http://cr.yp.to/djbdns.html"><IMG BORDER="0" WIDTH="88" + HEIGHT="31" SRC="djbdns.jpg" ALT="Powered by djbdns!"></A> + <IMG BORDER="0" WIDTH="88" HEIGHT="30" SRC="binclogo.gif" + ALT="Powered by Binc IMAP"> + </TD> + </TR> +</TABLE> + +</DIV> +</TD> +</TR> +</TABLE> +<BR><BR><BR><BR><BR><BR><BR><BR><BR><BR><BR><BR><BR><BR><BR><BR><BR><BR><BR> +<BR><BR><BR><BR><BR><BR><BR><BR><BR><BR><BR><BR><BR><BR><BR><BR><BR><BR><BR> + +</BODY> +</HTML> diff --git a/doc/OLD/HTML/bincimap.css b/doc/OLD/HTML/bincimap.css new file mode 100644 index 0000000..cf6c0b7 --- /dev/null +++ b/doc/OLD/HTML/bincimap.css @@ -0,0 +1,8 @@ +a:link { color: #fff; font-size: 12pt; font-family: Arial, Helvetica, Verdana; text-decoration: underline } +a:active { color: #fff; font-size: 12pt; font-family: Arial, Helvetica, Verdana; text-decoration: underline } +a { color: #fff; font-size: 12pt; font-family: Arial, Helvetica, Verdana; text-decoration: underline } +a:vlink { color: #fff; font-size: 12pt; font-family: Arial, Helvetica, Verdana; text-decoration: underline } +body { color: #fff; font-size: 12pt; font-family: Arial, Helvetica, Verdana } +.bodytext { color: #fff; font-size: 12pt; font-family: Arial, Helvetica, Verdana } +.headtext { color: #fff; font-size: 20pt; font-family: Arial, Helvetica, Verdana } + |