Binc IMAP

Date: Thu, 21 Sep 2023 18:12:32 +0200 Subject: added doc directory --- doc/OLD/HTML/bincimap-faq.html | 926 +++++++++++++++++++++++++++++++++++++ doc/OLD/HTML/bincimap-goals.html | 160 +++++++ doc/OLD/HTML/bincimap-imapdir.html | 257 ++++++++++ doc/OLD/HTML/bincimap-tech.html | 503 ++++++++++++++++++++ doc/OLD/HTML/bincimap.css | 8 + 5 files changed, 1854 insertions(+) create mode 100644 doc/OLD/HTML/bincimap-faq.html create mode 100644 doc/OLD/HTML/bincimap-goals.html create mode 100644 doc/OLD/HTML/bincimap-imapdir.html create mode 100644 doc/OLD/HTML/bincimap-tech.html create mode 100644 doc/OLD/HTML/bincimap.css (limited to 'doc/OLD/HTML') 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 @@ + + + + + + + + Binc IMAP - FAQ + + + + + + + + + + + + + + + + + + +

+ + + + + + + + + +

+ + + + + +

Binc IMAP - FAQ

+ GNU General Public License
+ Andreas Aardal Hanssen <andreas@hanssen.name> +

+ +

General questions +
+
Q: Why did you start writing Binc IMAP?
+
Q: What is "Binc"?
+
+
About Binc IMAP +
+
Q: What are the advantages of Binc IMAP?
+
Q: So Binc IMAP doesn't focus on security?
+
Q: Is Binc IMAP fast?
+
Q: Is Binc IMAP a stable, secure server?
+
+
Configuration +
+
Q: Which configuration files are used by Binc IMAP?
+
Q: How can I tell Binc IMAP where my mailboxes/folders are?
+
Q: How can I get SSL to work?
+
+
Usage +
+
Q: How do I find my folders in Binc IMAP?
+
+
Authentication +
+
Q: How does Binc IMAP authentication work?
+
+
Compiling +
+
Q: How do I fix this: "Unable to find required function getopt_long"?
+
Q: How do I fix this: "Unable to find the crypto library which is part of OpenSSL"?
+
Q: How do I fix this: "Unable to find the ssl library which is part of OpenSSL"?
+
+
Installing +
+
Q: How do I install Binc IMAP?
+
Q: Why does Binc IMAP (RPM) install under /opt?
+
+

+ +

+ + +Q: Why did you start writing Binc IMAP? + + +

+
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.
+ +
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.
+ +
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.
+ +
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.
+

+ +

+ + +Q: What is "Binc"? + + +

+ +
This should be quite obvious: Binc Is Not Courier-IMAP :-).
+ +

+ +

+ + +Q: What are the advantages of Binc IMAP? + + +

+ +
Binc IMAP is a light weight alternative to existing IMAP +servers. It's easier to install, easier to maintain, and it's easy to +integrate into existing (perhaps legacy) authentication +environments.
+ +
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 not imply that the code is better, but it's +certainly much easier to maintain.
+ +
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.
+ +
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.
+ +

+ +

+ + +Q: So Binc IMAP doesn't focus on security? + + +

Security comes naturally with a service with a clean, correct + design and no bugs
Security can not be claimed. To prove that a server is not + secure, one must simply find a way to exploit it. Claiming + that a server is secure is like claiming that nobody can find a way + to break it.
The only true argument is to prove that it's secure. And + that's almost impossible.
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.

+ +

+ + +Q: Is Binc IMAP fast? + + +

Binc IMAP focuses its optimizations on the type of activity that +dominates the lifetime of an IMAP connection, which is idle time.

+ +

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.
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.
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.
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.

+ +

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 grep. Searching for text in a large +mailbox is quite rare, however, compared to the random activity of +close-to-idle clients.

+ +

+ + +Q: Is Binc IMAP a stable, secure server? + + +

+
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 +Donald Knuth +said (my favorite quote):
+ +
"Beware of bugs in the above code; I have only proved it correct, + not tried it."
+ +
Knuth teaches that it can be easy to prove that your code is +correct, but who's going to prove that your proof 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:
+ +
+
Don't reinvent the wheel. Unless absolutely necessary, write + code that doesn't exist already.
+
Spend your time on making it work as simple as possible, + then start making optimizations.
+
Don't let optimization obfuscate your source code.
+
Find a better algorithm, or if you can't get the speed that you + want, change to a more efficient programming language.
+
Handle all error conditions.
+
Avoid buffers altogether.
+
Don't hand write parsers unless strictly necessary - they are + hard to get right.
+
For G's sake, be compliant! If the standard has flaws, then + help fix the flaws - don't break the standard.
+
+ +
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. :-)
+ +
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.
+ +

