POP3Lite Administrator's Manual, version VERSION, DATE.

Copyright © 2000, 2001 Gergely Nagy 8@free.bsd.hu

Permission is granted to copy, distribute and/or modify this document under the terms of the GNU Free Documentation License, Version 1.1 or any later version published by the Free Software Foundation; with the no Invariant Sections, with no Front-Cover Texts, and with no Back-Cover Texts. A copy of the license is included in the section entitled "GNU Free Documentation License".

This is the POP3Lite Administrator's Manual, version VERSION; a documentation of the POP3Lite Post Office Protocol 3 daemon for system administrators.

Introduction
************

This is POP3Lite, a flexible, RFC 1939 compliant Post Office Protocol 3 daemon.

It implements everything mentioned in the RFC (either natively, or via modules), and some other things that are not strictly POP3 related capabilities (such as modules, PAM support, SQL configuration, etc).

It was written because I found no other POP3 daemon, that would suit my needs. The ones I found were either buggy or not flexible enough. I could try to hack my enhancements in one of them, but writing a brand new one seemed to be an easier task.

As far as I know, POP3Lite is the only daemon that is designed to be extensible.

Features
========

The core features of POP3Lite are: Flexibility, stability and security.

As you see, the most outstanding feature is flexibility. We believe that a program should not stop its user (in this case, the system administrator) from extending its capabilities, or replacing its parts. If someone wants to add a new feature, he simply writes a module, and he's ready. If the way a feature is implemented, doesn't suit his needs, he can easily adjust it with a simple module. Anyone who is capable of writing C code can add something to POP3Lite!

During the development of our daemon, we tried to eliminate all possibility of security compromise. We tried to achieve this by not using any static-sized buffers, thus, preventing buffer overruns. The daemon does not use any temporary files, which eliminates another set of holes.  It also tries its best to drop its privileges as soon as possible, and because it runs from the Internet super-server, it does not have to regain those privileges, therefore it can drop them all, once and forever. In stand-alone mode, it does the same. The main process waits for connections, and forks a children when it receives one, then the children behaves exactly the same as if it were started from inetd.

Overview
========

By default, POP3Lite comes with a limited set of commands. It does not even support mailbox handling natively, however, all the necessary modules are included in the distribution to make it compliant with RFC 1939. To get a fully RFC compliant daemon, build the mailbox module into the daemon. To get the APOP command, use the APOP module.

Through modules, it can be extended to use PAM for authentication, read mail from a file in the user's home directory. You can add support for virtual hosting, or for SQL-based configuration.

With modules, everything is possible.

The way POP3Lite handles modules is easy.  The whole daemon is implemented via a set of hooks.  Some of these are predefined, which should exist in all cases, except when you removed them intentionally.

Whenever a module is loaded, the daemon calls the module's initialisation function, which sets up the module: overrides existing hooks, or registers new ones.

A properly written module (all modules in the main distribution are such) keeps a backup of the previous hook-handler, so it can call it if necessary.

This design makes it possible to replace almost any part of the main daemon, without the need to recompile the whole thing, or read through the whole source code. For an administrator, this means that if he wants to add new functionality, he only has to configure it. No compilation or other nasty tricks are required.

Command-line options
********************

Although POP3Lite shouldn't have any options on its command-line, there are a few options. Either because they are standard options, which are nice to have, or options that might prove useful.

--config, -c [file]
     Loads configuration from the specified file, instead of the default one.

     For example: pop3lite --config /etc/pop3lite-2.conf

--define, -D [field]=[value]
     Defines a configuration field, with the same syntax as in the configuration file.

     For example: pop3lite --define "MODULE_LIST=apop, mailbox, pam"

--inetd, -i
     Tells POP3Lite that it is run from inetd. Only available if compiled with standalone support.

--help, -h
     Displays command line options and arguments.

--pidfile, -p [file]
     When running as a daemon, write the pid of the master process to the specified file. Only available if compiled with standalone support.

--undefine, -U [field]
     Deletes a given field from the configuration table.

     For example: pop3lite --undefine userconf.user_options

--version, -v
     Displays the version number.

Configuration
*************

The file sysconfdir/pop3lite.conf contains the configuration for the POP3Lite daemon.

The configuration file is built up from key and value pairs, separated by an equation (=) sign.

A key may only contain alphanumerics, and some other characters, such as dots, underscores, etc.

Ideally, values contain only these characters. However, they may contain others.

Special characters (the quotation mark, the backslash, and the hash mark) can be escaped by prefixing them with a backslash.  However, you only have to escape the backslash if it stands before another special character.

To illustrate this, let's look at an example!

