`POP3Lite Administrator's Manual', version 1.25.2.1, 2001/05/02.

Copyright (C) 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 1.25.2.1; a
documentation of the POP3Lite Post Office Protocol 3 daemon for system
administrators.

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

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

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

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

3 Configuration
***************

The file `/etc/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.

3.0.1 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 `/lib/pop3lite'.

   * `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'.

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

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

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

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

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

GNU Free Documentation License
******************************

                        Version 1.1, March 2000

     Copyright (C) 2000  Free Software Foundation, Inc.
         59 Temple Place, Suite 330, Boston, MA  02111-1307  USA
     Everyone is permitted to copy and distribute verbatim copies
     of this license document, but changing it is not allowed.

Preamble
========

The purpose of this License is to make a manual, textbook, or other
written document "free" in the sense of freedom: to assure everyone the
effective freedom to copy and redistribute it, with or without
modifying it, either commercially or noncommercially.  Secondarily,
this License preserves for the author and publisher a way to get credit
for their work, while not being considered responsible for
modifications made by others.

This License is a kind of "copyleft", which means that derivative works
of the document must themselves be free in the same sense.  It
complements the GNU General Public License, which is a copyleft license
designed for free software.

We have designed this License in order to use it for manuals for free
software, because free software needs free documentation: a free
program should come with manuals providing the same freedoms that the
software does.  But this License is not limited to software manuals; it
can be used for any textual work, regardless of subject matter or
whether it is published as a printed book.  We recommend this License
principally for works whose purpose is instruction or reference.

APPLICABILITY AND DEFINITIONS
=============================

This License applies to any manual or other work that contains a notice
placed by the copyright holder saying it can be distributed under the
terms of this License.  The "Document", below, refers to any such
manual or work.  Any member of the public is a licensee, and is
addressed as "you".

A "Modified Version" of the Document means any work containing the
Document or a portion of it, either copied verbatim, or with
modifications and/or translated into another language.

A "Secondary Section" is a named appendix or a front-matter section of
the Document that deals exclusively with the relationship of the
publishers or authors of the Document to the Document's overall subject
(or to related matters) and contains nothing that could fall directly
within that overall subject.  (For example, if the Document is in part a
textbook of mathematics, a Secondary Section may not explain any
mathematics.)  The relationship could be a matter of historical
connection with the subject or with related matters, or of legal,
commercial, philosophical, ethical or political position regarding them.

The "Invariant Sections" are certain Secondary Sections whose titles
are designated, as being those of Invariant Sections, in the notice
that says that the Document is released under this License.

The "Cover Texts" are certain short passages of text that are listed,
as Front-Cover Texts or Back-Cover Texts, in the notice that says that
the Document is released under this License.

A "Transparent" copy of the Document means a machine-readable copy,
represented in a format whose specification is available to the general
public, whose contents can be viewed and edited directly and
straightforwardly with generic text editors or (for images composed of
pixels) generic paint programs or (for drawings) some widely available
drawing editor, and that is suitable for input to text formatters or
for automatic translation to a variety of formats suitable for input to
text formatters.  A copy made in an otherwise Transparent file format
whose markup has been designed to thwart or discourage subsequent
modification by readers is not Transparent.  A copy that is not
"Transparent" is called "Opaque".

Examples of suitable formats for Transparent copies include plain ASCII
without markup, Texinfo input format, LaTeX input format, SGML or XML
using a publicly available DTD, and standard-conforming simple HTML
designed for human modification.  Opaque formats include PostScript,
PDF, proprietary formats that can be read and edited only by
proprietary word processors, SGML or XML for which the DTD and/or
processing tools are not generally available, and the machine-generated
HTML produced by some word processors for output purposes only.

The "Title Page" means, for a printed book, the title page itself, plus
such following pages as are needed to hold, legibly, the material this
License requires to appear in the title page.  For works in formats
which do not have any title page as such, "Title Page" means the text
near the most prominent appearance of the work's title, preceding the
beginning of the body of the text.

VERBATIM COPYING
================

You may copy and distribute the Document in any medium, either
commercially or noncommercially, provided that this License, the
copyright notices, and the license notice saying this License applies
to the Document are reproduced in all copies, and that you add no other
conditions whatsoever to those of this License.  You may not use
technical measures to obstruct or control the reading or further
copying of the copies you make or distribute.  However, you may accept
compensation in exchange for copies.  If you distribute a large enough
number of copies you must also follow the conditions in section 3.

You may also lend copies, under the same conditions stated above, and
you may publicly display copies.

COPYING IN QUANTITY
===================