+ +

+ + +Q: Which configuration files are used by Binc IMAP? + + +

+
+
/etc/opt/bincimap/supervise/imap/run
+
/etc/opt/bincimap/supervise/imaps/run
+
/etc/opt/bincimap/xinetd/imap
+
/etc/opt/bincimap/xinetd/imaps
+
+ +
These files are for administrators. You can set up Binc IMAP's +authentication method here.
+ +
+
/etc/opt/bincimap/bincimap.conf
+
+ +
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.
+ +
+
$HOME/.bincimap
+
+ +
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.
+ +

+ +

+ + +Q: How can I tell Binc IMAP where my mailboxes/folders are? + + +

+ +
The configuration file has a section called Mailbox. You can +set the path to your users' mail depository there, relative to +the users' home areas.
+ +
If your depository is not is users' homeareas, for instance if your +depository has a /var/mail/user/ structure, you can safely set +path to "." or "". Your authenticator must then +change to the full path of the depository, /var/mail/user/, +before invoking bincimapd.
+ +
For a Maildir++ depository under standard home areas, with +the mailbox path set to "Maildir" in bincimap.conf, your structure +would typically look something like this:
+ + + + + + + + + + + + +
File system + IMAP + Description +
+
+~/Maildir/
+~/Maildir/.Sent/
+      
+
+
+"INBOX"
+"INBOX/Sent"
+      
+
+
+The main mailbox, the INBOX.
+A user created mailbox.
+      
+
+ +
If you use IMAPdir (setting depot="IMAPdir" and for instance +path="IMAPdir"), the structure would be slightly different:
+ + + + + + + + + + + + +
File system + IMAP + Description +
+
+~/IMAPdir/INBOX -> ../Maildir
+~/IMAPdir/Sent/
+~/IMAPdir/Sent.2003/
+~/Maildir/
+      
+
+
+"INBOX"
+"Sent"
+"Sent/2003"
+<zip>
+      
+
+
+The main mailbox symlink, the INBOX.
+A user created mailbox.
+A sublevel user created mailbox.
+Invisible.
+      
+
+ +
With no seperate directory for the mail depository, your structure +would be like this with IMAPdir, and similar with Maildir++ (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):
+ + + + + + + + + + + + +
File system + IMAP + Description +
+
+~/INBOX
+~/Sent/
+~/Sent.2003/
+      
+
+
+"INBOX"
+"Sent"
+"Sent/2003"
+      
+
+
+The main mailbox, the INBOX, a Maildir.
+A user created mailbox.
+A sublevel user created mailbox.
+      
+
+ +

+ +

+ + +Q: How can I get SSL to work? + + +

+ +
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.
+ +
When you have a PEM file, edit bincimap.conf in the SSL +section . You need to add an item called pem file and set it to +point to your PEM certificate. The path name must be absolute. For +example:
+ +
+  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"
+  }
+
+ +
The item ca file in bincimap.conf tells Binc IMAP +which file on your system contains a bundle of certificate +authorities.
+ +
Next comes the item called cipher list. It tells Binc IMAP +about which ciphers you want your server to support. This depends on +what version of OpenSSL you're running.
+ +
Last comes an option called verify peer. This tells Binc +IMAP wether to attempt to verify the client's identity.
+ +
Visit this link +at the Apache.org website to read more about SSL and TLS +principles.
+ +

+ +

+ + +Q: How do I find my folders in Binc IMAP? + + +

+ +
Binc IMAP can be configured to use two types of depositories: +Maildir++ and IMAPdir.
+ +
Using Maildir++, all folders in Binc IMAP must be subfolders of +INBOX. This is the default setting.
+ +
This means that if you want to create a folder called work, +you have to create INBOX.work or INBOX/work.
+ +
For some graphical IMAP clients like Outlook (look out!) or +Mozilla Mail, this means you need to right click on +INBOX and select "Create subfolder".
+ +
Using IMAPdir, folders can be created in any levels. See also this question.
+ +

+ +

