Binc IMAP logo Binc IMAP - FAQ
GNU General Public License
Andreas Aardal Hanssen <andreas@hanssen.name>
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 :-). The 'B' is from my ancient scene nick 'BitBrat/Bitto/Bibr (INF)', which I rarely use today.

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.1.8 of Binc IMAP has about 23000 lines of code. There are only 21000 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 impossible. 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. The server is now approaching two years of age, and so far it's delivered a rock solid experience to its users.

Q: Which configuration files are used by Binc IMAP?
  • /etc/opt/bincimap/service/imap/run
  • /etc/opt/bincimap/service/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?

Note: For SSL to work, Binc IMAP must be compiled with SSL support. To check if your server has this support, run the following command using the full path to bincimap-up:

  ldd /opt/bincimap/bin/bincimap-up
  
  # An alternative is to use otool.
  otool -L /opt/bincimap/bin/bincimap-up

If one of the output lines starts with "libssl", Binc IMAP supports SSL. If not, you need to recompile Binc IMAP with SSL support.

SSL in Binc IMAP is quite simple to set up. First you need a PEM encoded private key and 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.

Note: The PEM file contains a SSL certificate and your server's private key. It usually starts with the words "BEGIN RSA PRIVATE KEY", followed by a sequence of seemingly random characters, followed by "END RSA PRIVATE KEY". Then follows "BEGIN CERTIFICATE", more seemingly random characters and the "END CERTIFICATE".

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. If your certificate is self-signed, you can point to your own CA file or leave the setting empty. If your certificate is signed, have this setting point to your trusted third-party CA file.

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. The default list is usually fine.

Last comes an option called verify peer. This tells Binc IMAP wether to attempt to verify the client's identity.

To verify that SSL is set up correctly, you can connect to the server with a tool bundled with OpenSSL called openssl. Run the following command, replacing "server" with your server name. This should give you the server's greeting:

  # openssl s_client -connect server:993 -crlf
  * OK Welcome to Binc IMAP v1.1.8 (c) Copyright 2002, 2003
  Andreas Aardal Hanssen at 2003-07-13T11:45:25+0200

Note that you must enable SSL on your mail client to be able to connect to Binc IMAP with SSL support.

Visit this link at the Apache.org website to read more about SSL and TLS principles.

Q: How can I check that Binc IMAP is set up correctly?

Firstly, if Binc IMAP is set up correctly, then your users can connect and log in with their username and password, they can list mailboxes, create, rename and delete them, they can select mailboxes and check what messages are there and they can fetch messages and set flags.

To check that Binc IMAP is set up correctly, follow these simple steps:

1) Connection
  • Using telnet, connect to your service on port 143. Replace "server" with your server's name. If the server is set up correctly, you will see this greeting: 
      # telnet server 143
  * OK Welcome to Binc IMAP v1.1.8 (c) Copyright 2002, 2003
  Andreas Aardal Hanssen at 2003-07-13T11:45:25+0200
  • If you have SSL enabled (most likely you do), connect to port 993 with the openssl tool. If the server is set up correctly, you will see this greeting: 
      # openssl s_client -connect server:993 -crlf
  * OK Welcome to Binc IMAP v1.1.8 (c) Copyright 2002, 2003
  Andreas Aardal Hanssen at 2003-07-13T11:45:25+0200
2) Logging in / authenticating
  • Firstly, check your bincimap.conf file, in the "Authentication" section, for this setting: 
    allow plain auth in non ssl = "no"
    If you want users to be able to connect without using SSL, set this to "yes".
  • Using either the telnet (in case of "yes" in the above example) or openssl tool, try the LOGIN command, replacing "username" with one username on your server, and "password" with that user's password. You should get the reply on the second line. 
    1 LOGIN username password
1 LOGIN completed
    Note that you should try logging in with at least two users to check that this feature is working properly.
3) Listing, creating, renaming and deleting mailboxes
  • Enter the following command to list the user's first level mailboxes. You should get at least one line of response (starting with "* LIST") before you get the "2 OK LIST" reponse. 
    2 LIST "" "%"
* LIST (\UnMarked) "/" "INBOX"
2 OK LIST completed
  • Check your bincimap.conf file, under the Mailbox section, and check the "depot" setting. Try creating a mailbox with the following command, replacing mailbox with a name of your choice. Note that if you are using the Maildir++ depot setting, you must use "INBOX/mailbox" instead: 
    3 CREATE mailbox
3 OK CREATE completed
  • Rename the mailbox with this command. Note the "INBOX/" prefix when using a Maildir++ depot. (After that, rerunning the LIST command from above will give you a slightly different result than before): 
    4 RENAME mailbox newmailbox
4 OK RENAME completed
  • Now delete the mailbox with this command: 
    5 DELETE newmailbox
5 OK DELETE completed
4) Selecting a mailbox and looking inside
  • Select your INBOX with this command. Note that the response may be slightly different from in this example: 
    6 SELECT INBOX
* 146 EXISTS
* OK [UIDVALIDITY 1047992537]
* OK [UIDNEXT 2683] 2683 is the next UID
* FLAGS (\Answered \Flagged \Deleted \Recent \Seen \Draft)
* OK [PERMANENTFLAGS (\Answered \Flagged \Deleted \Seen \Draft)] Limited
6 OK [READ-WRITE]
  • Fetch the flags of all your messages with this command. Note that the "..." is for editorial clarity, many lines of output have been omitted in this example: 
    7 FETCH 1:* FLAGS
* 1 FETCH (FLAGS (\Seen \Answered))
* 2 FETCH (FLAGS (\Seen \Answered))
...
* 146 FETCH (FLAGS (\Seen \Answered))
7 OK FETCH completed
  • Set a flag with this command: 
    8 STORE 1 +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 <userid>, /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 <pid> 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 ssl 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/service/imap /service/imap
      • ln -s /etc/opt/bincimap/service/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. :-)

Valid HTML 4.01! Powered by djbdns! Powered by Binc IMAP