If you publish printed copies of the Document numbering more than 100,
and the Document's license notice requires Cover Texts, you must enclose
the copies in covers that carry, clearly and legibly, all these Cover
Texts: Front-Cover Texts on the front cover, and Back-Cover Texts on
the back cover.  Both covers must also clearly and legibly identify you
as the publisher of these copies.  The front cover must present the
full title with all words of the title equally prominent and visible.
You may add other material on the covers in addition.  Copying with
changes limited to the covers, as long as they preserve the title of
the Document and satisfy these conditions, can be treated as verbatim
copying in other respects.

If the required texts for either cover are too voluminous to fit
legibly, you should put the first ones listed (as many as fit
reasonably) on the actual cover, and continue the rest onto adjacent
pages.

If you publish or distribute Opaque copies of the Document numbering
more than 100, you must either include a machine-readable Transparent
copy along with each Opaque copy, or state in or with each Opaque copy
a publicly-accessible computer-network location containing a complete
Transparent copy of the Document, free of added material, which the
general network-using public has access to download anonymously at no
charge using public-standard network protocols.  If you use the latter
option, you must take reasonably prudent steps, when you begin
distribution of Opaque copies in quantity, to ensure that this
Transparent copy will remain thus accessible at the stated location
until at least one year after the last time you distribute an Opaque
copy (directly or through your agents or retailers) of that edition to
the public.

It is requested, but not required, that you contact the authors of the
Document well before redistributing any large number of copies, to give
them a chance to provide you with an updated version of the Document.

MODIFICATIONS
=============

You may copy and distribute a Modified Version of the Document under
the conditions of sections 2 and 3 above, provided that you release the
Modified Version under precisely this License, with the Modified
Version filling the role of the Document, thus licensing distribution
and modification of the Modified Version to whoever possesses a copy of
it.  In addition, you must do these things in the Modified Version:

  A. Use in the Title Page (and on the covers, if any) a title distinct
     from that of the Document, and from those of previous versions
     (which should, if there were any, be listed in the History section
     of the Document).  You may use the same title as a previous version
     if the original publisher of that version gives permission.

  B.  List on the Title Page, as authors, one or more persons or
     entities responsible for authorship of the modifications in the
     Modified Version, together with at least five of the principal
     authors of the Document (all of its principal authors, if it has
     less than five).

  C. State on the Title page the name of the publisher of the Modified
     Version, as the publisher.

  D.  Preserve all the copyright notices of the Document.

  E. Add an appropriate copyright notice for your modifications
     adjacent to the other copyright notices.

  F. Include, immediately after the copyright notices, a license notice
     giving the public permission to use the Modified Version under the
     terms of this License, in the form shown in the Addendum below.

  G. Preserve in that license notice the full lists of Invariant
     Sections and required Cover Texts given in the Document's license
     notice.

  H. Include an unaltered copy of this License.

  I. Preserve the section entitled "History", and its title, and add to
     it an item stating at least the title, year, new authors, and
     publisher of the Modified Version as given on the Title Page.  If
     there is no section entitled "History" in the Document, create one
     stating the title, year, authors, and publisher of the Document as
     given on its Title Page, then add an item describing the Modified
     Version as stated in the previous sentence.

  J. Preserve the network location, if any, given in the Document for
     public access to a Transparent copy of the Document, and likewise
     the network locations given in the Document for previous versions
     it was based on.  These may be placed in the "History" section.
     You may omit a network location for a work that was published at
     least four years before the Document itself, or if the original
     publisher of the version it refers to gives permission.

  K. In any section entitled "Acknowledgements" or "Dedications",
     preserve the section's title, and preserve in the section all the
     substance and tone of each of the contributor acknowledgements
     and/or dedications given therein.

  L. Preserve all the Invariant Sections of the Document, unaltered in
     their text and in their titles.  Section numbers or the equivalent
     are not considered part of the section titles.

  M. Delete any section entitled "Endorsements".  Such a section may
     not be included in the Modified Version.

  N. Do not retitle any existing section as "Endorsements" or to
     conflict in title with any Invariant Section.

If the Modified Version includes new front-matter sections or
appendices that qualify as Secondary Sections and contain no material
copied from the Document, you may at your option designate some or all
of these sections as invariant.  To do this, add their titles to the
list of Invariant Sections in the Modified Version's license notice.
These titles must be distinct from any other section titles.

You may add a section entitled "Endorsements", provided it contains
nothing but endorsements of your Modified Version by various
parties-for example, statements of peer review or that the text has
been approved by an organization as the authoritative definition of a
standard.

You may add a passage of up to five words as a Front-Cover Text, and a
passage of up to 25 words as a Back-Cover Text, to the end of the list
of Cover Texts in the Modified Version.  Only one passage of
Front-Cover Text and one of Back-Cover Text may be added by (or through
arrangements made by) any one entity.  If the Document already includes
a cover text for the same cover, previously added by you or by
arrangement made by the same entity you are acting on behalf of, you
may not add another; but you may replace the old one, on explicit
permission from the previous publisher that added the old one.