+ + +Q: How does Binc IMAP authentication work? + + +

+
Binc IMAP is spawned by xinetd, tcpserver or any other TCP wrapper +running as root.
+ +
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.
+ +
Binc IMAP uses the same authentication method as +qmail-pop3d, checkpassword. The pre-authentication stub invokes +the checkpassword compatible authenticator, which if the password is +correct in turn invokes the main Binc IMAP daemon.
+ +
The checkpassword documentation is +required reading for everyone running Binc IMAP.
+ +

+ +

+ + +Q: How do I fix this: "Unable to find required function getopt_long"? + + +

+ +
The getopt_long function is a GNU extension to the POSIX.2 getopt +function. It allows long arguments such as --enable-ssl.
+ +
Unfortunately, this function is not defined on all +platforms. Specifically, it is known to not exist on FreeBSD.
+ +
For FreeBSD users, install gnugetopt from ports. Otherwise, +post this problem with as much relevant info as you can provide, to +the mailing list.
+ +

+ +

+ + +Q: How do I fix this: "Unable to find the crypto library which is part of OpenSSL"? + + +

+ +
The crypto library is a part of OpenSSL. This +library is required for Binc IMAP to compile.
+ +
If you can not get Binc IMAP to compile with OpenSSL, there should +be a static RPM package available for download.
+ +

+ +

+ + +Q: How do I fix this: "Unable to find the ssl library which is part of OpenSSL"? + + +

+ +
The crypto library is a part of OpenSSL. This +library is required for Binc IMAP to compile.
+ +
If you can not get Binc IMAP to compile with OpenSSL, there should +be a static RPM package available for download.
+ +

+ +

+ + +Q: How do I install Binc IMAP? + + +

+ +
The easiest way to install Binc IMAP on your server is to +follow these instructions:
+ +
+
Download the RPM from http://www.bincimap.andreas.hanssen.name/dl/RPMS
+
Install the RPM
+
Copy, edit and perhaps symlink the configuration files: +
+
with daemontools: +
+
ln -s /etc/opt/bincimap/supervise/imap /service/imap
+
ln -s /etc/opt/bincimap/supervise/imaps /service/imaps
+
+
+
with xinetd: +
+
ln -s /etc/opt/bincimap/xinetd/imap /etc/xinetd.d/imap
+
ln -s /etc/opt/bincimap/xinetd/imaps /etc/xinetd.d/imaps
+
service xinetd restart
+
+
+
+
+
Check that the service is up by connecting using a standard IMAP client
+
+ +
If you want to build Binc IMAP from source, there's a README +file that gives you the instructions step by step, inside the +tarball. You can also get some clues by inspecting the bundled +bincimap-spec file's install section.
+ +

+ +

+ + +Q: Why does Binc IMAP (RPM) install under /opt? + + +

+ +
The reason for this is that I have tried my best to follow the File System Hierarchy +Standard.
+ +
Binaries go under /opt/bincimap/bin
+ +
Host specific configuration goes under /etc/opt/bincimap
+ +
If you want your files elsewhere, there's always the option to build +the project from source. :-)
+ +

+ +

+ + + + + + + + +

+ +

+

+

+ + + ++FLAGS \Flagged +* FETCH (FLAGS (\Seen \Flagged)) +8 OK STORE completed + + + +

+ +

If all these tests work fine, try connecting with an IMAP client +such as Mozilla, Outlook, Eudora, Netscape, Mutt or Pine.

+ + + +

+ + +Q: How do I find my folders in Binc IMAP? + + +

+ +
Binc IMAP can be configured to use two types of depositories: +Maildir++ and IMAPdir.
+ +
Using Maildir++, all folders in Binc IMAP must be subfolders of +INBOX. This is the default setting.
+ +
This means that if you want to create a folder called work, +you have to create INBOX.work or INBOX/work.
+ +
For some graphical IMAP clients like Outlook (look out!) or +Mozilla Mail, this means you need to right click on +INBOX and select "Create subfolder".
+ +
Using IMAPdir, folders can be created in any levels. See also this question.
+ +

+ +

+ + +Q: How does Binc IMAP authentication work? + + +

+
Binc IMAP is spawned by xinetd, tcpserver or any other TCP wrapper +running as root.
+ +
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.
+ +
Binc IMAP uses the same authentication method as +qmail-pop3d, checkpassword. The pre-authentication stub invokes +the checkpassword compatible authenticator, which if the password is +correct in turn invokes the main Binc IMAP daemon.
+ +
The checkpassword documentation is +required reading for everyone running Binc IMAP.
+ +