If you want the parser to interpret a value as

     	the quotation mark (")

You would write this:

     	the quotation mark (\")

However, to make it interpret a value as

     	the backslash (\)

You can write it exactly the same.

If you want to quote longer sequences, enclose them in quotation marks.  Note that between the quotes, you don't have to escape other quotes.

The parser treats a value as a list, with blanks or comas separating the items. Therefore, if you want to put any of these characters in a value, you have to enclose it in double quotes.  They can't be escaped otherwise.

Leading and trailing spaces are ignored, everything after an unescaped hash mark is treated as comment, and ignored.

If a line ends with a single, unescaped backslash, the next line will be treated as if it were appended to the current one. This allows breaking up long lines into shorter ones.

Options
-------

Although there are built-in options, they're not guaranteed to have any effect, because any module can re-implement any function, thus making an option useless. However, if you read the module's documentation too, there won't be any problem.

  * AUTO_LOGOUT_TIME The time (in minutes) of inactivity after a session is automatically ended. Defaults to 10.

  * DEFAULT.GREETING The default greeting message. Defaults to POP3 server ready.

  * LISTEN.HOST The host name or IP address to listen on in standalone mode. If empty, listen on all possible addresses.

  * LISTEN.PORT The port to listen on in standalone mode. Defaults to 110.

  * MAILBOX_TEMPLATE The path to the mailboxes.  This is a template, containing one variable, %s, which will be replaced by the appropriate user name. Defaults to /var/mail/%s.

  * MAX_CHILDREN The maximum number of children to allow. That is, the maximum number of clients that can be served at the same time.  The zero value is interpreted as unlimited. Available only in standalone mode. Defaults to 20.

  * MINIMUM_LOG_LEVEL The minimum priority required to log a message. Defaults to 1.

  * MODULE_DIRS A list of directories where modules are stored.  Defaults to pkglibdir.

  * MODULE_LIST A list of modules to load. They can be specified either via full path, or relative to any directory listed in MODULE_DIRS By default, this is empty.

  * QUIT_ON_ERROR If this option is specified, POP3Lite will issue an implicit quit if the connection drops or any other error occurs. This violates the RFCs, but may come handy for users using flaky phone lines.  By default this is off.

  * RUN_GID The gid to set after authentication. By default, the daemon uses the gid of the logged in user.

  * SYSLOG.DISABLE When this is turned on, all logging to syslog will be disabled. Defaults to no.

Caveats & Pitfalls
------------------

The module system used in POP3Lite is very fragile. It is easy to make the daemon crash with only a typo, so be careful.

It must be noted that a module loaded later will take precedence over the one which does the same thing, but was loaded before. For example, if you have two authentication modules (call them AUTH1 and AUTH2), and both of them can fall back to the previous implementation, then loading AUTH1, then AUTH2 will mean that if AUTH2 fails, it will call AUTH1. If they are loaded in reverse order, then if AUTH1 fails, then it will call AUTH2.

However, this is not the worst thing that can happen. Loading a module twice (or loading a module that is already built-in) might push the daemon into an infinite loop, or cause other trouble.

Security
********

Although POP3Lite was written with security in mind, there are some issues that need to be discussed.  However, most of this is a limitation in the POP3 protocol itself.

Modules
=======

The module concept is generally a really good idea. The Linux kernel has modules, the Apache server has modules, and every modern program has modules or something like that.

However, it introduces some new potential holes. When configured and set up correctly, these holes are plugged, if not, they may open up your system to attackers.

As a general rule, read the documentation of all the modules you install!  Read it carefully! If you can understand C code, read the source too, for that is the best documentation.

Keep in mind, that because a module can override almost any function, it can break the daemon. It is pretty easy to write a back-door module, and it is even easier to open a security hole by not properly configuring a module.

In the main distribution, every module comes with extensive documentation, use it! Those documents will mention the various security issues related to the specific module.

Setting RUN_GID
===============

If you have a system, where more than one user belongs to the same group, and this group is their primary group, then it is highly recommended that you set RUN_GID to the group id of the mail group (or whatever group the MDA runs with).

If you do not do this, then if a mailbox does not exist, it will be created user and group writable, that means that any user in the same group can modify the mailbox. This is done in this way, because if we do not create the mailbox group writable, the MDA wouldn't be able to deliver the messages.

On systems where each user has its own group, it is not a security risk to leave RUN_GID untouched, however, it might be necessary to set it, so the MDA can access the mailbox created by POP3Lite.

In a virtual-hosting environment, setting RUN_GID is essential for correct operation (as far as I can tell, however, a clever system design may prove me wrong).

If the messages aren't stored in the usual mailbox format, then this warnings may not apply.

Bugs & Limitations
******************

Currently, POP3Lite has some internal limitations, concerning mail size and line length (and a few other things).

One message (and the whole mailbox) must be smaller than the size of an unsigned long, which is around 2GB on ix86 platforms. Each line and the number of lines must be smaller than this too.

However, I do not consider these serious limitations, because if a mailbox is bigger than 2GB, then it is probably some mail bomb, and the box should be deleted. Not to mention that any root-fearing user should keep his mailbox small, just as administrators should keep user quotas even smaller... ;>

Of course, huge mailboxes will take more time and memory to load, so a 2GB mailbox would eat twice as much memory for a short period. This would surely put a smaller server to its knees, so cut off system limits, make them small.

     [file fdl.texi not included]