The author(s) and publisher(s) of the Document do not by this License
give permission to use their names for publicity for or to assert or
imply endorsement of any Modified Version.

COMBINING DOCUMENTS
===================

You may combine the Document with other documents released under this
License, under the terms defined in section 4 above for modified
versions, provided that you include in the combination all of the
Invariant Sections of all of the original documents, unmodified, and
list them all as Invariant Sections of your combined work in its
license notice.

The combined work need only contain one copy of this License, and
multiple identical Invariant Sections may be replaced with a single
copy.  If there are multiple Invariant Sections with the same name but
different contents, make the title of each such section unique by
adding at the end of it, in parentheses, the name of the original
author or publisher of that section if known, or else a unique number.
Make the same adjustment to the section titles in the list of Invariant
Sections in the license notice of the combined work.

In the combination, you must combine any sections entitled "History" in
the various original documents, forming one section entitled "History";
likewise combine any sections entitled "Acknowledgements", and any
sections entitled "Dedications".  You must delete all sections entitled
"Endorsements."

COLLECTIONS OF DOCUMENTS
========================

You may make a collection consisting of the Document and other documents
released under this License, and replace the individual copies of this
License in the various documents with a single copy that is included in
the collection, provided that you follow the rules of this License for
verbatim copying of each of the documents in all other respects.

You may extract a single document from such a collection, and distribute
it individually under this License, provided you insert a copy of this
License into the extracted document, and follow this License in all
other respects regarding verbatim copying of that document.

AGGREGATION WITH INDEPENDENT WORKS
==================================

A compilation of the Document or its derivatives with other separate
and independent documents or works, in or on a volume of a storage or
distribution medium, does not as a whole count as a Modified Version of
the Document, provided no compilation copyright is claimed for the
compilation.  Such a compilation is called an "aggregate", and this
License does not apply to the other self-contained works thus compiled
with the Document, on account of their being thus compiled, if they are
not themselves derivative works of the Document.

If the Cover Text requirement of section 3 is applicable to these
copies of the Document, then if the Document is less than one quarter
of the entire aggregate, the Document's Cover Texts may be placed on
covers that surround only the Document within the aggregate.  Otherwise
they must appear on covers around the whole aggregate.

TRANSLATION
===========

Translation is considered a kind of modification, so you may distribute
translations of the Document under the terms of section 4.  Replacing
Invariant Sections with translations requires special permission from
their copyright holders, but you may include translations of some or
all Invariant Sections in addition to the original versions of these
Invariant Sections.  You may include a translation of this License
provided that you also include the original English version of this
License.  In case of a disagreement between the translation and the
original English version of this License, the original English version
will prevail.

TERMINATION
===========

You may not copy, modify, sublicense, or distribute the Document except
as expressly provided for under this License.  Any other attempt to
copy, modify, sublicense or distribute the Document is void, and will
automatically terminate your rights under this License.  However,
parties who have received copies, or rights, from you under this
License will not have their licenses terminated so long as such parties
remain in full compliance.

FUTURE REVISIONS OF THIS LICENSE
================================

The Free Software Foundation may publish new, revised versions of the
GNU Free Documentation License from time to time.  Such new versions
will be similar in spirit to the present version, but may differ in
detail to address new problems or concerns.  See
http://www.gnu.org/copyleft/.

Each version of the License is given a distinguishing version number.
If the Document specifies that a particular numbered version of this
License "or any later version" applies to it, you have the option of
following the terms and conditions either of that specified version or
of any later version that has been published (not as a draft) by the
Free Software Foundation.  If the Document does not specify a version
number of this License, you may choose any version ever published (not
as a draft) by the Free Software Foundation.

ADDENDUM: How to use this License for your documents
====================================================

To use this License in a document you have written, include a copy of
the License in the document and put the following copyright and license
notices just after the title page:

     Copyright (c)  YEAR  YOUR NAME.
     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 Invariant Sections being LIST THEIR TITLES, with the
     Front-Cover Texts being LIST, and with the Back-Cover Texts being LIST.
     A copy of the license is included in the section entitled "GNU
     Free Documentation License".

If you have no Invariant Sections, write "with no Invariant Sections"
instead of saying which ones are invariant.  If you have no Front-Cover
Texts, write "no Front-Cover Texts" instead of "Front-Cover Texts being
LIST"; likewise for Back-Cover Texts.

If your document contains nontrivial examples of program code, we
recommend releasing these examples in parallel under your choice of
free software license, such as the GNU General Public License, to
permit their use in free software.