+ +

+ + +Q: What does this mean: "Server broke for , /bin/checkpassword returned 111 (internal error)"? + + +

+ +
This log line is printed by bincimap-up, and reflects how +confusing checkpassword can be at times. Most often, though, the +problem is easy to solve.
+ +
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.
+ +
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).
+ +
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 2>&1 >dump". Log in to reproduce the +error. Then interrupt the strace program and email the "dump" file to +the mailing list. Note: It is likely that the dump file +contains passwords in plain text.
+ +

+ +

+ + +Q: How do I fix this: "Unable to find required function getopt_long"? + + +

+ +
Note: This only applies to versions 1.1.6 or older.
+ +
The getopt_long function is a GNU extension to the POSIX.2 getopt +function. It allows long arguments such as --enable-ssl.
+ +
Unfortunately, this function is not defined on all +platforms. Specifically, it is known to not exist on FreeBSD.
+ +
For FreeBSD users, install gnugetopt from ports. Otherwise, +post this problem with as much relevant info as you can provide, to +the mailing list.
+ +

+ +

+ + +Q: How do I fix this: "Unable to find the crypto library which is part of OpenSSL"? + + +

+ +
The crypto library is a part of OpenSSL. This +library is required for Binc IMAP to compile.
+ +
If you can not get Binc IMAP to compile with OpenSSL, there should +be a static RPM package available for download.
+ +

+ +

+ + +Q: How do I fix this: "Unable to find the ssl library which is part of OpenSSL"? + + +

+ +
The crypto library is a part of OpenSSL. This +library is required for Binc IMAP to compile.
+ +
If you can not get Binc IMAP to compile with OpenSSL, there should +be a static RPM package available for download.
+ +

+ +

+ + +Q: How do I install Binc IMAP? + + +

+ +
The easiest way to install Binc IMAP on your server is to +follow these instructions:
+ +
+
Download the RPM from http://www.bincimap.andreas.hanssen.name/dl/RPMS
+
Install the RPM
+
Copy, edit and perhaps symlink the configuration files: +
+
with daemontools: +
+
ln -s /etc/opt/bincimap/supervise/imap /service/imap
+
ln -s /etc/opt/bincimap/supervise/imaps /service/imaps
+
+
+
with xinetd: +
+
ln -s /etc/opt/bincimap/xinetd/imap /etc/xinetd.d/imap
+
ln -s /etc/opt/bincimap/xinetd/imaps /etc/xinetd.d/imaps
+
service xinetd restart
+
+
+
+
+
Check that the service is up by connecting using a standard IMAP client
+
+ +
If you want to build Binc IMAP from source, there's a README +file that gives you the instructions step by step, inside the +tarball. You can also get some clues by inspecting the bundled +bincimap-spec file's install section.
+ +

+ +

+ + +Q: Why does Binc IMAP (RPM) install under /opt? + + +

+ +
The reason for this is that I have tried my best to follow the File System Hierarchy +Standard.
+ +
Binaries go under /opt/bincimap/bin
+ +
Host specific configuration goes under /etc/opt/bincimap
+ +
If you want your files elsewhere, there's always the option to build +the project from source. :-)
+ +

+ +

+ + + + + + + + +

+ +

+ + + + + +

+

+ + + 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 @@ + + + + + + + + Binc IMAP - Goals + + + + + + + + + + + + + + + + + + +

+ + + + + + + + + +

+ + + + + +

Binc IMAP - Goals

+ GNU General Public License
+ Andreas Aardal Hanssen <andreas@hanssen.name> +

+ +

+ +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. + +
+
Helpful, hospitable community +
+
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.
+
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.
+
The community is encouraged to pay back to the project's contributors by sharing their own + contributions to Binc IMAP through the GPL license.
+
+
+
Security through good design +
+
A well designed server is less exposed to bugs than a poorly designed server.
+
The server will strive to use every kind of security enhancing feature, while + keeping the implementation details as simple as possible.
+
The source is open 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.
+
+
+
No competition +
+
Under no circumstance will this project be in market driven competition with other + IMAP servers.
+
Binc IMAP is first and foremost a quality driven project.
+
This project is meant to influence the community 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.
+
+
+
Modularity +
+
Binary modularity +
Pluggable extension support. 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.
+
Pluggable authentication support. By supporting checkpassword + compatible authentication modules, Binc IMAP clients can authenticate against great + number of authorities.
+
+
Source modularity +
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.
+
Development of the design and implementation of Binc IMAP will focus on + extensibility, robustness and speed. +
+ +
+
+
Quality over quantity +
+
Binc IMAP's releases are milestones. We strive for perfection.
+
Work on improving the existing design and extensibility will always go ahead of + adding new features.
+
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.
+
+
+
+ +
+Last updated: 2003-03-24 + + +

+ + + + + + + + +

+ +

+

+

+ + + +"> + + + + + + + +

+

+ + + 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 @@ + + + + + + + + Binc IMAP - IMAPdir + + + + + + + + + + + + + + + + + + +

+ + + + + + + + + +

+ + + + + +

Binc IMAP - IMAPdir

+ GNU General Public License
+ Andreas Aardal Hanssen <andreas@hanssen.name> +

+ +

+ +
This document describes the generic mail folder structure +IMAPdir.
+ +
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.
+ +
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. IMAPdir is not bound to +any protocol.
+ +
IMAPdir works with any mailbox format where one mailbox can +be identified by a file, a directory or a symbolic link. One entry in +an IMAPdir folder is a candidate for a mailbox. If the +IMAPdir 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).
+ +
+
There is no limitation to the type of file system or the number of +file systems represented inside an IMAPdir.
+
There are no reserved ordinary folder +names such as "Sent", "Draft" or "Trash".
+
Clients of the mailboxes inside an IMAPdir +folder must follow the respective format and protocol conventions +strictly.
+
+ +
The format of a mailbox representation in IMAPdir is a +sequence of one or more US-ASCII characters (32-126), encoded using +the following rules:
+ +
+
A dot '.' character represents a soft hierarchy delimiter with two exceptions: +
+
A leading dot represents the dot itself.
+
A dot '.' preceded by a backslash '\' represents the dot '.' itself.
+
+
+
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.
+
A backslash '\' as the first character of an entry is considered an error.
+
All other characters represent themselves.
+
+ +Note that the protocol used to fetch the mailbox using the +structuring IMAPdir convention may restrict the character set +allowed. The clients must in those cases translate the mailbox +names to a selectable format. + +
As with Maildir++, +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.
+ +
The following example shows the typical content of an +IMAPdir stored under the directory mail/. The file +system column displays the contents as viewed by the UNIX command +'ls -al -F'.
+ + + + + + + + + + + + +
File system + IMAP + Description +
+
+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
+      
+
+
+"INBOX"
+"INBOX/old"
+"INBOX/outbox"
+"work"
+"3rd. of July"
+"Sent/2003/Jan"
+"Sent/2003/Feb"
+"Sent/2003/Mar"
+".foo"
+      
+
+
+Symbolic link to mbox
+Symbolic link to Maildir
+Maildir
+mbox
+mbox
+Maildir
+Maildir
+Maildir
+mbox
+      
+
+ +
In other multi level mailbox formats, INBOX is treated as a +special case.
+ +
+
Maildir++
+ +
+
Maildir++ + defines the mail directory itself as + INBOX. Any subdirectories inside starting with a single dot + '.', and containing the file maildirfolder are interpreted as + a Maildir++ + submailbox. + +
A Maildir is by + Dan J. Bernstein's definition identified by a directory that + contains the subdirectories cur, + new and tmp and nothing else.
+ +
The Maildir++ + definition follows naturally from Maildir++ + being an extension to Dan J. Bernstein's Maildir + format. However, although the directory ~/Maildir/ itself is a + standard representation of INBOX for Maildir clients, it is + not standard for other mailbox formats. With Maildir++, + your mailboxes and INBOX in particular must be a Maildir. +
+ +
mbox
+ +
+
When using the mbox storage format, the user's INBOX is typically + stored at /var/spool/mail/<username>.
+ +
Using this format, the mail depository client must both have the + path to the user's INBOX and the path to the user's local + mailbox depository, typically mail/.
+
+ +
+ +
Note that although IMAPdir has no restrictions with regards +to mailbox names, the protocol that uses IMAPdir might. For +example, IMAP servers will require the mailbox INBOX to be +present.
+ +
+ +
Last updated on 2003-03-20.
+ +
Please direct comments to IMAPdir or this document to the +Binc IMAP mailing list. Remember to search the archives +first.
+ +

+ + + + + + + + +

+ +

+

+

+ + + 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 @@ + + + + + + + + Binc IMAP - Technical Documentation + + + + + + + + + + + + + + + + + + +

+ + + + + + + + + +

+ + + + + +

Binc IMAP - Technical Documentation

+ GNU General Public License
+ Andreas Aardal Hanssen <andreas@hanssen.name> +

+ +

Binc in my home area, IMAPdir and cousins

+ +

+ +
Binc IMAP uses either Maildir++ +or a structure called IMAPdir to +store its set of mailboxes. IMAPdir is more or less similar to Maildir++, +but it provides more flexibility with regards to mailbox names and +hierarchy structure.
+ +
In a sense, IMAPdir takes all +the goods from Maildir 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.
+ +
In the root of the IMAPdir +structure, Binc IMAP stores the list of a user's subscribed folders in +a file called +bincimap-subscribed. This file should only be edited manually +if you are confident with Binc::Storage. Normally the +administrator and the IMAP user will leave this to Binc IMAP.
+ +
Binc IMAP's Maildir backend +(default) will temporarily create a lock file called +bincimap-scan-lock inside a Maildir 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.
+ +
Inside each Maildir, Binc IMAP +stores two files that allow multiple instances of the server to +communicate the state and changes of the mailbox: +bincimap-uidvalidity and +bincimap-cache. These files are safe to delete, although that +will trigger UIDVALIDITY to bounce and clients may have to +resynchronize their local state.
+ +

+ +

Object Oriented Design: Brokers, Depots, Operators.

+ +

+ + + + + + +
+
Binc IMAP's design is simple and modular. This + makes it easy to maintain and extend.
+ +
Although the IMAP protocol is relatively complex, you will + find that Binc IMAP's solution is surprisingly easy to + grasp.
+ +
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.
+ +
The main components are:
+ +
+
The Broker
+
The BrokerFactory
+
The Command
+
The Depot
+
The DepotFactory
+
The Mailbox
+
The Operator
+
The Session
+
The IO
+
+ + +
+ +
+Broker + +
One Broker holds a set of Operators. For each + state Binc IMAP is in, the BrokerFactory delegates exactly one Broker to hold the relevant Operator objects.
+ +
Typically, an Operator can be assigned to + more than one Broker. For example, the Operator that serves the IMAP command "NOOP" (a + command that is available in all three IMAP states), + NoopOperator, is available in all Broker objects.
+ +
The Broker is responsible for first passing + the Depot and the IO + singleton to the appropriate Operator, + generating a Command object.
+ +
The Broker is also responsible for passing + the resulting Command object to the Operator together with the Depot, generating the untagged responses + that come as a result of the processing.
+ +
+ + + + +
+
+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 (...
+        
+
+ +
+BrokerFactory + +
The BrokerFactory manages the Broker objects.
+ +
Given a state, the BrokerFactory provides a Broker that holds all the Operator objects available to the client.
+ +
This provides a modular and safe separation of the priviledges + available at the different states in the IMAP session.
+ +
The preauthenticate stub has a BrokerFactory that can only generate Broker objects for the non-authenticated + state.
+ +
+Command + +
A Command object holds all information + that was passed to the Operator that served + a specific IMAP command.
+ +
Command objects are named. Examples of + such names are "CHECK", "SUBSCRIBE" and "LOGOUT".
+ +
For the name "FETCH", the Command object + is decorated with + sequence set, optionally a section and so on. The + parse() method in each Operator is + responsible for decorating the Command + object.
+ +
The Command object is + short-lived. It is created, decorated, passed on to the Operator, then discarded.
+ +
+Depot + +
A Depot is responsible for handling the + different Mailbox objects, and it is the + mailbox structure authority.
+ +
Given an IMAP mailbox path as input, a Depot + can give the caller a corresponding Mailbox + object if it finds one that successfully identifies the type of Mailbox. + +
The Depot is also aware of what the + default Mailbox type object is. This + Mailbox object is used when creating new IMAP + mailboxes.
+ +
Finally, the Depot is used to translate + mailbox names to a representation on the file system and back. There + are currently two specializations of the Depot + object available: one for Maildir++ + and one for IMAPdir. Each has + its own characteristics in how do translate the mailbox hierarchy to + the file system.
+ + + + + +
+
+Mailbox *mailbox = depot.getDefaultMailbox();
+if (mailbox == NULL)
+  throw CriticalException("no default mailbox provided");
+
+try {
+  mailbox->imapCreate("work/2003/07/todo");
+} catch (...
+        
+
+ +
+DepotFactory + +
The DepotFactory manages the Depot objects.
+ +
New Depot objects are assigned to the DepotFactory in runtime. This makes it easy + to add new Depot objects using loadable + modules. The Depot objects are registered and + accessed via their names, such as "Maildir++" + or "IMAPdir".
+ +
The DepotFactory gives individual + users of Binc IMAP the option to choose the Depot object that suits their needs the best.
+ +
+IO + +
The IO is a global. It consists of two instances - + com and logger.
+ +
com reads and writes characters to and from the client, + and hides the optional SSL encryption.
+ +
logger writes characters to Binc IMAP's log files. It + hides the method used to log data. Currently it supports logging to + stderr and syslog.
+ +
+Mailbox + +
The Mailbox is an abstract for Binc IMAP's different + backends. Bundled with Binc is a backend for Maildir. The class + Maildir inherits Mailbox.
+ +
In short, a Mailbox contains all methods needed for Binc + IMAP to serve a specific backend. It also holds a method to identify + a Mailbox of its own kind.
+ +
All registered Mailbox objects are held by the + Depot.
+ +
+ + + + +
+
+Mailbox *mailbox = depot.getSelectedMailbox();
+if (mailbox == NULL)
+  throw CriticalException("no selected mailbox in selected state");
+
+mailbox->imapExpunge();
+mailbox->imapClose();
+        
+
+ +
+Operator + +
An Operator is associated with an IMAP command such as + "SEARCH" or "AUTHENTICATE". In short, the Operator is used to + perform an arbitrary operation on a Mailbox.
+ +
Typically, an Operator can be assigned to one or more + Broker objects. + +
Operators contain, among others, the two public methods: + parse() and process().
+ +
When given the IO singleton as input, the parse() + method generates a Command object. This object can then be + fed to process() together with a Depot.
+ +
When processing its command, an Operator is allowed to + generate untagged responses and it can also update the + state of a Mailbox, the Depot or the + Session singleton.
+ +
Operator objects are assigned + dynamically to each Broker, making it + very easy to write + extensions that add or replace existing Operator objects using Binc IMAP's loadable + module support.
+ +
+Session + +
The Session is a singleton object that holds + information that is relevant to the current IMAP session.
+ +
Currently, the Session contains information about:
+ +
+
Global configuration (administrator settings)
+
Local configuration (user settings)
+
Command line arguments
+
Folder subscription list
+
+ +
+ +
Last updated on 2003-03-20.
+ +
Please direct comments on this document to the Binc IMAP mailing list. Remember to search +the archives first.
+ +

+ + + + + + + + +

+ +

+

+

+ + + +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.

+ +

Although the inside of MaildirMessage both deals with files, + cacheing and MIME, the Operator needs not think about this.

+ + + +

+Operator +

+ +
An Operator is associated with an IMAP command such as + "SEARCH" or "AUTHENTICATE". In short, the Operator is used to + perform an arbitrary operation on a Mailbox.
+ +
Typically, an Operator can be assigned to one or more + Broker objects. + +
Operators contain, among others, the two public methods: + parse() and process().
+ +
The parse() method decorates a Request object. This object can then be fed to + process() together with a Depot.
+ +
When processing its request, an Operator + is allowed to generate untagged responses and it can also + update the state of a Mailbox, the Depot or the Session + singleton.
+ +
Operator objects are assigned + dynamically to each Broker, making it + very easy to write extensions that add or replace existing Operator objects using Binc IMAP's loadable + module support.
+

+ +

+Session +

+
The Session is a singleton object that holds + information that is relevant to the current IMAP session.
+ +
Currently, the Session contains information about:
+ +
+
Global configuration (administrator settings)
+
Local configuration (user settings)
+
Command line arguments
+
Folder subscription list
+
+

+ +

Last updated on 2003-07-31.

+ +

Please direct comments on this document to the Binc IMAP mailing list. Remember to search +the archives first.

+ + + + + + + + + + +

+ +

+ + + + + +

+

+ + + 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 } + -- cgit v1.2.3