Install all the files that comprise the new DocBook way of making the
authorPhilip Hazel <ph10@hermes.cam.ac.uk>
Thu, 16 Jun 2005 10:32:31 +0000 (10:32 +0000)
committerPhilip Hazel <ph10@hermes.cam.ac.uk>
Thu, 16 Jun 2005 10:32:31 +0000 (10:32 +0000)
documentation.

25 files changed:
doc/ABOUT [new file with mode: 0644]
doc/doc-docbook/ABOUT [new file with mode: 0644]
doc/doc-docbook/AdMarkup.txt [new file with mode: 0644]
doc/doc-docbook/HowItWorks.txt [new file with mode: 0644]
doc/doc-docbook/Makefile [new file with mode: 0644]
doc/doc-docbook/MyAsciidoc.conf [new file with mode: 0644]
doc/doc-docbook/MyStyle-chunk-html.xsl [new file with mode: 0644]
doc/doc-docbook/MyStyle-filter-fo.xsl [new file with mode: 0644]
doc/doc-docbook/MyStyle-fo.xsl [new file with mode: 0644]
doc/doc-docbook/MyStyle-html.xsl [new file with mode: 0644]
doc/doc-docbook/MyStyle-nochunk-html.xsl [new file with mode: 0644]
doc/doc-docbook/MyStyle-spec-fo.xsl [new file with mode: 0644]
doc/doc-docbook/MyStyle-txt-html.xsl [new file with mode: 0644]
doc/doc-docbook/MyStyle.xsl [new file with mode: 0644]
doc/doc-docbook/MyTitlepage.templates.xml [new file with mode: 0644]
doc/doc-docbook/Myhtml.css [new file with mode: 0644]
doc/doc-docbook/Pre-xml [new file with mode: 0755]
doc/doc-docbook/TidyHTML-filter [new file with mode: 0755]
doc/doc-docbook/TidyHTML-spec [new file with mode: 0755]
doc/doc-docbook/Tidytxt [new file with mode: 0755]
doc/doc-docbook/filter.ascd [new file with mode: 0644]
doc/doc-docbook/spec.ascd [new file with mode: 0644]
doc/doc-docbook/x2man [new file with mode: 0755]
doc/doc-scripts/ABOUT
doc/doc-src/ABOUT

diff --git a/doc/ABOUT b/doc/ABOUT
new file mode 100644 (file)
index 0000000..4bbaeaf
--- /dev/null
+++ b/doc/ABOUT
@@ -0,0 +1,33 @@
+$Cambridge: exim/doc/ABOUT,v 1.1 2005/06/16 10:32:31 ph10 Exp $
+
+CVS directory exim/exim-doc
+---------------------------
+
+This directory contains all the files related to Exim documentation. They are
+held in a number of subdirectories.
+
+doc-docbook      This directory contains the AsciiDoc and DocBook sources for
+                 the Exim specification and the filter description. It also
+                 contains a Makefile and all the scripts, stylesheets, etc.
+                 that are used to create the distributed renditions of the
+                 documents. This way of creating the documentation was
+                 introduced for release 4.60.
+
+doc-misc         This directory contains a number of miscellaneous documents
+                 that are relevant to Exim, but not part of its distribution
+                 tarball.
+
+doc-scripts      This directory contains scripts for building exported
+                 documentation from the original SGCAL input source. These were
+                 used up to and including release 4.50.
+
+doc-src          This directory contains the SGCAL source documents that were
+                 used up to and including release 4.50.
+
+doc-txt          This directory contains documentation that is maintained only
+                 as text files.
+
+Each of these directories contains an ABOUT file that describes its contents in
+more detail.
+
+End
diff --git a/doc/doc-docbook/ABOUT b/doc/doc-docbook/ABOUT
new file mode 100644 (file)
index 0000000..72048b5
--- /dev/null
@@ -0,0 +1,16 @@
+$Cambridge: exim/doc/doc-docbook/ABOUT,v 1.1 2005/06/16 10:32:31 ph10 Exp $
+
+CVS directory exim/exim-doc/doc-docbook
+---------------------------------------
+
+This directory contains the AsciiDoc and DocBook sources for the Exim
+specification and the filter description. It also contains a Makefile and all
+the scripts, stylesheets, etc. that are used to create the distributed
+renditions of the documents. This way of creating the documentation was
+introduced for release 4.60.
+
+The file HowItWorks.txt explains the processes by which the distributed
+renditions are created. It also contains a list of the files in this directory
+and what they all contain.
+
+End
diff --git a/doc/doc-docbook/AdMarkup.txt b/doc/doc-docbook/AdMarkup.txt
new file mode 100644 (file)
index 0000000..40942a6
--- /dev/null
@@ -0,0 +1,434 @@
+$Cambridge: exim/doc/doc-docbook/AdMarkup.txt,v 1.1 2005/06/16 10:32:31 ph10 Exp $
+
+Asciidoc markup used in the Exim documentation
+----------------------------------------------
+
+This file contains a summary of the AsciiDoc markup that is used in the source
+files of the Exim documentation. The source files are in plain text that can be
+edited by any text editor. They are converted by the AsciiDoc application into
+DocBook XML for subsequent processing into the various output formats.
+
+This markup requires AsciiDoc release 6.0.3 or later.
+
+The advantage of using AsciiDoc format as a "back end" is that is uses
+relatively simple markup in the majority of the text, making it easier to read
+and edit. The disadvantage is that it is tricky to deal with complicated
+formatting - though that is probably true of any markup language - and there
+are a few gotchas.
+
+The Exim documentation uses the default AsciiDoc markup with some additions. I
+have created a special AsciiDoc configuration file for use with the Exim
+documentation. You must use this configuration if you want to get sensible
+results,
+
+
+SPECIAL CHARACTERS
+
+When typing paragraphs of text, the following character sequences are
+recognized as markup if they occur surrounding a "word phrase" within a
+paragraph. In the list below, ... represents the text that is enclosed.
+
+  '...'    single quotes        italic:
+                                  used for email addresses, domains, local
+                                  parts, header names, user names
+
+  *...*    asterisks            bold
+                                  used for things like "*Note:*"
+
+  `...`    backticks            monospaced text
+                                  used for literal quoting
+
+  $...$    dollar               Exim variable
+                                  maps to XML <varname> with leading $
+
+  %...%    percent              Exim option, command line option
+                                  maps to XML <option>
+
+  ^...^    circumflex           Exim driver name, Unix command, filter command
+                                 maps to XML <command>
+
+  ^^...^^  double circumflex    C function: maps to XML <function>
+
+  ^%...%^  circumflex percent   parameter: maps to XML <parameter>
+                                  Not currently used
+
+  _..._    underscore           file name: maps to XML <filename>
+
+  ``...''  backticks & quotes   put word in quotation marks
+
+For example,
+
+  This is an 'italic phrase'. This is a _filename_ and a $variable$.
+  This ``word'' is in quote marks.
+
+These quoting characters are recognized only if they are not flanked by
+alphanumeric characters. Thus, for instance, an apostrophe within a word can be
+represented as a single quote without any problem. Quoting can be nested, but
+not overlapped. However, the resulting XML from nested quotes is not always
+valid, so nesting is best avoided. (For example, `xxx'yyy'xxx` generates an
+<emphasis> item within a <literal> item, and the DocBook DTD doesn't allow
+that.) However, one combination that does work is <literal> within an
+<emphasis>, so that is what you have to use if you want a boldface monospaced
+font. That is, use *`bold mono`* and not `*bold mono*`. Sigh.
+
+There are also some character sequences that are translated into non-Ascii
+characters:
+
+  --     en-dash    (&#x2013;)
+  ---    em-dash    (&#x8212;)
+  ~      hard space (&#x00a0;)
+  !!     dagger     (&#x2020;}
+
+The two-character sequence ## is turned into nothing. It is useful for
+disambiguating markup. For example, something like
+
+  ``quoted ending in 'emphasized'''
+
+is ambiguous, and as AsciiDoc looks for the longest markup first, it doesn't do
+what you want. You have to code this as
+
+  ``quoted ending in 'emphasized'##''
+
+The dashes are recognized only when surrounded by white space. The special Exim
+AsciiDoc configuration also translates most apostrophes to a typographic
+apostrophe (&#x2019;). There are some cases where this doesn't work, for
+example, an apostrophe after a word in another font (because the quote
+character gets in the way). For this purpose, there is a named "attribute" that
+can be used. Named attributes are substituted inside curly braces.
+
+For example, in the filter document there is a reference to an imaginary user
+called lg303. User names are italicized, so this is always typed as 'lg303' but
+if an apostrophe-s is needed after it, you have to type
+
+  'lg303'{ap}s
+
+Another named attribute is {tl}, which turns into a tilde character, because a
+literal tilde becomes a hard space.
+
+A third named attribute is {hh}, which turns into two hyphens, because a
+literal "--" is converted into an en dash.
+
+A fourth named attributs is {pc}, which turns into a percent sign.
+
+
+ESCAPING SPECIAL CHARACTERS
+
+Use backslash if you need to escape a special character.
+
+***** GOTCHA *****
+Backslash is not special when it precedes any other character. Thus, you need
+to know which characters are special, which is a pain.
+
+
+COMMENTS
+
+You can include comments that will not be copied to the XML document by
+creating a comment block that is delimited by at least three slashes. For
+example:
+
+  ///
+  This is an AsciiDoc comment block.
+  ///
+
+
+URL REFERENCES
+
+To refer to a URL, just put it in the text, followed by some text in square
+brackets to define the displayed text. If that is empty, the URL itself is
+displayed. For example, here's a reference to http://www.exim.org/[exim home
+page]. In HTML output, all you see is the display text; in printed output you
+see something like "exim home page [http://www.exim.org/]". The URL is printed
+in whatever is the current font, so it can be made bold by putting it in
+asterisks (for example).
+
+
+FORMAL PARAGRAPHS
+
+A formal paragraph has a title. This is normally typeset in bold at the start
+of the paragraph, and is useful as an alternative to a vertical labelled list
+(see below). To create such a paragraph, you just put its title first, like
+this:
+
+  [title="the title"]
+  Now give the text of the paragraph as usual.
+
+
+CHAPTERS AND SECTIONS
+
+AsciiDoc recognizes chapter and sections by looking for underlined lines, with
+the underlining character used to determine the type of section.
+
+  This is a chapter title
+  -----------------------
+
+  This is a section title
+  ~~~~~~~~~~~~~~~~~~~~~~~
+
+Chapter titles are used for running feet in the PDF form of the manual.
+Sometimes they are too long, causing them to be split in an ugly way. The
+solution to this is to define a short title for the chapter, like this:
+
+  [titleabbrev="short title"]
+  This is a rather long chapter title
+  -----------------------------------
+
+
+DISPLAYS
+
+Displayed blocks in a monospaced font can just be indented:
+
+  # Exim filter
+  deliver baggins@rivendell.middle-earth.example
+
+However, it seems that if the first line in such a block starts with an
+asterisk or if any lines in the block end in a backslash (as is quite often the
+case in Exim configuration examples), you have to use a "listing block" or a
+"literal block" instead of a "literal paragraph". Otherwise an initial asterisk
+makes AsciiDoc think this is a list item, and a terminating backslash causes
+lines to be concatenated.
+
+Another time when you have to use an explicit block is when a display forms
+part of a list item. This is because you have to indent such displays more than
+usual, because the processors don't appear to do this automatically.
+
+Listing blocks are delimited by lines of at least three hyphens; literal blocks
+are delimited by lines of at least four dots. For example:
+
+....
+/usr/sbin/sendmail -bf myfilter \
+   -f islington@never.where <test-message
+....
+
+Such blocks are indented by an amount that is specified in the style sheet, but
+this amount is always the same, regardless of whether the block is inside a
+list item (which is itself indented) or not. So if the block is within a list
+item, it must be explicitly indented as well.
+
+Blocks that are between lines of ampersands (at least 3 in each line) are
+displayed (by default) in the normal font, but with the lines unchanged. Quotes
+can be used in the block to specify different fonts. For example:
+
+&&&&
+`\n`   is replaced by a newline
+`\r`   is replaced by a carriage return
+`\t`   is replaced by a tab
+&&&&
+
+When this kind of output is required within a list of any kind (see below), you
+must precede it with a line consisting of just a plus sign, because by default
+any kind of block terminates the list item.
+
+
+CROSS-REFERENCES
+
+To set a cross-reference point, enclose the name in double square brackets:
+
+  [[SECTexample]]
+
+To refer to a cross-reference point, enclose the name in double angle brackets:
+
+  <<SECTexample>>
+
+
+INDEX ENTRIES
+
+To create an index entry, include a line like one of these:
+
+  cindex:[primary text,secondary text]
+  oindex:[primary text,secondary text]
+
+at the appropriate point in the text. The first is for the "concept index" and
+the second is for the "options index". Not all forms of output distinguish
+between these - sometimes there is just one index.
+
+The index for the Exim reference manual has a number of "see also" entries.
+Rather than invent some fancy AsciiDoc way of doing this, I have just coded
+them in XML, using the AsciiDoc escape hatch that is described below under
+FUDGES.
+
+
+LISTS
+
+For a bulleted list, start each item in the list with a hyphen or an asterisk
+followed by a space:
+
+  - First item.
+  - Second item.
+
+For a numbered list, start each item with a dot followed by a space:
+
+  . First item.
+  . Second item.
+
+
+VERTICAL LABELLED LISTS
+
+These are used for Exim command line options and similar things. They map into
+XML <variablelist> items. Start the list with the item name, followed by two
+colons, on a line by itself. This is followed by the text for the list item.
+
+
+LISTS CONTAINING MORE THAN ONE PARAGRAPH
+
+If there is more than one paragraph in a list item, the second and subsequent
+ones must be preceded by a line containing just a single "+" character, as
+otherwise the list is terminated. Literal paragraphs can be included without
+any special markup. For example:
+
+  first item::
+  This is the pararaph that describes the item.
+
+    We can even have an indented display
+    within the item
+  +
+  but any more paragraphs must be preceded by a plus character
+  (otherwise they aren't included in the list, and won't be
+  properly indented).
+
+The "+" notation can also be used to include other kinds of block within a list
+item. It's needed for all block types except nested lists and literal
+paragraphs.
+
+An alternative approach to lists that contain multiple paragraphs or blocks
+within each item is to put a line containing just two hyphens immediately
+before and immediately after the list. For example:
+
+  --
+  . First item
+
+  Second paragraph of first item
+
+  . Second item
+
+  And so on
+  --
+
+This is particularly helpful for nested lists (see below).
+
+
+NESTED LISTS
+
+You can nest lists of different types. However, if you want to revert to an
+outer list item at the end of a nested list, you must use the "--" feature
+described above for the inner list, so that its end can be explicitly marked.
+For example:
+
+  . Outer list
+  +
+  Second paragraph in outer list
+  +
+  --
+  - Inner list item
+  - Inner list second item
+  --
+  +
+  Another paragraph in the outer list first item
+
+  . Next item in the outer list
+
+
+TABLES
+
+A fixed-width table is started by a line of hyphens that determines the width
+of the table, interspersed with the following column stop characters:
+
+  ` backtick   align left
+  ' quote      align right
+  . dot        align centre
+
+The data is then aligned with the stop characters. For example:
+
+  `---`---
+  1   2
+  3   4
+  --------
+
+Alternatively, if tildes are used instead of hyphens, the data fields are
+comma-separated. Columns can also be specified numerically instead of by
+pattern. This is usually used with CSV data. For example:
+
+  `10`20`30~
+  one, two, three
+  ~~~~~
+
+This format is useful when the data is full of markup so that its final length
+bears little relationship to the input (for example, when there are cross
+references).
+
+By default, tables will be rendered with a frame at the top and bottom, and no
+separators between rows and columns. You can use AsciiDoc "attributes" to
+change this. Attributes are set by a sequence of name=value items in square
+brackets, before the thing to which they apply. For example:
+
+  [frame="none"]
+  `-----`-----
+  11    22
+  33    44
+  ------------
+
+The values for "frame" are "topbot", "sides", "all", or "none". There is also a
+"grid" attribute, whose possible values are "none", "cols", "rows", or "all".
+For example:
+
+  [frame="sides", grid="cols"]
+
+The commas between the attribute settings are important; if they are omitted,
+AsciiDoc ignores the attribute settings.
+
+
+EXIM CONFIGURATION OPTION HEADINGS
+
+Each Exim configuration option is formatted with its name, usage, type, and
+default value on a single line, spread over the line so as to fill it
+completely. The only way I know of aligning text using DocBook is to use a
+table. A special table format has been created to handle this special case. For
+example:
+
+  `..'=
+  %keep_malformed%, Use: 'main', Type: 'boolean', Default: 'false'
+  ===
+
+The first line defines four colums using stop characters, followed by an equals
+character that defines the table's "ruler" character. There is no need to
+define column widths, because the style forces the columns to fill the page
+width. The data is comma-separated.
+
+
+CHANGE BARS
+
+I haven't yet found a way of doing changebars in the printed versions. However,
+it is possible to put a green background behind changed text in the HTML
+version, so the appropriate markup should be used. Before a changed paragraph,
+insert
+
+  [revisionflag="changed"]
+
+This should precede any index settings at the start of the paragraph. If you
+want to do this for a display, you must use the "&&&" block described above,
+because that's the only type that I have set up to support it.
+
+
+FUDGES
+
+The current release of "fop", a program for producing PostScript from
+"formatting objects" (fo) data, which is an intermediate output that can be
+generated from DocBook XML, is not very good at page layout. For example, it
+can place a section heading as the last line on a page. I have set up a style
+that provides a means of forcing a page break in order to get round this. (But
+in practice, it happens so often that I have given up trying to use it.)
+
+At the AsciiDoc level, the markup uses a "backend block", which provides a way
+of specifying DocBook output directly. Backend blocks are surrounded by lines
+of plusses, and this particular fudge looks like this:
+
+  ++++++++++++
+  <?hard-pagebreak?>
+  ++++++++++++
+
+Backend blocks are used to insert XML comments into the output, to mark the
+start and end of Exim's command line options. These are used by the x2man
+script that creates the man page.
+
+
+Philip Hazel
+Last updated: 10 June 2005
diff --git a/doc/doc-docbook/HowItWorks.txt b/doc/doc-docbook/HowItWorks.txt
new file mode 100644 (file)
index 0000000..9be1466
--- /dev/null
@@ -0,0 +1,541 @@
+$Cambridge: exim/doc/doc-docbook/HowItWorks.txt,v 1.1 2005/06/16 10:32:31 ph10 Exp $
+
+CREATING THE EXIM DOCUMENTATION
+
+"You are lost in a maze of twisty little scripts."
+
+
+This document describes how the various versions of the Exim documentation, in
+different output formats, are created from DocBook XML, and also how the
+DocBook XML is itself created.
+
+
+BACKGROUND: THE OLD WAY
+
+From the start of Exim, in 1995, the specification was written in a local text
+formatting system known as SGCAL. This is capable of producing PostScript and
+plain text output from the same source file. Later, when the "ps2pdf" command
+became available with GhostScript, that was used to create a PDF version from
+the PostScript. (A few earlier versions were created by a helpful user who had
+bought the Adobe distiller software.)
+
+A demand for a version in "info" format led me to write a Perl script that
+converted the SGCAL input into a Texinfo file. Because of the somewhat
+restrictive requirements of Texinfo, this script has always needed a lot of
+maintenance, and has never been 100% satisfactory.
+
+The HTML version of the documentation was originally produced from the Texinfo
+version, but later I wrote another Perl script that produced it directly from
+the SGCAL input, which made it possible to produce better HTML.
+
+There were a small number of diagrams in the documentation. For the PostScript
+and PDF versions, these were created using Aspic, a local text-driven drawing
+program that interfaces directly to SGCAL. For the text and texinfo versions,
+alternative ascii-art diagrams were used. For the HTML version, screen shots of
+the PostScript output were turned into gifs.
+
+
+A MORE STANDARD APPROACH
+
+Although in principle SGCAL and Aspic could be generally released, they would
+be unlikely to receive much (if any) maintenance, especially after I retire.
+Furthermore, the old production method was only semi-automatic; I still did a
+certain amount of hand tweaking of spec.txt, for example. As the maintenance of
+Exim itself was being opened up to a larger group of people, it seemed sensible
+to move to a more standard way of producing the documentation, preferable fully
+automated. However, we wanted to use only non-commercial software to do this.
+
+At the time I was thinking about converting (early 2005), the "obvious"
+standard format in which to keep the documentation was DocBook XML. The use of
+XML in general, in many different applications, was increasing rapidly, and it
+seemed likely to remain a standard for some time to come. DocBook offered a
+particular form of XML suited to documents that were effectively "books".
+
+Maintaining an XML document by hand editing is a tedious, verbose, and
+error-prone process. A number of specialized XML text editors were available,
+but all the free ones were at a very primitive stage. I therefore decided to
+keep the master source in AsciiDoc format (described below), from which a
+secondary XML master could be automatically generated.
+
+All the output formats are generated from the XML file. If, in the future, a
+better way of maintaining the XML source becomes available, this can be adopted
+without changing any of the processing that produces the output documents.
+Equally, if better ways of processing the XML become available, they can be
+adopted without affecting the source maintenance.
+
+A number of issues arose while setting this all up, which are best summed up by
+the statement that a lot of the technology is (in 2005) still very immature. It
+is probable that trying to do this conversion any earlier would not have been
+anywhere near as successful. The main problems that still bother me are
+described in the penultimate section of this document.
+
+The following sections describe the processes by which the AsciiDoc files are
+transformed into the final output documents. In practice, the details are coded
+into a makefile that specifies the chain of commands for each output format.
+
+
+REQUIRED SOFTWARE
+
+Installing software to process XML puts lots and lots of stuff on your box. I
+run Gentoo Linux, and a lot of things have been installed as dependencies that
+I am not fully aware of. This is what I know about (version numbers are current
+at the time of writing):
+
+. AsciiDoc 6.0.3
+
+  This converts the master source file into a DocBook XML file, using a
+  customized AsciiDoc configuration file.
+
+. xmlto 0.0.18
+
+  This is a shell script that drives various XML processors. It is used to
+  produce "formatted objects" for PostScript and PDF output, and to produce
+  HTML output. It uses xsltproc, libxml, libxslt, libexslt, and possibly other
+  things that I have not figured out, to apply the DocBook XSLT stylesheets.
+
+. libxml 1.8.17
+  libxml2 2.6.17
+  libxslt 1.1.12
+
+  These are all installed on my box; I do not know which of libxml or libxml2
+  the various scripts are actually using.
+
+. xsl-stylesheets-1.66.1
+
+  These are the standard DocBook XSL stylesheets.
+
+. fop 0.20.5
+
+  FOP is a processor for "formatted objects". It is written in Java. The fop
+  command is a shell script that drives it.
+
+. w3m 0.5.1
+
+  This is a text-oriented web brower. It is used to produce the Ascii form of
+  the Exim documentation from a specially-created HTML format. It seems to do a
+  better job than lynx.
+
+. docbook2texi (part of docbook2X 0.8.5)
+
+  This is a wrapper script for a two-stage conversion process from DocBook to a
+  Texinfo file. It uses db2x_xsltproc and db2x_texixml. Unfortunately, there
+  are two versions of this command; the old one is based on an earlier fork of
+  docbook2X and does not work.
+
+. db2x_xsltproc and db2x_texixml (part of docbook2X 0.8.5)
+
+  More wrapping scripts (see previous item).
+
+. makeinfo 4.8
+
+  This is used to make a set of "info" files from a Texinfo file.
+
+In addition, there are some locally written Perl scripts. These are described
+below.
+
+
+ASCIIDOC
+
+AsciiDoc (http://www.methods.co.nz/asciidoc/) is a Python script that converts
+an input document in a more-or-less human-readable format into DocBook XML.
+For a document as complex as the Exim specification, the markup is quite
+complex - probably no simpler than the original SGCAL markup - but it is
+definitely easier to work with than XML itself.
+
+AsciiDoc is highly configurable. It comes with a default configuration, but I
+have extended this with an additional configuration file that must be used when
+processing the Exim documents. There is a separate document called AdMarkup.txt
+that describes the markup that is used in these documents. This includes the
+default AsciiDoc markup and the local additions.
+
+The author of AsciiDoc uses the extension .txt for input documents. I find
+this confusing, especially as some of the output files have .txt extensions.
+Therefore, I have used the extension .ascd for the sources.
+
+
+THE MAKEFILE
+
+The makefile supports a number of targets of the form x.y, where x is one of
+"filter", "spec", or "test", and y is one of "xml", "fo", "ps", "pdf", "html",
+"txt", or "info". The intermediate targets "x.xml" and "x.fo" are provided for
+testing purposes. The other five targets are production targets. For example:
+
+  make spec.pdf
+
+This runs the necessary tools in order to create the file spec.pdf from the
+original source spec.ascd. A number of intermediate files are created during
+this process, including the master DocBook source, called spec.xml. Of course,
+the usual features of "make" ensure that if this already exists and is
+up-to-date, it is not needlessly rebuilt.
+
+The "test" series of targets were created so that small tests could easily be
+run fairly quickly, because processing even the shortish filter document takes
+a bit of time, and processing the main specification takes ages.
+
+Another target is "exim.8". This runs a locally written Perl script called
+x2man, which extracts the list of command line options from the spec.xml file,
+and creates a man page. There are some XML comments in the spec.xml file to
+enable the script to find the start and end of the options list.
+
+There is also a "clean" target that deletes all the generated files.
+
+
+CREATING DOCBOOK XML FROM ASCIIDOC
+
+There is a single local AsciiDoc configuration file called MyAsciidoc.conf.
+Using this, one run of the asciidoc command creates a .xml file from a .ascd
+file. When this succeeds, there is no output.
+
+
+DOCBOOK PROCESSING
+
+Processing a .xml file into the five different output formats is not entirely
+straightforward. For a start, the same XML is not suitable for all the
+different output styles. When the final output is in a text format (.txt,
+.texinfo) for instance, all non-Ascii characters in the input must be converted
+to Ascii transliterations because the current processing tools do not do this
+correctly automatically.
+
+In order to cope with these issues in a flexible way, a Perl script called
+Pre-xml was written. This is used to preprocess the .xml files before they are
+handed to the main processors. Adding one more tool onto the front of the
+processing chain does at least seem to be in the spirit of XML processing.
+
+The XML processors themselves make use of style files, which can be overridden
+by local versions. There is one that applies to all styles, called MyStyle.xsl,
+and others for the different output formats. I have included comments in these
+style files to explain what changes I have made. Some of the changes are quite
+significant.
+
+
+THE PRE-XML SCRIPT
+
+The Pre-xml script copies a .xml file, making certain changes according to the
+options it is given. The currently available options are as follows:
+
+-abstract
+
+  This option causes the <abstract> element to be removed from the XML. The
+  source abuses the <abstract> element by using it to contain the author's
+  address so that it appears on the title page verso in the printed renditions.
+  This just gets in the way for the non-PostScript/PDF renditions.
+
+-ascii
+
+  This option is used for Ascii output formats. It makes the following
+  character replacements:
+
+    &8230;    =>  ...       (sic, no #x)
+    &#x2019;  =>  '         apostrophe
+    &#x201C;  =>  "         opening double quote
+    &#x201D;  =>  "         closing double quote
+    &#x2013;  =>  -         en dash
+    &#x2020;  =>  *         dagger
+    &#x2021;  =>  **        double dagger
+    &#x00a0;  =>  a space   hard space
+    &#x00a9;  =>  (c)       copyright
+
+  In addition, this option causes quotes to be put round <literal> text items,
+  and <quote> and </quote> to be replaced by Ascii quote marks. You would think
+  the stylesheet would cope with the latter, but it seems to generate non-Ascii
+  characters that w3m then turns into question marks.
+
+-bookinfo
+
+  This option causes the <bookinfo> element to be removed from the XML. It is
+  used for the PostScript/PDF forms of the filter document, in order to avoid
+  the generation of a full title page.
+
+-fi
+
+  Replace any occurrence of "fi" by the ligature &#xFB01; except when it is
+  inside an XML element, or inside a <literal> part of the text.
+
+  The use of ligatures would be nice for the PostScript and PDF formats. Sadly,
+  it turns out that fop cannot at present handle the FB01 character correctly.
+  The only format that does so is the HTML format, but when I used this in the
+  test version, people complained that it made searching for words difficult.
+  So at the moment, this option is not used. :-(
+
+-noindex
+
+  Remove the XML to generate a Concept Index and an Options index.
+
+-oneindex
+
+  Remove the XML to generate a Concept and an Options Index, and add XML to
+  generate a single index.
+
+The source document has two types of index entry, for a concept and an options
+index. However, no index is required for the .txt and .texinfo outputs.
+Furthermore, the only output processor that supports multiple indexes is the
+processor that produces "formatted objects" for PostScript and PDF output. The
+HTML processor ignores the XML settings for multiple indexes and just makes one
+unified index. Specifying two indexes gets you two copies of the same index, so
+this has to be changed.
+
+
+CREATING POSTSCRIPT AND PDF
+
+These two output formats are created in three stages. First, the XML is
+pre-processed. For the filter document, the <bookinfo> element is removed so
+that no title page is generated, but for the main specification, no changes are
+currently made.
+
+Second, the xmlto command is used to produce a "formatted objects" (.fo) file.
+This process uses the following stylesheets:
+
+  (1) Either MyStyle-filter-fo.xsl or MyStyle-spec-fo.xsl
+  (2) MyStyle-fo.xsl
+  (3) MyStyle.xsl
+  (4) MyTitleStyle.xsl
+
+The last of these is not used for the filter document, which does not have a
+title page. The first three stylesheets were created manually, either by typing
+directly, or by coping from the standard style sheet and editing.
+
+The final stylesheet has to be created from a template document, which is
+called MyTitlepage.templates.xml. This was copied from the standard styles and
+modified. The template is processed with xsltproc to produce the stylesheet.
+All this apparatus is appallingly heavyweight. The processing is also very slow
+in the case of the specification document. However, there should be no errors.
+
+In the third and final part of the processing, the .fo file that is produced by
+the xmlto command is processed by the fop command to generate either PostScript
+or PDF. This is also very slow, and you get a whole slew of errors, of which
+these are a sample:
+
+  [ERROR] property - "background-position-horizontal" is not implemented yet.
+
+  [ERROR] property - "background-position-vertical" is not implemented yet.
+
+  [INFO] JAI support was not installed (read: not present at build time).
+    Trying to use Jimi instead
+    Error creating background image: Error creating FopImage object (Error
+    creating FopImage object
+    (http://docbook.sourceforge.net/release/images/draft.png) :
+    org.apache.fop.image.JimiImage
+
+  [WARNING] table-layout=auto is not supported, using fixed!
+
+  [ERROR] Unknown enumerated value for property 'span': inherit
+
+  [ERROR] Error in span property value 'inherit':
+    org.apache.fop.fo.expr.PropertyException: No conversion defined
+
+  [ERROR] Areas pending, text probably lost in lineinclude parts matched in the
+    response by response_pattern by means of numeric variables such as
+
+The last one is particularly meaningless gobbledegook. Some of the errors and
+warnings are repeated many times. Nevertheless, it does eventually produce
+usable output, though I have a number of issues with it (see a later section of
+this document). Maybe one day there will be a new release of fop that does
+better. Maybe there will be some other means of producing PostScript and PDF
+from DocBook XML. Maybe porcine aeronautics will really happen.
+
+
+CREATING HTML
+
+Only two stages are needed to produce HTML, but the main specification is
+subsequently postprocessed. The Pre-xml script is called with the -abstract and
+-oneindex options to preprocess the XML. Then the xmlto command creates the
+HTML output directly. For the specification document, a directory of files is
+created, whereas the filter document is output as a single HTML page. The
+following stylesheets are used:
+
+  (1) Either MyStyle-chunk-html.xsl or MyStyle-nochunk-html.xsl
+  (2) MyStyle-html.xsl
+  (3) MyStyle.xsl
+
+The first stylesheet references the chunking or non-chunking standard
+stylesheet, as appropriate.
+
+The original HTML that I produced from the SGCAL input had hyperlinks back from
+chapter and section titles to the table of contents. These links are not
+generated by xmlto. One of the testers pointed out that the lack of these
+links, or simple self-referencing links for titles, makes it harder to copy a
+link name into, for example, a mailing list response.
+
+I could not find where to fiddle with the stylesheets to make such a change, if
+indeed the stylesheets are capable of it. Instead, I wrote a Perl script called
+TidyHTML-spec to do the job for the specification document. It updates the
+index.html file (which contains the the table of contents) setting up anchors,
+and then updates all the chapter files to insert appropriate links.
+
+The index.html file as built by xmlto contains the whole table of contents in a
+single line, which makes is hard to debug by hand. Since I was postprocessing
+it anyway, I arranged to insert newlines after every '>' character.
+
+The TidyHTML-spec script also takes the opportunity to postprocess the
+spec.html/ix01.html file, which contains the document index. Again, the index
+is generated as one single line, so it splits it up. Then it creates a list of
+letters at the top of the index and hyperlinks them both ways from the
+different letter portions of the index.
+
+People wanted similar postprocessing for the filter.html file, so that is now
+done using a similar script called TidyHTML-filter. It was easier to use a
+separate script because filter.html is a single file rather than a directory,
+so the logic is somewhat different.
+
+
+CREATING TEXT FILES
+
+This happens in four stages. The Pre-xml script is called with the -abstract,
+-ascii and -noindex options to remove the <abstract> element, convert the input
+to Ascii characters, and to disable the production of an index. Then the xmlto
+command converts the XML to a single HTML document, using these stylesheets:
+
+  (1) MyStyle-txt-html.xsl
+  (2) MyStyle-html.xsl
+  (3) MyStyle.xsl
+
+The MyStyle-txt-html.xsl stylesheet is the same as MyStyle-nochunk-html.xsl,
+except that it contains an addition item to ensure that a generated "copyright"
+symbol is output as "(c)" rather than the Unicode character. This is necessary
+because the stylesheet itself generates a copyright symbol as part of the
+document title; the character is not in the original input.
+
+The w3m command is used with the -dump option to turn the HTML file into Ascii
+text, but this contains multiple sequences of blank lines that make it look
+awkward, so, finally, a local Perl script called Tidytxt is used to convert
+sequences of blank lines into a single blank line.
+
+
+CREATING INFO FILES
+
+This process starts with the same Pre-xml call as for text files. The
+<abstract> element is deleted, non-ascii characters in the source are
+transliterated, and the <index> elements are removed. The docbook2texi script
+is then called to convert the XML file into a Texinfo file. However, this is
+not quite enough. The converted file ends up with "conceptindex" and
+"optionindex" items, which are not recognized by the makeinfo command. An
+in-line call to Perl in the Makefile changes these to "cindex" and "findex"
+respectively in the final .texinfo file. Finally, a call of makeinfo creates a
+set of .info files.
+
+There is one apparently unconfigurable feature of docbook2texi: it does not
+seem possible to give it a file name for its output. It chooses a name based on
+the title of the document. Thus, the main specification ends up in a file
+called the_exim_mta.texi and the filter document in exim_filtering.texi. These
+files are removed after their contents have been copied and modified by the
+inline Perl call, which makes a .texinfo file.
+
+
+CREATING THE MAN PAGE
+
+I wrote a Perl script called x2man to create the exim.8 man page from the
+DocBook XML source. I deliberately did NOT start from the AsciiDoc source,
+because it is the DocBook source that is the "standard". This comment line in
+the DocBook source marks the start of the command line options:
+
+  <!-- === Start of command line options === -->
+
+A similar line marks the end. If at some time in the future another way other
+than AsciiDoc is used to maintain the DocBook source, it needs to be capable of
+maintaining these comments.
+
+
+UNRESOLVED PROBLEMS
+
+There are a number of unresolved problems with producing the Exim documentation
+in the manner described above. I will describe them here in the hope that in
+future some way round them can be found.
+
+(1)  Errors in the toolchain
+
+     When a whole chain of tools is processing a file, an error somewhere in
+     the middle is often very hard to debug. For instance, an error in the
+     AsciiDoc might not show up until an XML processor throws a wobbly because
+     the generated XML is bad. You have to be able to read XML and figure out
+     what generated what. One of the reasons for creating the "test" series of
+     targets was to help in checking out these kinds of problem.
+
+(2)  There is a mechanism in XML for marking parts of the document as
+     "revised", and I have arranged for AsciiDoc markup to use it. However, at
+     the moment, the only output format that pays attention to this is the HTML
+     output, which sets a green background. There are therefore no revision
+     marks (change bars) in the PostScript, PDF, or text output formats as
+     there used to be. (There never were for Texinfo.)
+
+(3)  The index entries in the HTML format take you to the top of the section
+     that is referenced, instead of to the point in the section where the index
+     marker was set.
+
+(4)  The HTML output supports only a single index, so the concept and options
+     index entries have to be merged.
+
+(5)  The index for the PostScript/PDF output does not merge identical page
+     numbers, which makes some entries look ugly.
+
+(6)  None of the indexes (PostScript/PDF and HTML) make use of textual
+     markup; the text is all roman, without any italic or boldface.
+
+(7)  I turned off hyphenation in the PostScript/PDF output, because it was
+     being done so badly.
+
+     (a) It seems to force hyphenation if it is at all possible, without
+         regard to the "tightness" or "looseness" of the line. Decent
+         formatting software should attempt hyphenation only if the line is
+         over some "looseness" threshold; otherwise you get far too many
+         hyphenations, often for several lines in succession.
+
+     (b) It uses an algorithmic form of hyphenation that doesn't always produce
+         acceptable word breaks. (I prefer to use a hyphenation dictionary.)
+
+(8)  The PostScript/PDF output is badly paginated:
+
+     (a) There seems to be no attempt to avoid "widow" and "orphan" lines on
+         pages. A "widow" is the last line of a paragraph at the top of a page,
+         and an "orphan" is the first line of a paragraph at the bottom of a
+         page.
+
+     (b) There seems to be no attempt to prevent section headings being placed
+         last on a page, with no following text on the page.
+
+(9)  The fop processor does not support "fi" ligatures, not even if you put the
+     appropriate Unicode character into the source by hand.
+
+(10) There are no diagrams in the new documentation. This is something I could
+     work on. The previously-used Aspic command for creating line art from a
+     textual description can output Encapsulated PostScript or Scalar Vector
+     Graphics, which are two standard diagram representations. Aspic could be
+     formally released and used to generate output that could be included in at
+     least some of the output formats.
+
+The consequence of (7), (8), and (9) is that the PostScript/PDF output looks as
+if it comes from some of the very early attempts at text formatting of around
+20 years ago. We can only hope that 20 years' progress is not going to get
+lost, and that things will improve in this area.
+
+
+LIST OF FILES
+
+AdMarkup.txt                   Describes the AsciiDoc markup that is used
+HowItWorks.txt                 This document
+Makefile                       The makefile
+MyAsciidoc.conf                Localized AsciiDoc configuration
+MyStyle-chunk-html.xsl         Stylesheet for chunked HTML output
+MyStyle-filter-fo.xsl          Stylesheet for filter fo output
+MyStyle-fo.xsl                 Stylesheet for any fo output
+MyStyle-html.xsl               Stylesheet for any HTML output
+MyStyle-nochunk-html.xsl       Stylesheet for non-chunked HTML output
+MyStyle-spec-fo.xsl            Stylesheet for spec fo output
+MyStyle-txt-html.xsl           Stylesheet for HTML=>text output
+MyStyle.xsl                    Stylesheet for all output
+MyTitleStyle.xsl               Stylesheet for spec title page
+MyTitlepage.templates.xml      Template for creating MyTitleStyle.xsl
+Myhtml.css                     Experimental css stylesheet for HTML output
+Pre-xml                        Script to preprocess XML
+TidyHTML-filter                Script to tidy up the filter HTML output
+TidyHTML-spec                  Script to tidy up the spec HTML output
+Tidytxt                        Script to compact multiple blank lines
+filter.ascd                    AsciiDoc source of the filter document
+spec.ascd                      AsciiDoc source of the specification document
+x2man                          Script to make the Exim man page from the XML
+
+The file Myhtml.css was an experiment that was not followed through. It is
+mentioned in a comment in MyStyle-html.xsl, but is not at present in use.
+
+
+Philip Hazel
+Last updated: 10 June 2005
diff --git a/doc/doc-docbook/Makefile b/doc/doc-docbook/Makefile
new file mode 100644 (file)
index 0000000..802f740
--- /dev/null
@@ -0,0 +1,177 @@
+# $Cambridge: exim/doc/doc-docbook/Makefile,v 1.1 2005/06/16 10:32:31 ph10 Exp $
+
+# Make file for Exim documentation from Asciidoc source.
+
+notarget:;    @echo "** You must specify a target, in the form x.y, where x is 'filter', 'spec',"
+             @echo "** or 'test', and y is 'xml', 'fo', 'ps', 'pdf', 'html', 'txt', or 'info'."
+             @echo "** One other possible target is 'exim.8'".
+             exit 1
+
+
+############################## MAN PAGE ################################
+
+exim.8: spec.xml
+             ./x2man
+
+########################################################################
+
+
+############################### FILTER #################################
+
+filter.xml:   filter.ascd MyAsciidoc.conf
+             asciidoc -d book -b docbook -f MyAsciidoc.conf filter.ascd
+
+filter-fo.xml: filter.xml Pre-xml
+             Pre-xml -bookinfo <filter.xml >filter-fo.xml
+
+filter-html.xml: filter.xml Pre-xml
+             Pre-xml <filter.xml >filter-html.xml
+
+filter-txt.xml: filter.xml Pre-xml
+             Pre-xml -ascii <filter.xml >filter-txt.xml
+
+filter.fo:    filter-fo.xml MyStyle-filter-fo.xsl MyStyle-fo.xsl MyStyle.xsl
+             /bin/rm -rf filter.fo filter-fo.fo
+             xmlto -x MyStyle-filter-fo.xsl fo filter-fo.xml
+             /bin/mv -f filter-fo.fo filter.fo
+
+filter.ps:    filter.fo
+             fop filter.fo -ps filter.ps
+
+filter.pdf:   filter.fo
+             fop filter.fo -pdf filter.pdf
+
+filter.html:  filter-html.xml TidyHTML-filter MyStyle-nochunk-html.xsl MyStyle-html.xsl MyStyle.xsl
+             /bin/rm -rf filter.html filter-html.html
+             xmlto -x MyStyle-nochunk-html.xsl html-nochunks filter-html.xml
+             /bin/mv -f filter-html.html filter.html
+              ./TidyHTML-filter
+
+filter.txt:   filter-txt.xml Tidytxt MyStyle-txt-html.xsl MyStyle-html.xsl MyStyle.xsl
+             /bin/rm -rf filter-txt.html
+             xmlto -x MyStyle-txt-html.xsl html-nochunks filter-txt.xml
+             w3m -dump filter-txt.html >filter.txt
+
+# I have not found a way of making docbook2texi write its output anywhere
+# other than the file name that it makes up. The --to-stdout option does not
+# work.
+
+filter.info:  filter-txt.xml
+             docbook2texi filter-txt.xml
+             perl -ne 's/conceptindex/cindex/;s/optionindex/findex/;print;' \
+               <exim_filtering.texi | Tidytxt >filter.texinfo
+             /bin/rm -rf exim_filtering.texi
+             makeinfo -o filter.info filter.texinfo
+
+########################################################################
+
+
+################################ SPEC ##################################
+
+spec.xml:     spec.ascd MyAsciidoc.conf
+             asciidoc -d book -b docbook -f MyAsciidoc.conf spec.ascd
+
+spec-fo.xml:  spec.xml Pre-xml
+             Pre-xml <spec.xml >spec-fo.xml
+
+spec-html.xml: spec.xml Pre-xml
+             Pre-xml -abstract -oneindex <spec.xml >spec-html.xml
+
+spec-txt.xml: spec.xml Pre-xml
+             Pre-xml -abstract -ascii -noindex <spec.xml >spec-txt.xml
+
+spec.fo:      spec-fo.xml MyStyle-spec-fo.xsl MyStyle-fo.xsl MyStyle.xsl MyTitleStyle.xsl
+             /bin/rm -rf spec.fo spec-fo.fo
+             xmlto -x MyStyle-spec-fo.xsl fo spec-fo.xml
+             /bin/mv -f spec-fo.fo spec.fo
+
+spec.ps:      spec.fo
+             FOP_OPTS=-Xmx512m fop spec.fo -ps spec.ps
+
+spec.pdf:     spec.fo
+             FOP_OPTS=-Xmx512m fop spec.fo -pdf spec.pdf
+
+spec.html:    spec-html.xml TidyHTML-spec MyStyle-chunk-html.xsl MyStyle-html.xsl MyStyle.xsl
+             /bin/rm -rf spec.html
+             xmlto -x MyStyle-chunk-html.xsl -o spec.html html spec-html.xml
+             ./TidyHTML-spec
+
+spec.txt:     spec-txt.xml Tidytxt MyStyle-txt-html.xsl MyStyle-html.xsl MyStyle.xsl
+             /bin/rm -rf spec-txt.html
+             xmlto -x MyStyle-txt-html.xsl html-nochunks spec-txt.xml
+             w3m -dump spec-txt.html | Tidytxt >spec.txt
+
+# I have not found a way of making docbook2texi write its output anywhere
+# other than the file name that it makes up. The --to-stdout option does not
+# work.
+
+spec.info:    spec-txt.xml
+             docbook2texi spec-txt.xml
+             perl -ne 's/conceptindex/cindex/;s/optionindex/findex/;print;' \
+               <the_exim_mta.texi >spec.texinfo
+             /bin/rm -rf the_exim_mta.texi
+             makeinfo -o spec.info spec.texinfo
+
+########################################################################
+
+
+################################ TEST ##################################
+
+# These targets (similar to the above)  are for running little tests.
+
+test.xml:     test.ascd MyAsciidoc.conf
+             asciidoc -d book -b docbook -f MyAsciidoc.conf test.ascd
+
+test-fo.xml:  test.xml Pre-xml
+             ./Pre-xml <test.xml >test-fo.xml
+
+test-html.xml: test.xml Pre-xml
+             ./Pre-xml -abstract -oneindex <test.xml >test-html.xml
+
+test-txt.xml: test.xml Pre-xml
+             ./Pre-xml -abstract -ascii -noindex <test.xml >test-txt.xml
+
+test.fo:      test-fo.xml MyStyle-spec-fo.xsl MyStyle-fo.xsl MyStyle.xsl MyTitleStyle.xsl
+             /bin/rm -rf test.fo test-fo.fo
+             xmlto -x MyStyle-spec-fo.xsl fo test-fo.xml
+             /bin/mv -f test-fo.fo test.fo
+
+test.ps:      test.fo
+             fop test.fo -ps test.ps
+
+test.pdf:     test.fo
+             fop test.fo -pdf test.pdf
+
+test.html:    test-html.xml MyStyle-nochunk-html.xsl MyStyle-html.xsl MyStyle.xsl
+             /bin/rm -rf test.html test-html.html
+             xmlto -x MyStyle-nochunk-html.xsl html-nochunks test-html.xml
+             /bin/mv -f test-html.html test.html
+
+test.txt:     test-txt.xml Tidytxt MyStyle-txt-html.xsl MyStyle-html.xsl MyStyle.xsl
+             /bin/rm -rf test-txt.html
+             xmlto -x MyStyle-txt-html.xsl html-nochunks test-txt.xml
+             w3m -dump test-txt.html | Tidytxt >test.txt
+
+# I have not found a way of making docbook2texi write its output anywhere
+# other than the file name that it makes up. The --to-stdout option does not
+# work.
+
+test.info:    test-txt.xml
+             docbook2texi test-txt.xml
+             perl -ne 's/conceptindex/cindex/;s/optionindex/findex/;print;' \
+               <short_title.texi >test.texinfo
+             /bin/rm -rf short_title.texi
+             makeinfo -o test.info test.texinfo
+
+########################################################################
+
+
+################################ CLEAN #################################
+
+clean:; /bin/rm -rf exim.8 \
+             filter*.xml spec*.xml test*.xml \
+             *.fo *.html *.pdf *.ps \
+             filter*.txt spec*.txt test*.txt \
+             *.info* *.texinfo *.texi
+
+########################################################################
diff --git a/doc/doc-docbook/MyAsciidoc.conf b/doc/doc-docbook/MyAsciidoc.conf
new file mode 100644 (file)
index 0000000..4b09e5a
--- /dev/null
@@ -0,0 +1,205 @@
+# $Cambridge: exim/doc/doc-docbook/MyAsciidoc.conf,v 1.1 2005/06/16 10:32:31 ph10 Exp $
+
+# Asciidoc configuration customization for creating the DocBook XML sources
+# of the Exim specification and the filter document.
+
+[miscellaneous]
+newline=\n
+
+[quotes]
+_=filename
+$=varname
+%=option
+^=command
+^^=function
+^%|%^=parameter
+``|''=quoted
+
+[tags]
+strong=<emphasis role="bold">|</emphasis>
+
+filename=<filename>|</filename>
+varname=<varname>$|</varname>
+option=<option>|</option>
+command=<command>|</command>
+function=<function>|</function>
+parameter=<parameter>|</parameter>
+quoted=<quote>|</quote>
+
+
+[replacements]
+# Nothing - this is for disambiguating markup
+"##"=
+
+# -- En dash
+(^|[^-])--($|[^-])=\1&#x2013;\2
+
+# --- Em dash
+(^|\s+)---($|\s+)=\1&#x8212;\2
+
+# -- Hard space
+~=&#x00a0;
+
+# ' automatic apostrophe
+([A-Za-z0-9])'([A-Za-z\s])=\1&#x2019;\2
+
+# daggers
+!!=&#x2020;
+!\?=&#x2021;
+
+# The default markup recognizes subscripts and superscripts using tilde and
+# circumflex. We don't want this. These settings manage to turn off the
+# effect, while still allowing tilde to be recognized as a hard space.
+\^(.+?)\^=^\1^
+~(.+?)~=~\1~
+
+
+[attributes]
+# Manual apostrophe: needed for an apostrophe after something quoted, because
+# I can't get the automatic one to work in that situation
+ap=&#x2019;
+
+# Manual tilde: tilde is defined as a hard space, and it doesn't seem possible
+# to quote is using a backslash.
+tl=&#x007e;
+
+# Two hyphens, to stop them being treated as an en dash
+hh=&#x002d;&#x002d;
+
+# Percent: causes confusion with the quote otherwise
+pc=&#x0025;
+
+# Colon: there's a case where this causes trouble
+co=&#x003A;
+
+# The sequence "[]" for use in index terms
+bk=&#x005B;&#x005D;
+
+
+# We need to add extra stuff to the <bookinfo> element
+
+[header]
+<?xml {xmldecl}?>
+<!DOCTYPE book {dtddecl}>
+
+<book lang="en">
+{doctitle#}<bookinfo>
+    <title>{doctitle}</title>
+    <titleabbrev>{doctitleabbrev}</titleabbrev>
+    <date>{date}</date>
+    {authored#}<author>
+        <firstname>{firstname}</firstname>
+        <othername>{middlename}</othername>
+        <surname>{lastname}</surname>
+    {authored#}</author>
+    <authorinitials>{authorinitials}</authorinitials>
+    {revisionhistory%}<revhistory><revision><revnumber>{revision}</revnumber><date>{date}</date>{authorinitials?<authorinitials>{authorinitials}</authorinitials>}{revremark?<revremark>{revremark}</revremark>}</revision></revhistory>
+    <corpname>{companyname}</corpname>
+    <othercredit><contrib>{othercredit},</contrib></othercredit>
+    {copyright#}<copyright><year>{cpyear}</year><holder>{copyright}</holder></copyright>
+    <abstract><para>{abstract}</para></abstract>
+{doctitle#}</bookinfo>
+
+
+# Define a new kind of block that maps to <literallayout> so as not to
+# insist on a monospaced font. Delimiter is &&&.
+
+[blockdef-literallayout]
+delimiter=^&{3,}(\[(?P<args>.*)\])?=*$
+template=literallayoutblock
+presubs=specialcharacters,quotes,replacements,macros,callouts
+
+# The template for my non-monospaced literal layout block
+
+[literallayoutblock]
+<literallayout{revisionflag? revisionflag="{revisionflag}"}>
+|
+</literallayout>
+
+
+# Paragraph substitution - use <para> rather than <simplepara>
+
+[paragraph]
+{title#}<formalpara{id? id="{id}"{revisionflag? revisionflag="{revisionflag}"}}><title>{title}</title><para>
+{title%}<para{id? id="{id}"}{revisionflag? revisionflag="{revisionflag}"}>
+|
+{title%}</para>
+{title#}</para></formalpara>
+{empty}
+
+
+# Define a special table for left-centre-right lines, filling the whole page
+# width, with a border but no separators, for Exim configuration options. It
+# would be nice if this could call the default [table] template, forcing the
+# appropriate attributes, but I have not found a way of doing this.
+
+[tabledef-conf]
+fillchar==
+format=csv
+template=conf-table
+colspec=<colspec align="{colalign}"/>
+bodyrow=<row>|</row>
+bodydata=<entry>|</entry>
+
+[conf-table]
+<{title?table}{title!informaltable}{id? id="{id}"} pgwide="1" frame="all" colsep="0" rowsep="0">
+<title>{title}</title>
+<tgroup cols="{cols}">
+<colspec align="left" colwidth="8*"/>
+<colspec align="center" colwidth = "5*"/>
+<colspec align="center" colwidth = "5*"/>
+<colspec align="right" colwidth = "6*"/>
+{headrows#}<thead>
+{headrows}
+{headrows#}</thead>
+{footrows#}<tfoot>
+{footrows}
+{footrows#}</tfoot>
+<tbody>
+{bodyrows}
+</tbody>
+</tgroup>
+</{title?table}{title!informaltable}>
+
+# The default indexterm macro generates primary index entries for the
+# secondary and tertiary terms as well, which does not make sense
+# in the context of the way I write indexes. As well as a replacement
+# that does the simple, straightforward thing, we actually want to have
+# two different macros: one for concepts and one for options.
+
+[cindex-inlinemacro]
+# Inline index term for concepts.
+<indexterm role="concept">
+  <primary>{1}</primary>
+  <secondary>{2}</secondary>
+  <tertiary>{3}</tertiary>
+</indexterm>
+
+[oindex-inlinemacro]
+# Inline index term for options.
+<indexterm role="option">
+  <primary>{1}</primary>
+  <secondary>{2}</secondary>
+  <tertiary>{3}</tertiary>
+</indexterm>
+
+# Allow for the "role" attribute for an index.
+
+[sect-index]
+<index{id? id="{id}"}{role? role="{role}"}>
+<title>{title}</title>
+|
+</index>
+
+
+# Allow for the "titleabbrev" attribute for chapters.
+
+[sect1]
+<chapter{id? id="{id}"}>
+<title>{title}</title>
+<titleabbrev>{titleabbrev}</titleabbrev>
+|
+</chapter>
+
+
+#### End ####
diff --git a/doc/doc-docbook/MyStyle-chunk-html.xsl b/doc/doc-docbook/MyStyle-chunk-html.xsl
new file mode 100644 (file)
index 0000000..3a1cb91
--- /dev/null
@@ -0,0 +1,20 @@
+<!-- $Cambridge: exim/doc/doc-docbook/MyStyle-chunk-html.xsl,v 1.1 2005/06/16 10:32:31 ph10 Exp $ -->
+
+<!-- This stylesheet driver imports the DocBook XML stylesheet for chunked
+HTML output, and then imports my common stylesheet for HTML output. Finally, it
+fiddles with the chunking parameters to arrange for chapter chunking only (no
+section chunking). -->
+
+<xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform" version='1.0'>
+
+<xsl:import href="/usr/share/sgml/docbook/xsl-stylesheets-1.66.1/xhtml/chunk.xsl"/>
+<xsl:import href="MyStyle-html.xsl"/>
+
+
+<!-- No section chunking; don't output the list of chunks -->
+
+<xsl:param name="chunk.section.depth" select="0"></xsl:param>
+<xsl:param name="chunk.quietly" select="1"/>
+
+
+</xsl:stylesheet>
diff --git a/doc/doc-docbook/MyStyle-filter-fo.xsl b/doc/doc-docbook/MyStyle-filter-fo.xsl
new file mode 100644 (file)
index 0000000..33a6733
--- /dev/null
@@ -0,0 +1,55 @@
+<!-- $Cambridge: exim/doc/doc-docbook/MyStyle-filter-fo.xsl,v 1.1 2005/06/16 10:32:31 ph10 Exp $ -->
+
+<xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform" version='1.0'>
+
+<!-- This stylesheet driver imports the DocBook XML stylesheet for FO output,
+and then imports my common stylesheet that makes changes that are wanted for
+all forms of output. Then it imports my FO stylesheet that contains changes for
+all printed output. Finally, there are some changes that apply only when
+printing the filter document. -->
+
+<xsl:import href="/usr/share/sgml/docbook/xsl-stylesheets-1.66.1/fo/docbook.xsl"/>
+<xsl:import href="MyStyle.xsl"/>
+<xsl:import href="MyStyle-fo.xsl"/>
+
+<!-- For the filter document, we do not want a title page and verso, as it
+isn't really a "book", though we use the book XML style. It turns out that this
+can be fiddled simply by changing the text "Table of Contents" to the title of
+the document.
+
+However, it seems that we have to repeat here the language-specific changes
+that are also present in MyStyle.xsl, because this overrides rather than adds
+to the settings. -->
+
+<xsl:param name="local.l10n.xml" select="document('')"/>
+<l:i18n xmlns:l="http://docbook.sourceforge.net/xmlns/l10n/1.0">
+  <l:l10n language="en">
+
+   <l:gentext key="TableofContents" text="Exim&#x2019;s interfaces to mail filtering"/>
+
+    <!-- The default (as modified above) gives us "Chapter xxx" or "Section
+    xxx", with a capital letter at the start. So we have to make an more
+    complicated explicit change to give just the number. -->
+
+    <l:context name="xref-number">
+      <l:template name="chapter" text="%n"/>
+      <l:template name="sect1" text="%n"/>
+      <l:template name="sect2" text="%n"/>
+      <l:template name="section" text="%n"/>
+    </l:context>
+
+    <!-- I think that having a trailing dot after section numbers looks fussy,
+    whereas you need it after just the digits of a chapter number. In both
+    cases we want to get rid of the word "chapter" or "section". -->
+
+    <l:context name="title-numbered">
+      <l:template name="chapter" text="%n.&#160;%t"/>
+      <l:template name="sect1" text="%n&#160;%t"/>
+      <l:template name="sect2" text="%n&#160;%t"/>
+      <l:template name="section" text="%n&#160;%t"/>
+    </l:context>
+
+  </l:l10n>
+</l:i18n>
+
+</xsl:stylesheet>
diff --git a/doc/doc-docbook/MyStyle-fo.xsl b/doc/doc-docbook/MyStyle-fo.xsl
new file mode 100644 (file)
index 0000000..bd0dd31
--- /dev/null
@@ -0,0 +1,241 @@
+<!-- $Cambridge: exim/doc/doc-docbook/MyStyle-fo.xsl,v 1.1 2005/06/16 10:32:31 ph10 Exp $ -->
+
+<xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform"
+                xmlns:fo="http://www.w3.org/1999/XSL/Format"
+                version="1.0">
+
+<!-- This stylesheet driver contains changes that I want to apply to the
+printed output form of both the filter document and the main Exim
+specification. It is imported by MyStyle-filter-fo.xsl and MyStyle-spec-fo.xsl.
+-->
+
+<xsl:import href="MyTitleStyle.xsl"/>
+
+
+
+<!-- Set A4 paper, double sided -->
+
+<xsl:param name="paper.type" select="'A4'"></xsl:param>
+
+<!-- This currently causes errors
+<xsl:param name="double.sided" select="1"></xsl:param>
+-->
+
+<!-- Allow for typed index entries. The "role" setting works with DocBook
+version 4.2 or earlier. Later versions (which we are not currently using)
+need "type". -->
+
+<xsl:param name="index.on.type" select="1"></xsl:param>
+<xsl:param name="index.on.role" select="1"></xsl:param>
+
+
+<!-- The default uses short chapter titles in the TOC! I want them only for
+use in footer lines. So we have to modify this template. I changed
+"titleabbrev.markup" to "title.markup". While I'm here, I also made chapter
+entries print in bold. -->
+
+<xsl:template name="toc.line">
+  <xsl:variable name="id">
+    <xsl:call-template name="object.id"/>
+  </xsl:variable>
+
+  <xsl:variable name="label">
+    <xsl:apply-templates select="." mode="label.markup"/>
+  </xsl:variable>
+
+  <fo:block text-align-last="justify"
+            end-indent="{$toc.indent.width}pt"
+            last-line-end-indent="-{$toc.indent.width}pt">
+    <fo:inline keep-with-next.within-line="always">
+      <!-- Added lines for bold -->
+      <xsl:choose>
+        <xsl:when test="self::chapter">
+          <xsl:attribute name="font-weight">bold</xsl:attribute>
+        </xsl:when>
+        <xsl:when test="self::index">
+          <xsl:attribute name="font-weight">bold</xsl:attribute>
+        </xsl:when>
+      </xsl:choose>
+      <!--  ..................  -->
+      <fo:basic-link internal-destination="{$id}">
+        <xsl:if test="$label != ''">
+          <xsl:copy-of select="$label"/>
+          <xsl:value-of select="$autotoc.label.separator"/>
+        </xsl:if>
+        <xsl:apply-templates select="." mode="title.markup"/>
+      </fo:basic-link>
+    </fo:inline>
+    <fo:inline keep-together.within-line="always">
+      <xsl:text> </xsl:text>
+      <fo:leader leader-pattern="dots"
+                 leader-pattern-width="3pt"
+                 leader-alignment="reference-area"
+                 keep-with-next.within-line="always"/>
+      <xsl:text> </xsl:text>
+      <fo:basic-link internal-destination="{$id}">
+        <fo:page-number-citation ref-id="{$id}"/>
+      </fo:basic-link>
+    </fo:inline>
+  </fo:block>
+</xsl:template>
+
+
+
+
+
+
+
+<!--
+Adjust the sizes of the fonts for titles; the defaults are too gross.
+-->
+
+<!-- Level 1 is sect1 level -->
+
+<xsl:attribute-set name="section.title.level1.properties">
+  <xsl:attribute name="font-size">
+    <xsl:value-of select="$body.font.master * 1.2"></xsl:value-of>
+    <xsl:text>pt</xsl:text>
+  </xsl:attribute>
+</xsl:attribute-set>
+
+
+<!-- Fiddling with chapter titles is more messy -->
+
+<xsl:template match="title" mode="chapter.titlepage.recto.auto.mode">
+  <fo:block xmlns:fo="http://www.w3.org/1999/XSL/Format"
+            xsl:use-attribute-sets="chapter.titlepage.recto.style"
+            margin-left="{$title.margin.left}"
+            font-size="17pt"
+            font-weight="bold"
+            font-family="{$title.font.family}">
+    <xsl:call-template name="component.title">
+      <xsl:with-param name="node" select="ancestor-or-self::chapter[1]"/>
+    </xsl:call-template>
+  </fo:block>
+</xsl:template>
+
+<xsl:template match="title" mode="chapter.titlepage.verso.auto.mode">
+  <fo:block xmlns:fo="http://www.w3.org/1999/XSL/Format"
+            xsl:use-attribute-sets="chapter.titlepage.recto.style"
+            margin-left="{$title.margin.left}"
+            font-size="17pt"
+            font-weight="bold"
+            font-family="{$title.font.family}">
+    <xsl:call-template name="component.title">
+      <xsl:with-param name="node" select="ancestor-or-self::chapter[1]"/>
+    </xsl:call-template>
+  </fo:block>
+</xsl:template>
+
+
+<!-- This provides a hard pagebreak mechanism as a get-out -->
+
+<xsl:template match="processing-instruction('hard-pagebreak')">
+  <fo:block xmlns:fo="http://www.w3.org/1999/XSL/Format" break-before='page'>
+  </fo:block>
+</xsl:template>
+
+
+<!-- Sort out the footer. Useful information is available at
+http://www.sagehill.net/docbookxsl/PrintHeaders.html
+-->
+
+
+<xsl:attribute-set name="footer.content.properties">
+  <!-- <xsl:attribute name="font-family">serif</xsl:attribute> -->
+  <!-- <xsl:attribute name="font-size">9pt</xsl:attribute> -->
+  <xsl:attribute name="font-style">italic</xsl:attribute>
+</xsl:attribute-set>
+
+
+
+
+<!-- Things that can be inserted into the footer are:
+
+<fo:page-number/>
+Inserts the current page number.
+
+<xsl:apply-templates select="." mode="title.markup"/>
+Inserts the title of the current chapter, appendix, or other component.
+
+<xsl:apply-templates select="." mode="titleabbrev.markup"/>
+Inserts the titleabbrev of the current chapter, appendix, or other component,
+if it is available. Otherwise it inserts the regular title.
+
+<xsl:apply-templates select="." mode="object.title.markup"/>
+Inserts the chapter title with chapter number label. Likewise for appendices.
+
+<fo:retrieve-marker ... />      Used to retrieve the current section name.
+
+<xsl:apply-templates select="//corpauthor[1]"/>
+Inserts the value of the first corpauthor element found anywhere in the
+document.
+
+<xsl:call-template name="datetime.format">
+  <xsl:with-param ...
+Inserts a date timestamp.
+
+<xsl:call-template name="draft.text"/>
+Inserts the Draft message if draft.mode is currently on.
+
+<fo:external-graphic ... />
+Inserts a graphical image.
+See the section Graphic in header or footer for details.
+-->
+
+
+<xsl:template name="footer.content">
+  <xsl:param name="pageclass" select="''"/>
+  <xsl:param name="sequence" select="''"/>
+  <xsl:param name="position" select="''"/>
+  <xsl:param name="gentext-key" select="''"/>
+
+  <fo:block>
+    <!-- pageclass can be front, body, back -->
+    <!-- sequence can be odd, even, first, blank -->
+    <!-- position can be left, center, right -->
+    <xsl:choose>
+      <xsl:when test="$pageclass = 'titlepage'">
+        <!-- nop; no footer on title pages -->
+      </xsl:when>
+
+      <xsl:when test="$double.sided != 0 and $sequence = 'even'
+                      and $position='left'">
+        <fo:page-number/>
+      </xsl:when>
+
+      <xsl:when test="$double.sided != 0 and ($sequence = 'odd' or $sequence = 'first')
+                      and $position='right'">
+        <fo:page-number/>
+      </xsl:when>
+
+      <xsl:when test="$double.sided = 0 and $position='center'">
+        <fo:page-number/>
+      </xsl:when>
+
+      <xsl:when test="$double.sided = 0 and $position='right'">
+        <xsl:apply-templates select="." mode="titleabbrev.markup"/>
+      </xsl:when>
+
+      <xsl:when test="$sequence='blank'">
+        <xsl:choose>
+          <xsl:when test="$double.sided != 0 and $position = 'left'">
+            <fo:page-number/>
+          </xsl:when>
+          <xsl:when test="$double.sided = 0 and $position = 'center'">
+            <fo:page-number/>
+          </xsl:when>
+          <xsl:otherwise>
+            <!-- nop -->
+          </xsl:otherwise>
+        </xsl:choose>
+      </xsl:when>
+
+      <xsl:otherwise>
+        <!-- nop -->
+      </xsl:otherwise>
+    </xsl:choose>
+  </fo:block>
+</xsl:template>
+
+</xsl:stylesheet>
diff --git a/doc/doc-docbook/MyStyle-html.xsl b/doc/doc-docbook/MyStyle-html.xsl
new file mode 100644 (file)
index 0000000..e0b7537
--- /dev/null
@@ -0,0 +1,171 @@
+<!-- $Cambridge: exim/doc/doc-docbook/MyStyle-html.xsl,v 1.1 2005/06/16 10:32:31 ph10 Exp $ -->
+
+<xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform" version='1.0'>
+
+<!-- This stylesheet driver imports my common stylesheet that makes some
+changes that are wanted for all forms of output. Then it makes changes that are
+specific to HTML output. -->
+
+<xsl:import href="MyStyle.xsl"/>
+
+<xsl:param name="shade.verbatim" select="1"></xsl:param>
+
+<xsl:attribute-set name="shade.verbatim.style">
+  <xsl:attribute name="bgcolor">#F0F0E0</xsl:attribute>
+  <xsl:attribute name="width">100%</xsl:attribute>
+  <xsl:attribute name="cellpadding">2</xsl:attribute>
+  <xsl:attribute name="border">0</xsl:attribute>
+</xsl:attribute-set>
+
+<!-- This is how you can make use of a CSS stylesheet, but at present I'm
+not doing so. -->
+
+<!--
+<xsl:param name="html.stylesheet" select="'Myhtml.css'"/>
+-->
+
+
+<!-- This removes the title of the current page from the top of the page -
+redundant because each page is a chapter, whose title shows just below. It also
+removes the titles of the next/prev at the bottom of the page, but I don't
+think that matters too much. -->
+
+<xsl:param name="navig.showtitles" select="'0'"/>
+
+
+<!-- This allows for the setting of RevisionFlag on elements. -->
+
+<xsl:param name="show.revisionflag" select="'1'"/>
+
+<xsl:template name="system.head.content">
+<style type="text/css">
+<xsl:text>
+div.added    { background-color: #ffff99; }
+div.deleted  { text-decoration: line-through;
+               background-color: #FF7F7F; }
+div.changed  { background-color: #99ff99; }
+div.off      {  }
+
+span.added   { background-color: #ffff99; }
+span.deleted { text-decoration: line-through;
+               background-color: #FF7F7F; }
+span.changed { background-color: #99ff99; }
+span.off     {  }
+</xsl:text>
+</style>
+</xsl:template>
+
+<xsl:template match="*[@revisionflag]">
+  <xsl:choose>
+    <xsl:when test="local-name(.) = 'para' or local-name(.) = 'simpara'                     or local-name(.) = 'formalpara'                     or local-name(.) = 'section'                     or local-name(.) = 'sect1'                     or local-name(.) = 'sect2'                     or local-name(.) = 'sect3'                     or local-name(.) = 'sect4'                     or local-name(.) = 'sect5'                     or local-name(.) = 'chapter'                     or local-name(.) = 'preface'                     or local-name(.) = 'itemizedlist'                     or local-name(.) = 'varlistentry'                     or local-name(.) = 'glossary'                     or local-name(.) = 'bibliography'                     or local-name(.) = 'index'                     or local-name(.) = 'appendix'">
+      <div class="{@revisionflag}">
+        <xsl:apply-imports/>
+      </div>
+    </xsl:when>
+    <xsl:when test="local-name(.) = 'phrase' or local-name(.) = 'ulink'                     or local-name(.) = 'link'                     or local-name(.) = 'filename'                     or local-name(.) = 'literal'                     or local-name(.) = 'member'                     or local-name(.) = 'glossterm'                     or local-name(.) = 'sgmltag'                     or local-name(.) = 'quote'                     or local-name(.) = 'emphasis'                     or local-name(.) = 'command'                     or local-name(.) = 'xref'">
+      <span class="{@revisionflag}">
+        <xsl:apply-imports/>
+      </span>
+    </xsl:when>
+    <xsl:when test="local-name(.) = 'listitem' or local-name(.) = 'entry'                     or local-name(.) = 'title'">
+      <!-- nop; these are handled directly in the stylesheet -->
+      <xsl:apply-imports/>
+    </xsl:when>
+    <xsl:otherwise>
+      <xsl:message>
+        <xsl:text>Revisionflag on unexpected element: </xsl:text>
+        <xsl:value-of select="local-name(.)"/>
+        <xsl:text> (Assuming block)</xsl:text>
+      </xsl:message>
+      <div class="{@revisionflag}">
+        <xsl:apply-imports/>
+      </div>
+    </xsl:otherwise>
+  </xsl:choose>
+</xsl:template>
+
+
+<!-- The default uses short chapter titles in the TOC! I want them only for
+use in footer lines in printed output. So we have to modify this template. I
+changed "titleabbrev.markup" to "title.markup". -->
+
+<xsl:template name="toc.line">
+  <xsl:param name="toc-context" select="."/>
+  <xsl:param name="depth" select="1"/>
+  <xsl:param name="depth.from.context" select="8"/>
+
+ <span>
+  <xsl:attribute name="class"><xsl:value-of select="local-name(.)"/></xsl:attribute>
+  <a>
+    <xsl:attribute name="href">
+      <xsl:call-template name="href.target">
+        <xsl:with-param name="context" select="$toc-context"/>
+      </xsl:call-template>
+    </xsl:attribute>
+
+    <xsl:variable name="label">
+      <xsl:apply-templates select="." mode="label.markup"/>
+    </xsl:variable>
+    <xsl:copy-of select="$label"/>
+    <xsl:if test="$label != ''">
+      <xsl:value-of select="$autotoc.label.separator"/>
+    </xsl:if>
+
+    <xsl:apply-templates select="." mode="title.markup"/>
+  </a>
+  </span>
+</xsl:template>
+
+
+<!-- The default stylesheets generate both chapters and sections with <h2>
+headings in the HTML. The argument is that the HTML headings don't go deep
+enough to match the DocBook levels. But surely it would be better to stop them
+at the bottom end? Anyway, the Exim documents have only one level of section
+within chapters, and even if they went to two, it wouldn't exhaust HTML's
+capabilities. So I have copied the style stuff here, making a 1-character
+change from "+ 1" to "+ 2" in roughly the middle. -->
+
+<xsl:template name="section.heading">
+  <xsl:param name="section" select="."/>
+  <xsl:param name="level" select="1"/>
+  <xsl:param name="allow-anchors" select="1"/>
+  <xsl:param name="title"/>
+  <xsl:param name="class" select="'title'"/>
+
+  <xsl:variable name="id">
+    <xsl:choose>
+      <!-- if title is in an *info wrapper, get the grandparent -->
+      <xsl:when test="contains(local-name(..), 'info')">
+        <xsl:call-template name="object.id">
+          <xsl:with-param name="object" select="../.."/>
+        </xsl:call-template>
+      </xsl:when>
+      <xsl:otherwise>
+        <xsl:call-template name="object.id">
+          <xsl:with-param name="object" select=".."/>
+        </xsl:call-template>
+      </xsl:otherwise>
+    </xsl:choose>
+  </xsl:variable>
+
+  <!-- HTML H level is two higher than section level -->
+  <xsl:variable name="hlevel" select="$level + 2"/>
+  <xsl:element name="h{$hlevel}">
+    <xsl:attribute name="class"><xsl:value-of select="$class"/></xsl:attribute>
+    <xsl:if test="$css.decoration != '0'">
+      <xsl:if test="$hlevel&lt;3">
+        <xsl:attribute name="style">clear: both</xsl:attribute>
+      </xsl:if>
+    </xsl:if>
+    <xsl:if test="$allow-anchors != 0">
+      <xsl:call-template name="anchor">
+        <xsl:with-param name="node" select="$section"/>
+        <xsl:with-param name="conditional" select="0"/>
+      </xsl:call-template>
+    </xsl:if>
+    <xsl:copy-of select="$title"/>
+  </xsl:element>
+</xsl:template>
+
+
+</xsl:stylesheet>
diff --git a/doc/doc-docbook/MyStyle-nochunk-html.xsl b/doc/doc-docbook/MyStyle-nochunk-html.xsl
new file mode 100644 (file)
index 0000000..d067173
--- /dev/null
@@ -0,0 +1,11 @@
+<!-- $Cambridge: exim/doc/doc-docbook/MyStyle-nochunk-html.xsl,v 1.1 2005/06/16 10:32:31 ph10 Exp $ -->
+
+<xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform" version='1.0'>
+
+<!-- This stylesheet driver imports the DocBook XML stylesheet for unchunked
+HTML output, and then imports my common stylesheet for HTML output. -->
+
+<xsl:import href="/usr/share/sgml/docbook/xsl-stylesheets-1.66.1/xhtml/docbook.xsl"/>
+<xsl:import href="MyStyle-html.xsl"/>
+
+</xsl:stylesheet>
diff --git a/doc/doc-docbook/MyStyle-spec-fo.xsl b/doc/doc-docbook/MyStyle-spec-fo.xsl
new file mode 100644 (file)
index 0000000..ead674c
--- /dev/null
@@ -0,0 +1,17 @@
+<!-- $Cambridge: exim/doc/doc-docbook/MyStyle-spec-fo.xsl,v 1.1 2005/06/16 10:32:31 ph10 Exp $ -->
+
+<xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform" version='1.0'>
+
+<!-- This stylesheet driver imports the DocBook XML stylesheet for FO output,
+and then imports my common stylesheet that makes changes that are wanted for
+all forms of output. Then it imports my FO stylesheet that contains changes for
+all printed output. Finally, there are some changes that apply only when
+printing the Exim specification document. -->
+
+<xsl:import href="/usr/share/sgml/docbook/xsl-stylesheets-1.66.1/fo/docbook.xsl"/>
+<xsl:import href="MyStyle.xsl"/>
+<xsl:import href="MyStyle-fo.xsl"/>
+
+<!-- Nothing special for the full spec document yet -->
+
+</xsl:stylesheet>
diff --git a/doc/doc-docbook/MyStyle-txt-html.xsl b/doc/doc-docbook/MyStyle-txt-html.xsl
new file mode 100644 (file)
index 0000000..7ec02ec
--- /dev/null
@@ -0,0 +1,23 @@
+<!-- $Cambridge: exim/doc/doc-docbook/MyStyle-txt-html.xsl,v 1.1 2005/06/16 10:32:31 ph10 Exp $ -->
+
+<xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform" version='1.0'>
+
+<!-- This stylesheet driver imports the DocBook XML stylesheet for unchunked
+HTML output, and then imports my common stylesheet for HTML output. Then it
+adds an instruction to use "(c)" for copyright rather than the Unicode
+character. -->
+
+<xsl:import href="/usr/share/sgml/docbook/xsl-stylesheets-1.66.1/xhtml/docbook.xsl"/>
+<xsl:import href="MyStyle-html.xsl"/>
+
+<xsl:template name="dingbat.characters">
+  <xsl:param name="dingbat">bullet</xsl:param>
+  <xsl:choose>
+    <xsl:when test="$dingbat='copyright'">(c)</xsl:when>
+    <xsl:otherwise>
+      <xsl:text>?</xsl:text>
+    </xsl:otherwise>
+  </xsl:choose>
+</xsl:template>
+
+</xsl:stylesheet>
diff --git a/doc/doc-docbook/MyStyle.xsl b/doc/doc-docbook/MyStyle.xsl
new file mode 100644 (file)
index 0000000..a3e05cc
--- /dev/null
@@ -0,0 +1,202 @@
+<!-- $Cambridge: exim/doc/doc-docbook/MyStyle.xsl,v 1.1 2005/06/16 10:32:31 ph10 Exp $ -->
+
+<xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform" version='1.0'>
+
+<!-- This file contains changes to the Docbook XML stylesheets that I want to
+have happen in all forms of output. It is imported by all the drivers. -->
+
+
+<!-- Set body font size -->
+
+<xsl:param name="body.font.master">11</xsl:param>
+
+<!-- Set no relative indent for titles and body -->
+
+<xsl:param name="title.margin.left">0pt</xsl:param>
+
+
+<!-- This removes the dot at the end of run-in titles, which we use
+for formal paragraphs for command line options. -->
+
+<xsl:param name="runinhead.default.title.end.punct" select="' '"></xsl:param>
+
+
+<!-- Without this setting, variable lists get misformatted in the FO case,
+causing overprinting. Maybe with a later release of fop the need to do this
+might go away. -->
+
+<xsl:param name="variablelist.as.blocks" select="1"></xsl:param>
+
+
+<!--
+Cause sections to be numbered, and to include the outer component number.
+-->
+
+<xsl:param name="section.autolabel">1</xsl:param>
+<xsl:param name="section.label.includes.component.label">1</xsl:param>
+
+
+<!--
+Specify TOCs only for top-level things. No TOCs for components (e.g. chapters)
+-->
+
+<xsl:param name="generate.toc">
+article   toc,title
+book      toc,title
+</xsl:param>
+
+
+<!-- Turn off the poor hyphenation -->
+
+<xsl:param name="hyphenate">false</xsl:param>
+
+
+<!--
+Generate only numbers, no titles, in cross references.
+-->
+
+<xsl:param name="xref.with.number.and.title">0</xsl:param>
+
+
+<!-- Hopefully this might do something useful? It doesn't seem to. -->
+
+<xsl:param name="fop.extensions" select="1"></xsl:param>
+
+
+<!-- Output variable names in italic rather than the default monospace. -->
+
+<xsl:template match="varname">
+  <xsl:call-template name="inline.italicseq"/>
+</xsl:template>
+
+
+<!-- Output file names in italic rather than the default monospace. -->
+
+<xsl:template match="filename">
+  <xsl:call-template name="inline.italicseq"/>
+</xsl:template>
+
+
+<!-- Output options in bold rather than the default monospace. -->
+
+<xsl:template match="option">
+  <xsl:call-template name="inline.boldseq"/>
+</xsl:template>
+
+
+<!--
+Make a number of more detailed changes to the style that involve more than just
+fiddling with a parameter.
+-->
+
+<xsl:param name="local.l10n.xml" select="document('')"/>
+<l:i18n xmlns:l="http://docbook.sourceforge.net/xmlns/l10n/1.0">
+  <l:l10n language="en">
+
+    <!-- The default (as modified above) gives us "Chapter xxx" or "Section
+    xxx", with a capital letter at the start. So we have to make an more
+    complicated explicit change to give just the number. -->
+
+    <l:context name="xref-number">
+      <l:template name="chapter" text="%n"/>
+      <l:template name="sect1" text="%n"/>
+      <l:template name="sect2" text="%n"/>
+      <l:template name="section" text="%n"/>
+    </l:context>
+
+    <!-- I think that having a trailing dot after section numbers looks fussy,
+    whereas you need it after just the digits of a chapter number. In both
+    cases we want to get rid of the word "chapter" or "section". -->
+
+    <l:context name="title-numbered">
+      <l:template name="chapter" text="%n.&#160;%t"/>
+      <l:template name="sect1" text="%n&#160;%t"/>
+      <l:template name="sect2" text="%n&#160;%t"/>
+      <l:template name="section" text="%n&#160;%t"/>
+    </l:context>
+
+  </l:l10n>
+</l:i18n>
+
+
+<!-- The default has far too much space on either side of displays and lists -->
+
+<xsl:attribute-set name="verbatim.properties">
+  <xsl:attribute name="space-before.minimum">0em</xsl:attribute>
+  <xsl:attribute name="space-before.optimum">0em</xsl:attribute>
+  <xsl:attribute name="space-before.maximum">0em</xsl:attribute>
+  <xsl:attribute name="space-after.minimum">0em</xsl:attribute>
+  <xsl:attribute name="space-after.optimum">0em</xsl:attribute>
+  <xsl:attribute name="space-after.maximum">0em</xsl:attribute>
+  <xsl:attribute name="start-indent">0.3in</xsl:attribute>
+</xsl:attribute-set>
+
+<xsl:attribute-set name="list.block.spacing">
+  <xsl:attribute name="space-before.optimum">0em</xsl:attribute>
+  <xsl:attribute name="space-before.minimum">0em</xsl:attribute>
+  <xsl:attribute name="space-before.maximum">0em</xsl:attribute>
+  <xsl:attribute name="space-after.optimum">0em</xsl:attribute>
+  <xsl:attribute name="space-after.minimum">0em</xsl:attribute>
+  <xsl:attribute name="space-after.maximum">0em</xsl:attribute>
+</xsl:attribute-set>
+
+<!-- List item spacing -->
+
+<xsl:attribute-set name="list.item.spacing">
+  <xsl:attribute name="space-before.optimum">0.8em</xsl:attribute>
+  <xsl:attribute name="space-before.minimum">0.8em</xsl:attribute>
+  <xsl:attribute name="space-before.maximum">1em</xsl:attribute>
+</xsl:attribute-set>
+
+<!-- Reduce the space after informal tables -->
+
+<xsl:attribute-set name="informal.object.properties">
+  <xsl:attribute name="space-before.minimum">1em</xsl:attribute>
+  <xsl:attribute name="space-before.optimum">1em</xsl:attribute>
+  <xsl:attribute name="space-before.maximum">2em</xsl:attribute>
+  <xsl:attribute name="space-after.minimum">0em</xsl:attribute>
+  <xsl:attribute name="space-after.optimum">0em</xsl:attribute>
+  <xsl:attribute name="space-after.maximum">0em</xsl:attribute>
+</xsl:attribute-set>
+
+<!-- Reduce the space after section titles. 0 is not small enough. -->
+
+<xsl:attribute-set name="section.title.level1.properties">
+  <xsl:attribute name="space-after.minimum">-6pt</xsl:attribute>
+  <xsl:attribute name="space-after.optimum">-4pt</xsl:attribute>
+  <xsl:attribute name="space-after.maximum">0pt</xsl:attribute>
+</xsl:attribute-set>
+
+<!-- Slightly reduce the space before paragraphs -->
+
+<xsl:attribute-set name="normal.para.spacing">
+  <xsl:attribute name="space-before.optimum">0.8em</xsl:attribute>
+  <xsl:attribute name="space-before.minimum">0.8em</xsl:attribute>
+  <xsl:attribute name="space-before.maximum">1.0em</xsl:attribute>
+</xsl:attribute-set>
+
+
+<xsl:attribute-set name="table.cell.padding">
+  <xsl:attribute name="padding-left">2pt</xsl:attribute>
+  <xsl:attribute name="padding-right">2pt</xsl:attribute>
+  <xsl:attribute name="padding-top">0pt</xsl:attribute>
+  <xsl:attribute name="padding-bottom">0pt</xsl:attribute>
+</xsl:attribute-set>
+
+
+
+<!-- Turn off page header rule -->
+<xsl:param name="header.rule" select="0"></xsl:param>
+
+<!-- Remove page header content -->
+<xsl:template name="header.content"/>
+
+<!-- Remove space for page header -->
+<xsl:param name="body.margin.top" select="'0in'"></xsl:param>
+<xsl:param name="region.before.extent" select="'0in'"></xsl:param>
+
+<!-- Turn off page footer rule -->
+<xsl:param name="footer.rule" select="0"></xsl:param>
+
+
+</xsl:stylesheet>
diff --git a/doc/doc-docbook/MyTitlepage.templates.xml b/doc/doc-docbook/MyTitlepage.templates.xml
new file mode 100644 (file)
index 0000000..27c4c8a
--- /dev/null
@@ -0,0 +1,101 @@
+<!DOCTYPE t:templates [
+<!ENTITY hsize0 "10pt">
+<!ENTITY hsize1 "12pt">
+<!ENTITY hsize2 "14.4pt">
+<!ENTITY hsize3 "17.28pt">
+<!ENTITY hsize4 "20.736pt">
+<!ENTITY hsize5 "24.8832pt">
+<!ENTITY hsize0space "7.5pt"> <!-- 0.75 * hsize0 -->
+<!ENTITY hsize1space "9pt"> <!-- 0.75 * hsize1 -->
+<!ENTITY hsize2space "10.8pt"> <!-- 0.75 * hsize2 -->
+<!ENTITY hsize3space "12.96pt"> <!-- 0.75 * hsize3 -->
+<!ENTITY hsize4space "15.552pt"> <!-- 0.75 * hsize4 -->
+<!ENTITY hsize5space "18.6624pt"> <!-- 0.75 * hsize5 -->
+]>
+
+<!-- $Cambridge: exim/doc/doc-docbook/MyTitlepage.templates.xml,v 1.1 2005/06/16 10:32:31 ph10 Exp $ -->
+
+<!-- This document is copied from the DocBook XSL stylesheets, and modified to
+do what I want it to do for the Exim reference manual. Process this document
+with:
+
+xsltproc -output MyTitleStyle.xsl \
+  /usr/share/sgml/docbook/xsl-stylesheets-1.66.1/template/titlepage.xsl \
+  MyTitlepage.templates.xml
+
+in order to generate a style sheet called MyTitleStyle.xsl. That is then
+included in my customization stylesheet. What a lot of heavyweight apparatus we
+need to set up! -->
+
+
+<t:templates xmlns:t="http://nwalsh.com/docbook/xsl/template/1.0"
+             xmlns:param="http://nwalsh.com/docbook/xsl/template/1.0/param"
+             xmlns:fo="http://www.w3.org/1999/XSL/Format"
+             xmlns:xsl="http://www.w3.org/1999/XSL/Transform">
+
+<!-- ********************************************************************
+     $Id: titlepage.templates.xml,v 1.23 2003/12/16 00:30:49 bobstayton Exp $
+     ********************************************************************
+
+     This file is part of the DocBook XSL Stylesheet distribution.
+     See ../README or http://docbook.sf.net/ for copyright
+     and other information.
+
+     ******************************************************************** -->
+
+<!-- ==================================================================== -->
+
+  <t:titlepage t:element="book" t:wrapper="fo:block">
+    <t:titlepage-content t:side="recto">
+      <title
+             t:named-template="division.title"
+             param:node="ancestor-or-self::book[1]"
+             text-align="center"
+             font-size="&hsize5;"
+             space-before="&hsize5space;"
+             font-weight="bold"
+             font-family="{$title.fontset}"/>
+      <subtitle
+                text-align="center"
+                font-size="&hsize4;"
+                space-before="&hsize4space;"
+                font-family="{$title.fontset}"/>
+      <corpauthor font-size="&hsize3;"
+                  keep-with-next="always"
+                  space-before="2in"/>
+      <authorgroup space-before="2in"/>
+      <author font-size="&hsize3;"
+              space-before="&hsize2space;"
+              keep-with-next="always"/>
+    </t:titlepage-content>
+
+  <t:titlepage-content t:side="verso">
+      <title
+             t:named-template="book.verso.title"
+             font-size="&hsize2;"
+             font-weight="bold"
+             font-family="{$title.fontset}"/>
+      <corpauthor/>
+      <authorgroup t:named-template="verso.authorgroup"/>
+      <author/>
+      <othercredit/>
+      <pubdate space-before="1em"/>
+      <abstract/>
+      <copyright/>
+      <legalnotice font-size="8pt"/>
+  </t:titlepage-content>
+
+<!-- This change stops it putting a blank page after the verso -->
+  <t:titlepage-separator>
+<!--      <fo:block break-after="page"/> -->
+  </t:titlepage-separator>
+
+  <t:titlepage-before t:side="recto">
+  </t:titlepage-before>
+
+  <t:titlepage-before t:side="verso">
+      <fo:block break-after="page"/>
+  </t:titlepage-before>
+</t:titlepage>
+
+</t:templates>
diff --git a/doc/doc-docbook/Myhtml.css b/doc/doc-docbook/Myhtml.css
new file mode 100644 (file)
index 0000000..8a69817
--- /dev/null
@@ -0,0 +1,31 @@
+# $Cambridge: exim/doc/doc-docbook/Myhtml.css,v 1.1 2005/06/16 10:32:31 ph10 Exp $
+
+.screen {
+        font-family: monospace;
+        font-size: 1em;
+        display: block;
+        padding: 10px;
+        border: 1px solid #bbb;
+        background-color: #eee;
+        color: #000;
+        overflow: auto;
+        border-radius: 2.5px;
+        -moz-border-radius: 2.5px;
+        margin: 0.5em 2em;
+
+}
+
+.programlisting {
+        font-family: monospace;
+        font-size: 1em;
+        display: block;
+        padding: 10px;
+        border: 1px solid #bbb;
+        background-color: #ddd;
+        color: #000;
+        overflow: auto;
+        border-radius: 2.5px;
+        -moz-border-radius: 2.5px;
+        margin: 0.5em 2em;
+}
+
diff --git a/doc/doc-docbook/Pre-xml b/doc/doc-docbook/Pre-xml
new file mode 100755 (executable)
index 0000000..113e6f9
--- /dev/null
@@ -0,0 +1,173 @@
+#! /usr/bin/perl
+
+# $Cambridge: exim/doc/doc-docbook/Pre-xml,v 1.1 2005/06/16 10:32:31 ph10 Exp $
+
+# Script to pre-process XML input before processing it for various purposes.
+# Options specify which transformations are to be done. Monospaced literal
+# layout blocks are never touched.
+
+# Changes:
+
+# -abstract: Remove the <abstract> element
+
+# -ascii:    Replace &8230;   (sic, no x) with ...
+#            Replace &#x2019; by '
+#            Replace &#x201C; by "
+#            Replace &#x201D; by "
+#            Replace &#x2013; by -
+#            Replace &#x2020; by *
+#            Replace &#x2021; by **
+#            Replace &#x00a0; by a space
+#            Replace &#169;   by (c)
+#            Put quotes round <literal> text
+#            Put quotes round <quote> text
+
+# -bookinfo: Remove the <bookinfo> element from the file
+
+# -fi:       Replace "fi" by &#xFB01; except when it is in an XML element, or
+#            inside a <literal>.
+
+# -noindex   Remove the XML to generate a Concept and an Options index.
+# -oneindex  Ditto, but add XML to generate a single index.
+
+
+
+# The function that processes non-literal monospaced text
+
+sub process()
+{
+my($s) = $_[0];
+
+$s =~ s/fi(?![^<>]*>)/&#xFB01;/g if $ligatures;
+
+if ($ascii)
+  {
+  $s =~ s/&#8230;/.../g;
+  $s =~ s/&#x2019;/'/g;
+  $s =~ s/&#x201C;/"/g;
+  $s =~ s/&#x201D;/"/g;
+  $s =~ s/&#x2013;/-/g;
+  $s =~ s/&#x2020;/*/g;
+  $s =~ s/&#x2021;/**/g;
+  $s =~ s/&#x00a0;/ /g;
+  $s =~ s/&#x00a9;/(c)/g;
+  $s =~ s/<quote>/"/g;
+  $s =~ s/<\/quote>/"/g;
+  }
+
+$s;
+}
+
+
+# The main program
+
+$abstract  = 0;
+$ascii     = 0;
+$bookinfo  = 0;
+$inliteral = 0;
+$ligatures = 0;
+$madeindex = 0;
+$noindex   = 0;
+$oneindex  = 0;
+
+foreach $arg (@ARGV)
+  {
+  if    ($arg eq "-fi")       { $ligatures = 1; }
+  elsif ($arg eq "-abstract") { $abstract = 1; }
+  elsif ($arg eq "-ascii")    { $ascii = 1; }
+  elsif ($arg eq "-bookinfo") { $bookinfo = 1; }
+  elsif ($arg eq "-noindex")  { $noindex = 1; }
+  elsif ($arg eq "-oneindex") { $oneindex = 1; }
+  else  { die "** Pre-xml: Unknown option \"$arg\"\n"; }
+  }
+
+while (<STDIN>)
+  {
+  # Remove <abstract> if required
+
+  next if ($abstract && /^\s*<abstract>/);
+
+  # Remove <bookinfo> if required
+
+  if ($bookinfo && /^<bookinfo/)
+    {
+    while (<STDIN>) { last if /^<\/bookinfo/; }
+    next;
+    }
+
+  # Copy monospaced literallayout blocks
+
+  if (/^<literallayout class="monospaced">/)
+    {
+    print;
+    while (<STDIN>)
+      {
+      print;
+      last if /^<\/literallayout>/;
+      }
+    next;
+    }
+
+  # Adjust index-generation code if required
+
+  if (($noindex || $oneindex) && /^<index[\s>]/)
+    {
+    while (<STDIN>)
+      {
+      last if /^<\/index>/;
+      }
+
+    if ($oneindex && !$madeindex)
+      {
+      $madeindex = 1;
+      print "<index><title>Index</title></index>\n";
+      }
+
+    next;
+    }
+
+  # A line that is not in a monospaced literal block; keep track of which
+  # parts are in <literal> and which not. The latter get processed by the
+  # function above.
+
+  for (;;)
+    {
+    if ($inliteral)
+      {
+      if (/^(.*?)<\/literal>(.*)$/)
+        {
+        print $1;
+        print "\"" if $ascii;
+        print "</literal>";
+        $inliteral = 0;
+        $_ = "$2\n";
+        }
+      else
+        {
+        print;
+        last;
+        }
+      }
+
+    # Not in literal state
+
+    else
+      {
+      if (/^(.*?)<literal>(.*)$/)
+        {
+        print &process($1);
+        print "<literal>";
+        print "\"" if $ascii;
+        $inliteral = 1;
+        $_ = "$2\n";
+        }
+      else
+        {
+        print &process($_);
+        last;
+        }
+      }
+    }    # Loop for different parts of one line
+  }      # Loop for multiple lines
+
+# End
diff --git a/doc/doc-docbook/TidyHTML-filter b/doc/doc-docbook/TidyHTML-filter
new file mode 100755 (executable)
index 0000000..f23a9a7
--- /dev/null
@@ -0,0 +1,79 @@
+#! /usr/bin/perl
+
+# $Cambridge: exim/doc/doc-docbook/TidyHTML-filter,v 1.1 2005/06/16 10:32:31 ph10 Exp $
+
+# Script to tidy up the filter HTML file that is generated by xmlto. The
+# following changes are made:
+#
+# 1. Split very long lines.
+# 2. Create reverse links from chapter and section titles back to the TOC.
+
+
+$tocref = 1;
+
+# Read in the filter.html file.
+
+open(IN, "filter.html") || die "Failed to open filter.html for reading: $!\n";
+@text = <IN>;
+close(IN);
+
+# Insert a newline after every > because the whole toc is generated as one
+# humungous line that is hard to check. Then split the lines so that each one
+# is a separate element in the vector.
+
+foreach $line (@text) { $line =~ s/>\s*/>\n/g; }
+for ($i = 0; $i < scalar(@text); $i++)
+  { splice @text, $i, 1, (split /(?<=\n)/, $text[$i]); }
+
+# We want to create reverse links from each chapter and section title back to
+# the relevant place in the TOC. Scan the TOC for the relevant entries. Add
+# an id to each entry, and create tables that remember the new link ids. We
+# detect the start of the TOC by <div class="toc" and the end of the TOC by
+# <div class="chapter".
+
+# Skip to start of TOC
+
+for ($i = 0; $i < scalar(@text); $i++)
+  {
+  last if $text[$i] =~ /^<div class="toc"/;
+  }
+
+# Scan the TOC
+
+for (; $i < scalar(@text); $i++)
+  {
+  last if $text[$i] =~ /^<div class="chapter"/;
+  if ($text[$i] =~ /^<a href="(#[^"]+)">/)
+    {
+    my($ss) = $1;
+    my($id) = sprintf "%04d", $tocref++;
+    $text[$i] =~ s/<a/<a id="toc$id"/;
+    $backref{"$ss"} = "toc$id";
+    }
+  }
+
+# Scan remainder of the document
+
+for (; $i < scalar(@text); $i++)
+  {
+  if ($text[$i] =~ /^<h[23] /)
+    {
+    $i++;
+    if ($text[$i] =~ /^<a( xmlns="[^"]+")? id="([^"]+)">$/)
+      {
+      my($ref) = $backref{"#$2"};
+      $text[$i++] = "<a$1 href=\"#$ref\" id=\"$2\">\n";
+      my($temp) = $text[$i];
+      $text[$i] = $text[$i+1];
+      $text[++$i] = $temp;
+      }
+    }
+  }
+
+# Write out the revised file
+
+open(OUT, ">filter.html") || die "Failed to open filter.html for writing: $!\n";
+print OUT @text;
+close(OUT);
+
+# End
diff --git a/doc/doc-docbook/TidyHTML-spec b/doc/doc-docbook/TidyHTML-spec
new file mode 100755 (executable)
index 0000000..8459bcf
--- /dev/null
@@ -0,0 +1,139 @@
+#! /usr/bin/perl
+
+# $Cambridge: exim/doc/doc-docbook/TidyHTML-spec,v 1.1 2005/06/16 10:32:31 ph10 Exp $
+
+# Script to tidy up the spec HTML files that are generated by xmlto. The
+# following changes are made:
+#
+# 1. Tidy the index.html file by splitting the very long lines.
+# 2. Create reverse links from chapter and section titles back to the TOC.
+# 3. Tidy the ix01.html file - the actual index - by splitting long lines.
+# 4. Insert links from the letter divisions to the top of the Index.
+
+chdir "spec.html";
+
+$tocref = 1;
+
+# Read in the index.html file. It's really the TOC.
+
+open(IN, "index.html") || die "Failed to open index.html for reading: $!\n";
+@toc = <IN>;
+close(IN);
+
+# Insert a newline after every > because the whole toc is generated as one
+# humungous line that is hard to check. Then split the lines so that each one
+# is a separate element in the vector.
+
+foreach $line (@toc) { $line =~ s/>\s*/>\n/g; }
+for ($i = 0; $i < scalar(@toc); $i++)
+  { splice @toc, $i, 1, (split /(?<=\n)/, $toc[$i]); }
+
+# We want to create reverse links from each chapter and section title back to
+# the relevant place in the TOC. Scan the TOC for the relevant entries. Add
+# an id to each entry, and create tables that remember the file names and the
+# new link ids.
+
+foreach $line (@toc)
+  {
+  if ($line =~ /^<a href="((?:ch|ix)\d+\.html)(#[^"]+)?">/)
+    {
+    my($chix) = $1;
+    my($ss) = $2;
+    my($id) = sprintf "%04d", $tocref++;
+    $line =~ s/<a/<a id="toc$id"/;
+    $backref{"$chix$ss"} = "toc$id";
+    push @chlist, $chix;
+    }
+  }
+
+# Write out the modified index.html file.
+
+open (OUT, ">index.html") || die "Failed to open index.html for writing: $!\n";
+print OUT @toc;
+close(OUT);
+
+# Now scan each of the other page files and insert the reverse links.
+
+foreach $file (@chlist)
+  {
+  open(IN, "$file") || die "Failed to open $file for reading: $!\n";
+  @text = <IN>;
+  close(IN);
+
+  foreach $line (@text)
+    {
+    if ($line =~ /^(.*?)<a( xmlns="[^"]+")? id="([^"]+)"><\/a>(.+?)<\/h(.*)$/)
+      {
+      my($pre, $opt, $id, $title, $post) = ($1, $2, $3, $4, $5);
+
+      # Section reference
+      my($ref) = $backref{"$file#$id"};
+
+      # If not found, try for a chapter reference
+      $ref = $backref{"$file"} if !defined $ref;
+
+      # Adjust the line
+      $line = "$pre<a$opt href=\"index.html#$ref\" id=\"$id\">$title</a></h$post";
+      }
+    }
+
+  open(OUT, ">$file") || die "Failed to open $file for writing: $!\n";
+  print OUT @text;
+  close(OUT);
+  }
+
+# Now process the ix01.html file
+
+open(IN, "ix01.html") || die "Failed to open ix01.html for reading: $!\n";
+@index = <IN>;
+close(IN);
+
+# Insert a newline after every > because the whole index is generated as one
+# humungous line that is hard to check. Then split the lines so that each one
+# is a separate element in the vector.
+
+foreach $line (@index) { $line =~ s/>\s*/>\n/g; }
+for ($i = 0; $i < scalar(@index); $i++)
+  { splice @index, $i, 1, (split /(?<=\n)/, $index[$i]); }
+
+# We want to add a list of letters at the top of the index, and link back
+# to them from each letter heading. First find the index title and remember
+# where to insert the list of letters.
+
+for ($i = 0; $i < scalar(@index); $i++)
+  {
+  if ($index[$i] =~ /^<\/h2>$/)
+    {
+    $listindex = $i;
+    last;
+    }
+  }
+
+# Now scan through for the letter headings and build the cross references,
+# while also building up the list to insert.
+
+$list = "<h4>\n";
+for (; $i < scalar(@index); $i++)
+  {
+  if ($index[$i] =~ /^(.)<\/h3>$/)
+    {
+    $letter = $1;
+    $index[$i-1] =~ s/^/<a id="${letter}B" href="#${letter}T">/;
+    $index[$i] =~ s/$/<\/a>/;
+    $list .= "<a id=\"${letter}T\" href=\"#${letter}B\"> $letter</a>\n";
+    }
+  }
+
+# Now we know which letters we have, we can insert the list.
+
+$list .= "</h4>\n";
+splice @index, $listindex, 0, $list;
+
+# Write out the modified index.html file.
+
+open (OUT, ">ix01.html") || die "Failed to open ix01.html for writing: $!\n";
+print OUT @index;
+close(OUT);
+
+
+# End
diff --git a/doc/doc-docbook/Tidytxt b/doc/doc-docbook/Tidytxt
new file mode 100755 (executable)
index 0000000..02bf9db
--- /dev/null
@@ -0,0 +1,21 @@
+#! /usr/bin/perl
+
+# $Cambridge: exim/doc/doc-docbook/Tidytxt,v 1.1 2005/06/16 10:32:31 ph10 Exp $
+
+# Script to tidy up the output of w3m when it makes a text file. We convert
+# sequences of blank lines into a single blank line.
+
+$blanks = 0;
+while (<>)
+  {
+  if (/^\s*$/)
+    {
+    $blanks++;
+    next;
+    }
+  print "\n" if $blanks > 0;
+  $blanks = 0;
+  print;
+  }
+
+# End
diff --git a/doc/doc-docbook/filter.ascd b/doc/doc-docbook/filter.ascd
new file mode 100644 (file)
index 0000000..8fd9c7e
--- /dev/null
@@ -0,0 +1,1759 @@
+///
+$Cambridge: exim/doc/doc-docbook/filter.ascd,v 1.1 2005/06/16 10:32:31 ph10 Exp $
+
+This file contains the Asciidoc source for the document that describes Exim's
+filtering facilities from a user's point of view. See the file AdMarkup.txt for
+an explanation of the markup that is used. It is more or less standard
+Asciidoc, but with a few changes and additions.
+///
+
+
+///
+This preliminary stuff creates a <bookinfo> entry in the XML. This is removed
+when creating the PostScript/PDF output, because we do not want a full-blown
+title page created for those versions. The stylesheet fudges up a title line to
+replace the text "Table of contents". However, for the other forms of output,
+the <bookinfo> element is retained and used.
+///
+
+Exim's interfaces to mail filtering
+===================================
+:author:          Philip Hazel
+:copyright:       University of Cambridge
+:cpyear:          2005
+:date:            13 May 2005
+:doctitleabbrev:  Exim filtering
+:revision:        4.50
+
+
+//////////////////////////////////////////////////////////////////////////////
+***WARNING*** Do not put anything, not even a titleabbrev setting, before
+the first chapter (luckily it does not need one) because if you do, AsciiDoc
+creates an empty <preface> element, which we do not want.
+//////////////////////////////////////////////////////////////////////////////
+
+
+Forwarding and filtering in Exim
+--------------------------------
+
+This document describes the user interfaces to Exim's in-built mail filtering
+facilities, and is copyright (C) University of Cambridge 2005. It corresponds
+to Exim version 4.50.
+
+
+
+Introduction
+~~~~~~~~~~~~
+Most Unix mail transfer agents (programs that deliver mail) permit individual
+users to specify automatic forwarding of their mail, usually by placing a list
+of forwarding addresses in a file called '.forward' in their home directories.
+Exim extends this facility by allowing the forwarding instructions to be a set
+of rules rather than just a list of addresses, in effect providing ``'.forward'
+with conditions''. Operating the set of rules is called 'filtering', and the
+file that contains them is called a 'filter file'.
+
+Exim supports two different kinds of filter file. An 'Exim filter' contains
+instructions in a format that is unique to Exim. A 'Sieve filter' contains
+instructions in the Sieve format that is defined by RFC 3028. As this is a
+standard format, Sieve filter files may already be familiar to some users.
+Sieve files should also be portable between different environments. However,
+the Exim filtering facility contains more features (such as variable
+expansion), and better integration with the host environment (such as the use
+of external processes and pipes).
+
+The choice of which kind of filter to use can be left to the end-user, provided
+that the system administrator has configured Exim appropriately for both kinds
+of filter. However, if interoperability is important, Sieve is the only
+choice.
+
+The ability to use filtering or traditional forwarding has to be enabled by the
+system administrator, and some of the individual facilities can be separately
+enabled or disabled. A local document should be provided to describe exactly
+what has been enabled. In the absence of this, consult your system
+administrator.
+
+This document describes how to use a filter file and the format of its
+contents. It is intended for use by end-users. Both Sieve filters and Exim
+filters are covered. However, for Sieve filters, only issues that relate to the
+Exim implementation are discussed, since Sieve itself is described elsewhere.
+
+The contents of traditional '.forward' files are not described here. They
+normally contain just a list of addresses, file names, or pipe commands,
+separated by commas or newlines, but other types of item are also available.
+The full details can be found in the chapter on the ^redirect^ router in the
+Exim specification, which also describes how the system administrator can set
+up and control the use of filtering.
+
+
+
+Filter operation
+~~~~~~~~~~~~~~~~
+It is important to realize that, in Exim, no deliveries are actually made while
+a filter or traditional '.forward' file is being processed. Running a filter
+or processing a traditional '.forward' file sets up future delivery
+operations, but does not carry them out.
+
+The result of filter or '.forward' file processing is a list of destinations
+to which a message should be delivered. The deliveries themselves take place
+later, along with all other deliveries for the message. This means that it is
+not possible to test for successful deliveries while filtering. It also means
+that any duplicate addresses that are generated are dropped, because Exim never
+delivers the same message to the same address more than once.
+
+
+
+
+[[SECTtesting]]
+Testing a new filter file
+~~~~~~~~~~~~~~~~~~~~~~~~~
+Filter files, especially the more complicated ones, should always be tested, as
+it is easy to make mistakes. Exim provides a facility for preliminary testing
+of a filter file before installing it. This tests the syntax of the file and
+its basic operation, and can also be used with traditional '.forward' files.
+
+Because a filter can do tests on the content of messages, a test message is
+required. Suppose you have a new filter file called 'myfilter' and a test
+message called 'test-message'. Assuming that Exim is installed with the
+conventional path name '/usr/sbin/sendmail' (some operating systems use
+'/usr/lib/sendmail'), the following command can be used:
+
+  /usr/sbin/sendmail -bf myfilter <test-message
+
+The %-bf% option tells Exim that the following item on the command line is the
+name of a filter file that is to be tested. There is also a %-bF% option,
+which is similar, but which is used for testing system filter files, as opposed
+to user filter files, and which is therefore of use only to the system
+administrator.
+
+The test message is supplied on the standard input. If there are no
+message-dependent tests in the filter, an empty file ('/dev/null') can be
+used. A supplied message must start with header lines or the ``From'' message
+separator line which is found in many multi-message folder files. Note that
+blank lines at the start terminate the header lines. A warning is given if no
+header lines are read.
+
+The result of running this command, provided no errors are detected in the
+filter file, is a list of the actions that Exim would try to take if presented
+with the message for real.
+For example, for an Exim filter, the output
+
+  Deliver message to: gulliver@lilliput.fict.example
+  Save message to: /home/lemuel/mail/archive
+
+means that one copy of the message would be sent to
+'gulliver@lilliput.fict.example', and another would be added to the file
+_/home/lemuel/mail/archive_, if all went well.
+
+The actions themselves are not attempted while testing a filter file in this
+way; there is no check, for example, that any forwarding addresses are valid.
+For an Exim filter,
+if you want to know why a particular action is being taken, add the %-v%
+option to the command. This causes Exim to output the results of any
+conditional tests and to indent its output according to the depth of nesting of
+^if^ commands. Further additional output from a filter test can be generated
+by the ^testprint^ command, which is described below.
+
+When Exim is outputting a list of the actions it would take, if any text
+strings are included in the output, non-printing characters therein are
+converted to escape sequences. In particular, if any text string contains a
+newline character, this is shown as ``\n'' in the testing output.
+
+When testing a filter in this way, Exim makes up an ``envelope'' for the message.
+The recipient is by default the user running the command, and so is the sender,
+but the command can be run with the %-f% option to supply a different sender.
+For example,
+
+...
+/usr/sbin/sendmail -bf myfilter \
+   -f islington@never.where <test-message
+...
+
+Alternatively, if the %-f% option is not used, but the first line of the
+supplied message is a ``From'' separator from a message folder file (not the same
+thing as a 'From:' header line), the sender is taken from there. If %-f% is
+present, the contents of any ``From'' line are ignored.
+
+The ``return path'' is the same as the envelope sender, unless the message
+contains a 'Return-path:' header, in which case it is taken from there. You
+need not worry about any of this unless you want to test out features of a
+filter file that rely on the sender address or the return path.
+
+It is possible to change the envelope recipient by specifying further options.
+The %-bfd% option changes the domain of the recipient address, while the
+%-bfl% option changes the ``local part'', that is, the part before the @ sign.
+An adviser could make use of these to test someone else's filter file.
+
+The %-bfp% and %-bfs% options specify the prefix or suffix for the local part.
+These are relevant only when support for multiple personal mailboxes is
+implemented; see the description in section <<SECTmbox>> below.
+
+
+Installing a filter file
+~~~~~~~~~~~~~~~~~~~~~~~~
+A filter file is normally installed under the name '.forward' in your home
+directory -- it is distinguished from a conventional '.forward' file by its
+first line (described below). However, the file name is configurable, and some
+system administrators may choose to use some different name or location for
+filter files.
+
+
+Testing an installed filter file
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+Testing a filter file before installation cannot find every potential problem;
+for example, it does not actually run commands to which messages are piped.
+Some ``live'' tests should therefore also be done once a filter is installed.
+
+If at all possible, test your filter file by sending messages from some other
+account. If you send a message to yourself from the filtered account, and
+delivery fails, the error message will be sent back to the same account, which
+may cause another delivery failure. It won't cause an infinite sequence of such
+messages, because delivery failure messages do not themselves generate further
+messages. However, it does mean that the failure won't be returned to you, and
+also that the postmaster will have to investigate the stuck message.
+
+If you have to test an Exim filter from the same account, a sensible precaution
+is to include the line
+
+  if error_message then finish endif
+
+as the first filter command, at least while testing. This causes filtering to
+be abandoned for a delivery failure message, and since no destinations are
+generated, the message goes on to be delivered to the original address. Unless
+there is a good reason for not doing so, it is recommended that the above test
+be left in all Exim filter files.
+(This does not apply to Sieve files.)
+
+
+
+Details of filtering commands
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+The filtering commands for Sieve and Exim filters are completely different in
+syntax and semantics. The Sieve mechanism is defined in RFC 3028; in the next
+chapter we describe how it is integrated into Exim. The subsequent chapter
+covers Exim filtering commands in detail.
+
+
+
+[[CHAPsievefilter]]
+Sieve filter files
+------------------
+The code for Sieve filtering in Exim was contributed by Michael Haardt, and
+most of the content of this chapter is taken from the notes he provided. Since
+Sieve is a extensible language, it is important to understand ``Sieve'' in this
+context as ``the specific implementation of Sieve for Exim''.
+
+This chapter does not contain a description of Sieve, since that can be found
+in RFC 3028, which should be read in conjunction with these notes.
+
+The Exim Sieve implementation offers the core as defined by RFC 3028,
+comparison tests, the *copy*, *envelope*, *fileinto*, and *vacation*
+extensions, but not the *reject* extension. Exim does not support message
+delivery notifications (MDNs), so adding it just to the Sieve filter (as
+required for *reject*) makes little sense.
+
+In order for Sieve to work properly in Exim, the system administrator needs to
+make some adjustments to the Exim configuration. These are described in the
+chapter on the ^redirect^ router in the full Exim specification.
+
+
+Recognition of Sieve filters
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+A filter file is interpreted as a Sieve filter if its first line is
+
+  # Sieve filter
+
+This is what distinguishes it from a conventional '.forward' file or an Exim
+filter file.
+
+
+
+Saving to specified folders
+~~~~~~~~~~~~~~~~~~~~~~~~~~~
+If the system administrator has set things up as suggested in the Exim
+specification, and you use *keep* or *fileinto* to save a mail into a
+folder, absolute files are stored where specified, relative files are stored
+relative to $home$, and *inbox* goes to the standard mailbox location.
+
+
+
+Strings containing header names
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+RFC 3028 does not specify what happens if a string denoting a header field does
+not contain a valid header name, for example, it contains a colon. This
+implementation generates an error instead of ignoring the header field in order
+to ease script debugging, which fits in the common picture of Sieve.
+
+
+
+Exists test with empty list of headers
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+The *exists* test succeeds only if all specified headers exist. RFC 3028
+does not explicitly specify what happens on an empty list of headers. This
+implementation evaluates that condition as true, interpreting the RFC in a
+strict sense.
+
+
+
+Header test with invalid MIME encoding in header
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+Some MUAs process invalid base64 encoded data, generating junk.
+Others ignore junk after seeing an equal sign in base64 encoded data.
+RFC 2047 does not specify how to react in this case, other than stating
+that a client must not forbid to process a message for that reason.
+RFC 2045 specifies that invalid data should be ignored (apparently
+looking at end of line characters). It also specifies that invalid data
+may lead to rejecting messages containing them (and there it appears to
+talk about true encoding violations), which is a clear contradiction to
+ignoring them.
+
+RFC 3028 does not specify how to process incorrect MIME words.
+This implementation treats them literally, as it does if the word is
+correct but its character set cannot be converted to UTF-8.
+
+
+
+Address test for multiple addresses per header
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+A header may contain multiple addresses. RFC 3028 does not explicitly
+specify how to deal with them, but since the address test checks if
+anything matches anything else, matching one address suffices to
+satisfy the condition. That makes it impossible to test if a header
+contains a certain set of addresses and no more, but it is more logical
+than letting the test fail if the header contains an additional address
+besides the one the test checks for.
+
+
+
+Semantics of keep
+~~~~~~~~~~~~~~~~~
+The *keep* command is equivalent to
+
+  fileinto "inbox";
+
+It saves the message and resets the implicit keep flag. It does not set the
+implicit keep flag; there is no command to set it once it has been reset.
+
+
+
+Semantics of fileinto
+~~~~~~~~~~~~~~~~~~~~~
+RFC 3028 does not specify whether %fileinto% should try to create a mail folder
+if it does not exist. This implementation allows the sysadmin to configure that
+aspect using the ^appendfile^ transport options %create_directory%,
+%create_file%, and %file_must_exist%. See the ^appendfile^ transport in
+the Exim specification for details.
+
+
+
+Semantics of redirect
+~~~~~~~~~~~~~~~~~~~~~
+Sieve scripts are supposed to be interoperable between servers, so this
+implementation does not allow mail to be redirected to unqualified addresses,
+because the domain would depend on the system being used. On systems with
+virtual mail domains, the default domain is probably not what the user expects
+it to be.
+
+
+
+String arguments
+~~~~~~~~~~~~~~~~
+There has been confusion if the string arguments to *require* are to be
+matched case-sensitively or not. This implementation matches them with
+the match type ^:is^ (default, see section 2.7.1) and the comparator
+^i;ascii-casemap^ (default, see section 2.7.3). The RFC defines the
+command defaults clearly, so any different implementations violate RFC
+3028. The same is valid for comparator names, also specified as strings.
+
+
+
+Number units
+~~~~~~~~~~~~
+There is a mistake in RFC 3028: the suffix G denotes gibi-, not tebibyte.
+The mistake is obvious, because RFC 3028 specifies G to denote 2^30
+(which is gibi, not tebi), and that is what this implementation uses as
+scaling factor for the suffix G.
+
+
+
+RFC compliance
+~~~~~~~~~~~~~~
+Exim requires the first line of a Sieve filter to be
+
+  # Sieve filter
+
+Of course the RFC does not specify that line. Do not expect examples to work
+without adding it, though.
+
+RFC 3028 requires the use of CRLF to terminate a line.
+The rationale was that CRLF is universally used in network protocols
+to mark the end of the line. This implementation does not embed Sieve
+in a network protocol, but uses Sieve scripts as part of the Exim MTA.
+Since all parts of Exim use LF as newline character, this implementation
+does, too, by default, though the system administrator may choose (at Exim
+compile time) to use CRLF instead.
+
+Exim violates RFC 2822, section 3.6.8, by accepting 8-bit header names, so
+this implementation repeats this violation to stay consistent with Exim.
+This is in preparation to UTF-8 data.
+
+Sieve scripts cannot contain NUL characters in strings, but mail
+headers could contain MIME encoded NUL characters, which could never
+be matched by Sieve scripts using exact comparisons.  For that reason,
+this implementation extends the Sieve quoted string syntax with \0
+to describe a NUL character, violating \0 being the same as 0 in
+RFC 3028.  Even without using \0, the following tests are all true in
+this implementation. Implementations that use C-style strings will only
+evaluate the first test as true.
+
+  Subject: =?iso-8859-1?q?abc=00def
+
+  header :contains "Subject" ["abc"]
+  header :contains "Subject" ["def"]
+  header :matches "Subject" ["abc?def"]
+
+Note that by considering Sieve to be a MUA, RFC 2047 can be interpreted
+in a way that NUL characters truncating strings is allowed for Sieve
+implementations, although not recommended. It is further allowed to use
+encoded NUL characters in headers, but that's not recommended either.
+The above example shows why.
+
+RFC 3028 states that if an implementation fails to convert a character
+set to UTF-8, two strings cannot be equal if one contains octets greater
+than 127. Assuming that all unknown character sets are one-byte character
+sets with the lower 128 octets being US-ASCII is not sound, so this
+implementation violates RFC 3028 and treats such MIME words literally.
+That way at least something could be matched.
+
+The folder specified by *fileinto* must not contain the character
+sequence ``..'' to avoid security problems. RFC 3028 does not specify the
+syntax of folders apart from *keep* being equivalent to
+
+  fileinto "INBOX";
+
+This implementation uses _inbox_ instead.
+
+Sieve script errors currently cause messages to be silently filed into
+_inbox_.  RFC 3028 requires that the user is notified of that condition.
+This may be implemented in future by adding a header line to mails that
+are filed into _inbox_ due to an error in the filter.
+
+
+
+[[CHAPeximfilter]]
+Exim filter files
+-----------------
+This chapter contains a full description of the contents of Exim filter files.
+
+
+Format of Exim filter files
+~~~~~~~~~~~~~~~~~~~~~~~~~~~
+Apart from leading white space, the first text in an Exim filter file must be
+
+  # Exim filter
+
+This is what distinguishes it from a conventional '.forward' file or a Sieve
+filter file. If the file does not have this initial line (or the equivalent for
+a Sieve filter), it is treated as a conventional '.forward' file, both when
+delivering mail and when using the %-bf% testing mechanism. The white space in
+the line is optional, and any capitalization may be used. Further text on the
+same line is treated as a comment. For example, you could have
+
+  #   Exim filter   <<== do not edit or remove this line!
+
+The remainder of the file is a sequence of filtering commands, which consist of
+keywords and data values. For example, in the command
+
+  deliver gulliver@lilliput.fict.example
+
+the keyword is `deliver` and the data value is
+`gulliver@lilliput.fict.example`. White space or line breaks separate the
+components of a command, except in the case of conditions for the ^if^ command,
+where round brackets (parentheses) also act as separators. Complete commands
+are separated from each other by white space or line breaks; there are no
+special terminators. Thus, several commands may appear on one line, or one
+command may be spread over a number of lines.
+
+If the character # follows a separator anywhere in a command, everything from
+# up to the next newline is ignored. This provides a way of including comments
+in a filter file.
+
+
+Data values in filter commands
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+There are two ways in which a data value can be input:
+
+- If the text contains no white space then it can be typed verbatim. However, if
+it is part of a condition, it must also be free of round brackets
+(parentheses), as these are used for grouping in conditions.
+
+- Otherwise, it must be enclosed in double quotation marks. In this case, the
+character \ (backslash) is treated as an ``escape character'' within the string,
+causing the following character or characters to be treated specially:
+
+&&&&
+`\n`   is replaced by a newline
+`\r`   is replaced by a carriage return
+`\t`   is replaced by a tab
+&&&&
+
+Backslash followed by up to three octal digits is replaced by the character
+specified by those digits, and \x followed by up to two hexadecimal digits is
+treated similarly. Backslash followed by any other character is replaced
+by the second character, so that in particular, \\" becomes " and \\ becomes
+\. A data item enclosed in double quotes can be continued onto the next line
+by ending the first line with a backslash. Any leading white space at the start
+of the continuation line is ignored.
+
+In addition to the escape character processing that occurs when strings are
+enclosed in quotes, most data values are also subject to 'string expansion'
+(as described in the next section), in which case the characters `\$` and `\`
+are also significant. This means that if a single backslash is actually
+required in such a string, and the string is also quoted, \\\\ has to be
+entered.
+
+The maximum permitted length of a data string, before expansion, is 1024
+characters.
+
+
+++++++++++++
+<?hard-pagebreak?>
+++++++++++++
+
+[[SECTfilterstringexpansion]]
+String expansion
+~~~~~~~~~~~~~~~~
+Most data values are expanded before use. Expansion consists of replacing
+substrings beginning with `\$` with other text. The full expansion facilities
+available in Exim are extensive. If you want to know everything that Exim can
+do with strings, you should consult the chapter on string expansion in the Exim
+documentation.
+
+In filter files, by far the most common use of string expansion is the
+substitution of the contents of a variable. For example, the substring
+
+  $reply_address
+
+is replaced by the address to which replies to the message should be sent. If
+such a variable name is followed by a letter or digit or underscore, it must be
+enclosed in curly brackets (braces), for example,
+
+  ${reply_address}
+
+If a `\$` character is actually required in an expanded string, it must be
+escaped with a backslash, and because backslash is also an escape character in
+quoted input strings, it must be doubled in that case. The following two
+examples illustrate two different ways of testing for a `\$` character in a
+message:
+
+  if $message_body contains \$ then ...
+  if $message_body contains "\\$" then ...
+
+You can prevent part of a string from being expanded by enclosing it between
+two occurrences of `\N`. For example,
+
+  if $message_body contains \N$$$$\N then ...
+
+tests for a run of four dollar characters.
+
+
+Some useful general variables
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+A complete list of the available variables is given in the Exim documentation.
+This shortened list contains the ones that are most likely to be useful in
+personal filter files:
+
+$body_linecount$: The number of lines in the body of the message.
+
+$body_zerocount$: The number of binary zero characters in the body of the
+message.
+
+
+$home$: In conventional configurations, this variable normally contains the
+user's home directory. The system administrator can, however, change this.
+
+$local_part$: The part of the email address that precedes the @ sign --
+normally the user's login name. If support for multiple personal mailboxes is
+enabled (see section <<SECTmbox>> below) and a prefix or suffix for the local
+part was recognized, it is removed from the string in this variable.
+
+$local_part_prefix$: If support for multiple personal mailboxes is enabled
+(see section <<SECTmbox>> below), and a local part prefix was recognized,
+this variable contains the prefix. Otherwise it contains an empty string.
+
+$local_part_suffix$: If support for multiple personal mailboxes is enabled
+(see section <<SECTmbox>> below), and a local part suffix was recognized,
+this variable contains the suffix. Otherwise it contains an empty string.
+
+$message_body$: The initial portion of the body of the message. By default,
+up to 500 characters are read into this variable, but the system administrator
+can configure this to some other value. Newlines in the body are converted into
+single spaces.
+
+$message_body_end$: The final portion of the body of the message, formatted
+and limited in the same way as $message_body$.
+
+$message_body_size$: The size of the body of the message, in bytes.
+
+$message_headers$: The header lines of the message, concatenated into a
+single string, with newline characters between them.
+
+$message_id$: The message's local identification string, which is unique for
+each message handled by a single host.
+
+$message_size$: The size of the entire message, in bytes.
+
+$original_local_part$: When an address that arrived with the message is
+being processed, this contains the same value as the variable $local_part$.
+However, if an address generated by an alias, forward, or filter file is being
+processed, this variable contains the local part of the original address.
+
+$reply_address$: The contents of the 'Reply-to:' header, if the message
+has one; otherwise the contents of the 'From:' header. It is the address to
+which normal replies to the message should be sent.
+
+$return_path$: The return path -- that is, the sender field that will be
+transmitted as part of the message's envelope if the message is sent to another
+host. This is the address to which delivery errors are sent. In many cases,
+this variable has the same value as $sender_address$, but if, for example,
+an incoming message to a mailing list has been expanded, $return_path$ may
+have been changed to contain the address of the list maintainer.
+
+$sender_address$: The sender address that was received in the envelope of
+the message. This is not necessarily the same as the contents of the 'From:'
+or 'Sender:' header lines. For delivery error messages (``bounce messages'')
+there is no sender address, and this variable is empty.
+
+$tod_full$: A full version of the time and date, for example: Wed, 18 Oct
+1995 09:51:40 +0100. The timezone is always given as a numerical offset from
+GMT.
+
+$tod_log$: The time and date in the format used for writing Exim's log files,
+without the timezone, for example: 1995-10-12 15:32:29.
+
+$tod_zone$: The local timezone offset, for example: +0100.
+
+
+
+[[SECTheadervariables]]
+Header variables
+~~~~~~~~~~~~~~~~
+There is a special set of expansion variables containing the header lines of
+the message being processed. These variables have names beginning with
+$header_$ followed by the name of the header line, terminated by a colon.
+For example,
+
+  $header_from:
+  $header_subject:
+
+The whole item, including the terminating colon, is replaced by the contents of
+the message header line. If there is more than one header line with the same
+name, their contents are concatenated. For header lines whose data consists of
+a list of addresses (for example, 'From:' and 'To:'), a comma and newline is
+inserted between each set of data. For all other header lines, just a newline
+is used.
+
+Leading and trailing white space is removed from header line data, and if there
+are any MIME ``words'' that are encoded as defined by RFC 2047 (because they
+contain non-ASCII characters), they are decoded and translated, if possible, to
+a local character set. Translation is attempted only on operating systems that
+have the ^^iconv()^^ function. This makes the header line look the same as it
+would when displayed by an MUA. The default character set is ISO-8859-1, but
+this can be changed by means of the ^headers^ command (see below).
+
+If you want to see the actual characters that make up a header line, you can
+specify $rheader_$ instead of $header_$. This inserts the ``raw''
+header line, unmodified.
+
+There is also an intermediate form, requested by $bheader_$, which removes
+leading and trailing space and decodes MIME ``words'', but does not do any
+character translation. If an attempt to decode what looks superficially like a
+MIME ``word'' fails, the raw string is returned. If decoding produces a binary
+zero character, it is replaced by a question mark.
+
+The capitalization of the name following $header_$ is not significant.
+Because any printing character except colon may appear in the name of a
+message's header (this is a requirement of RFC 2822, the document that
+describes the format of a mail message) curly brackets must 'not' be used in
+this case, as they will be taken as part of the header name. Two shortcuts are
+allowed in naming header variables:
+
+- The initiating $header_$, $rheader_$, or $bheader_$ can be
+abbreviated to $h_$, $rh_$, or $bh_$, respectively.
+
+- The terminating colon can be omitted if the next character is white space. The
+white space character is retained in the expanded string. However, this is not
+recommended, because it makes it easy to forget the colon when it really is
+needed.
+
+If the message does not contain a header of the given name, an empty string is
+substituted. Thus it is important to spell the names of headers correctly. Do
+not use $header_Reply_to$ when you really mean $header_Reply-to$.
+
+
+User variables
+~~~~~~~~~~~~~~
+There are ten user variables with names $n0$ -- $n9$ that can be
+incremented by the ^add^ command (see section <<SECTadd>>). These can be used
+for ``scoring'' messages in various ways. If Exim is configured to run a
+``system filter'' on every message, the values left in these variables are
+copied into the variables $sn0$ -- $sn9$ at the end of the system filter, thus
+making them available to users' filter files. How these values are used is
+entirely up to the individual installation.
+
+
+Current directory
+~~~~~~~~~~~~~~~~~
+The contents of your filter file should not make any assumptions about the
+current directory. It is best to use absolute paths for file names; you
+can normally make use of the $home$ variable to refer to your home directory.
+The ^save^ command automatically inserts $home$ at the start of non-absolute
+paths.
+
+
+
+
+[[SECTsigdel]]
+Significant deliveries
+~~~~~~~~~~~~~~~~~~~~~~
+When in the course of delivery a message is processed by a filter file, what
+happens next, that is, after the filter file has been processed, depends on
+whether or not the filter sets up any 'significant deliveries'. If at least
+one significant delivery is set up, the filter is considered to have handled
+the entire delivery arrangements for the current address, and no further
+processing of the address takes place. If, however, no significant deliveries
+are set up, Exim continues processing the current address as if there were no
+filter file, and typically sets up a delivery of a copy of the message into a
+local mailbox. In particular, this happens in the special case of a filter file
+containing only comments.
+
+The delivery commands ^deliver^, ^save^, and ^pipe^ are by default
+significant. However, if such a command is preceded by the word ^unseen^, its
+delivery is not considered to be significant. In contrast, other commands such
+as ^mail^ and ^vacation^ do not set up significant deliveries unless
+preceded by the word ^seen^.
+
+The following example commands set up significant deliveries:
+
+  deliver jack@beanstalk.example
+  pipe $home/bin/mymailscript
+  seen mail subject "message discarded"
+  seen finish
+
+The following example commands do not set up significant deliveries:
+
+  unseen deliver jack@beanstalk.example
+  unseen pipe $home/bin/mymailscript
+  mail subject "message discarded"
+  finish
+
+
+
+
+Filter commands
+~~~~~~~~~~~~~~~
+The filter commands that are described in subsequent sections are listed
+below, with the section in which they are described in brackets:
+
+[frame="none"]
+`-------------`-----------------------------------------------
+^add^         ~~increment a user variable (section <<SECTadd>>)
+^deliver^     ~~deliver to an email address (section <<SECTdeliver>>)
+^fail^        ~~force delivery failure (sysadmin use) (section <<SECTfail>>)
+^finish^      ~~end processing (section <<SECTfinish>>)
+^freeze^      ~~freeze message (sysadmin use) (section <<SECTfreeze>>)
+^headers^     ~~set the header character set (section <<SECTheaders>>)
+^if^          ~~test condition(s) (section <<SECTif>>)
+^logfile^     ~~define log file (section <<SECTlog>>)
+^logwrite^    ~~write to log file (section <<SECTlog>>)
+^mail^        ~~send a reply message (section <<SECTmail>>)
+^pipe^        ~~pipe to a command (section <<SECTpipe>>)
+^save^        ~~save to a file (section <<SECTsave>>)
+^testprint^   ~~print while testing (section <<SECTtestprint>>)
+^vacation^    ~~tailored form of ^mail^ (section <<SECTmail>>)
+--------------------------------------------------------------
+
+The ^headers^ command has additional parameters that can be used only in a
+system filter. The ^fail^ and ^freeze^ commands are available only when
+Exim's filtering facilities are being used as a system filter, and are
+therefore usable only by the system administrator and not by ordinary users.
+They are mentioned only briefly in this document; for more information, see the
+main Exim specification.
+
+
+
+[[SECTadd]]
+The add command
+~~~~~~~~~~~~~~~
+&&&
+`     add `<'number'>` to `<'user variable'>
+`e.g. add 2 to n3`
+&&&
+
+There are 10 user variables of this type, with names $n0$ -- $n9$. Their
+values can be obtained by the normal expansion syntax (for example $n3$) in
+other commands. At the start of filtering, these variables all contain zero.
+Both arguments of the ^add^ command are expanded before use, making it
+possible to add variables to each other. Subtraction can be obtained by adding
+negative numbers.
+
+
+
+[[SECTdeliver]]
+The deliver command
+~~~~~~~~~~~~~~~~~~~
+
+&&&
+`     deliver` <'mail address'>
+`e.g. deliver "Dr Livingstone <David@somewhere.africa.example>"`
+&&&
+
+This command provides a forwarding operation. The delivery that it sets up is
+significant unless the command is preceded by ^unseen^ (see section
+<<SECTsigdel>>). The message is sent on to the given address, exactly as
+happens if the address had appeared in a traditional '.forward' file. If you
+want to deliver the message to a number of different addresses, you can use
+more than one ^deliver^ command (each one may have only one address). However,
+duplicate addresses are discarded.
+
+To deliver a copy of the message to your normal mailbox, your login name can be
+given as the address. Once an address has been processed by the filtering
+mechanism, an identical generated address will not be so processed again, so
+doing this does not cause a loop.
+
+However, if you have a mail alias, you should 'not' refer to it here. For
+example, if the mail address 'L.Gulliver' is aliased to 'lg303' then all
+references in Gulliver's '.forward' file should be to 'lg303'. A reference
+to the alias will not work for messages that are addressed to that alias,
+since, like '.forward' file processing, aliasing is performed only once on an
+address, in order to avoid looping.
+
+Following the new address, an optional second address, preceded by
+^errors_to^ may appear. This changes the address to which delivery errors on
+the forwarded message will be sent. Instead of going to the message's original
+sender, they go to this new address. For ordinary users, the only value that is
+permitted for this address is the user whose filter file is being processed.
+For example, the user 'lg303' whose mailbox is in the domain
+'lilliput.example' could have a filter file that contains
+
+  deliver jon@elsewhere.example errors_to lg303@lilliput.example
+
+Clearly, using this feature makes sense only in situations where not all
+messages are being forwarded. In particular, bounce messages must not be
+forwarded in this way, as this is likely to create a mail loop if something
+goes wrong.
+
+
+
+[[SECTsave]]
+The save command
+~~~~~~~~~~~~~~~~
+&&&
+`     save `<'file name'>
+`e.g. save $home/mail/bookfolder`
+&&&
+
+This command specifies that a copy of the message is to be appended to the
+given file (that is, the file is to be used as a mail folder). The delivery
+that ^save^ sets up is significant unless the command is preceded by
+^unseen^ (see section <<SECTsigdel>>).
+
+More than one ^save^ command may be obeyed; each one causes a copy of the
+message to be written to its argument file, provided they are different
+(duplicate ^save^ commands are ignored).
+
+If the file name does not start with a / character, the contents of the
+$home$ variable are prepended, unless it is empty. In conventional
+configurations, this variable is normally set in a user filter to the user's
+home directory, but the system administrator may set it to some other path. In
+some configurations, $home$ may be unset, in which case a non-absolute path
+name may be generated. Such configurations convert this to an absolute path
+when the delivery takes place. In a system filter, $home$ is never set.
+
+The user must of course have permission to write to the file, and the writing
+of the file takes place in a process that is running as the user, under the
+user's primary group. Any secondary groups to which the user may belong are not
+normally taken into account, though the system administrator can configure Exim
+to set them up. In addition, the ability to use this command at all is
+controlled by the system administrator -- it may be forbidden on some systems.
+
+An optional mode value may be given after the file name. The value for the mode
+is interpreted as an octal number, even if it does not begin with a zero. For
+example:
+
+  save /some/folder 640
+
+This makes it possible for users to override the system-wide mode setting for
+file deliveries, which is normally 600. If an existing file does not have the
+correct mode, it is changed.
+
+An alternative form of delivery may be enabled on your system, in which each
+message is delivered into a new file in a given directory. If this is the case,
+this functionality can be requested by giving the directory name terminated by
+a slash after the ^save^ command, for example
+
+  save separated/messages/
+
+There are several different formats for such deliveries; check with your system
+administrator or local documentation to find out which (if any) are available
+on your system. If this functionality is not enabled, the use of a path name
+ending in a slash causes an error.
+
+
+
+[[SECTpipe]]
+The pipe command
+~~~~~~~~~~~~~~~~
+&&&
+`     pipe `<'command'>
+`e.g. pipe "$home/bin/countmail $sender_address"`
+&&&
+
+This command specifies that the message is to be delivered to the specified
+command using a pipe. The delivery that it sets up is significant unless the
+command is preceded by ^unseen^ (see section <<SECTsigdel>>). Remember,
+however, that no deliveries are done while the filter is being processed. All
+deliveries happen later on. Therefore, the result of running the pipe is not
+available to the filter.
+
+When the deliveries are done, a separate process is run, and a copy of the
+message is passed on its standard input. The process runs as the user, under
+the user's primary group. Any secondary groups to which the user may belong are
+not normally taken into account, though the system administrator can configure
+Exim to set them up. More than one ^pipe^ command may appear; each one causes
+a copy of the message to be written to its argument pipe, provided they are
+different (duplicate ^pipe^ commands are ignored).
+
+When the time comes to transport the message,
+the command supplied to ^pipe^ is split up by Exim into a command name and a
+number of arguments. These are delimited by white space except for arguments
+enclosed in double quotes, in which case backslash is interpreted as an escape,
+or in single quotes, in which case no escaping is recognized. Note that as the
+whole command is normally supplied in double quotes, a second level of quoting
+is required for internal double quotes. For example:
+
+  pipe "$home/myscript \"size is $message_size\""
+
+String expansion is performed on the separate components after the line has
+been split up, and the command is then run directly by Exim; it is not run
+under a shell. Therefore, substitution cannot change the number of arguments,
+nor can quotes, backslashes or other shell metacharacters in variables cause
+confusion.
+
+Documentation for some programs that are normally run via this kind of pipe
+often suggest that the command should start with
+
+  IFS=" "
+
+This is a shell command, and should 'not' be present in Exim filter files,
+since it does not normally run the command under a shell.
+
+However, there is an option that the administrator can set to cause a shell to
+be used. In this case, the entire command is expanded as a single string and
+passed to the shell for interpretation. It is recommended that this be avoided
+if at all possible, since it can lead to problems when inserted variables
+contain shell metacharacters.
+
+The default PATH set up for the command is determined by the system
+administrator, usually containing at least _/usr/bin_ so that common commands
+are available without having to specify an absolute file name. However, it is
+possible for the system administrator to restrict the pipe facility so that the
+command name must not contain any / characters, and must be found in one of the
+directories in the configured PATH. It is also possible for the system
+administrator to lock out the use of the ^pipe^ command altogether.
+
+When the command is run, a number of environment variables are set up. The
+complete list for pipe deliveries may be found in the Exim reference manual.
+Those that may be useful for pipe deliveries from user filter files are:
+
+&&&
+`DOMAIN            `   the domain of the address
+`HOME              `   your home directory
+`LOCAL_PART        `   see below
+`LOCAL_PART_PREFIX `   see below
+`LOCAL_PART_SUFFIX `   see below
+`LOGNAME           `   your login name
+`MESSAGE_ID        `   the unique id of the message
+`PATH              `   the command search path
+`RECIPIENT         `   the complete recipient address
+`SENDER            `   the sender of the message
+`SHELL             `   `/bin/sh`
+`USER              `   see below
+&&&
+
+LOCAL_PART, LOGNAME, and USER are all set to the same value,
+namely, your login id. LOCAL_PART_PREFIX and LOCAL_PART_SUFFIX may
+be set if Exim is configured to recognize prefixes or suffixes in the local
+parts of addresses. For example, a message addressed to
+'pat-suf2@domain.example' may cause the filter for user 'pat' to be run. If
+this sets up a pipe delivery, LOCAL_PART_SUFFIX is `-suf2` when the
+pipe command runs. The system administrator has to configure Exim specially for
+this feature to be available.
+
+If you run a command that is a shell script, be very careful in your use of
+data from the incoming message in the commands in your script. RFC 2822 is very
+generous in the characters that are permitted to appear in mail addresses, and
+in particular, an address may begin with a vertical bar or a slash. For this
+reason you should always use quotes round any arguments that involve data from
+the message, like this:
+
+  /some/command '$SENDER'
+
+so that inserted shell meta-characters do not cause unwanted effects.
+
+Remember that, as was explained earlier, the pipe command is not run at the
+time the filter file is interpreted. The filter just defines what deliveries
+are required for one particular addressee of a message. The deliveries
+themselves happen later, once Exim has decided everything that needs to be done
+for the message.
+
+A consequence of this is that you cannot inspect the return code from the pipe
+command from within the filter. Nevertheless, the code returned by the command
+is important, because Exim uses it to decide whether the delivery has succeeded
+or failed.
+
+The command should return a zero completion code if all has gone well. Most
+non-zero codes are treated by Exim as indicating a failure of the pipe. This is
+treated as a delivery failure, causing the message to be returned to its
+sender. However, there are some completion codes that are treated as temporary
+errors. The message remains on Exim's spool disk, and the delivery is tried
+again later, though it will ultimately time out if the delivery failures go on
+too long. The completion codes to which this applies can be specified by the
+system administrator; the default values are 73 and 75.
+
+The pipe command should not normally write anything to its standard output or
+standard error file descriptors. If it does, whatever is written is normally
+returned to the sender of the message as a delivery error, though this action
+can be varied by the system administrator.
+
+
+
+[[SECTmail]]
+Mail commands
+~~~~~~~~~~~~~
+There are two commands that cause the creation of a new mail message, neither
+of which count as a significant delivery unless the command is preceded by the
+word ^seen^ (see section <<SECTsigdel>>). This is a powerful facility, but it
+should be used with care, because of the danger of creating infinite sequences
+of messages. The system administrator can forbid the use of these commands
+altogether.
+
+To help prevent runaway message sequences, these commands have no effect when
+the incoming message is a bounce (delivery error) message, and messages sent by
+this means are treated as if they were reporting delivery errors. Thus, they
+should never themselves cause a bounce message to be returned. The basic
+mail-sending command is
+
+&&&
+`mail [to `<'address-list'>`]`
+`     [cc `<'address-list'>`]`
+`     [bcc `<'address-list'>`]`
+`     [from `<'address'>`]`
+`     [reply_to `<'address'>`]`
+`     [subject `<'text'>`]`
+`     [extra_headers `<'text'>`]`
+`     [text `<'text'>`]`
+`     [[expand] file `<'filename'>`]`
+`     [return message]`
+`     [log `<'log file name'>`]`
+`     [once `<'note file name'>`]`
+`     [once_repeat `<'time interval'>`]`
+
+`e.g. mail text "Your message about $h_subject: has been received"`
+&&&
+
+Each <'address-list'> can contain a number of addresses, separated by commas,
+in the format of a 'To:' or 'Cc:' header line. In fact, the text you supply
+here is copied exactly into the appropriate header line. It may contain
+additional information as well as email addresses. For example:
+
+...
+mail to "Julius Caesar <jc@rome.example>, \
+         <ma@rome.example> (Mark A.)"
+...
+
+Similarly, the texts supplied for ^from^ and ^reply_to^ are copied into
+their respective header lines.
+
+As a convenience for use in one common case, there is also a command called
+^vacation^. It behaves in the same way as ^mail^, except that the defaults for
+the %subject%, %file%, %log%, %once%, and %once_repeat% options are
+
+  subject "On vacation"
+  expand file .vacation.msg
+  log  .vacation.log
+  once .vacation
+  once_repeat 7d
+
+respectively. These are the same file names and repeat period used by the
+traditional Unix ^vacation^ command. The defaults can be overridden by
+explicit settings, but if a file name is given its contents are expanded only
+if explicitly requested.
+
+*Warning*: The ^vacation^ command should always be used conditionally,
+subject to at least the ^personal^ condition (see section <<SECTpersonal>>
+below) so as not to send automatic replies to non-personal messages from
+mailing lists or elsewhere. Sending an automatic response to a mailing list or
+a mailing list manager is an Internet Sin.
+
+For both commands, the key/value argument pairs can appear in any order. At
+least one of ^text^ or ^file^ must appear (except with ^vacation^, where
+there is a default for ^file^); if both are present, the text string appears
+first in the message. If ^expand^ precedes ^file^, each line of the file is
+subject to string expansion before it is included in the message.
+
+Several lines of text can be supplied to ^text^ by including the escape
+sequence ``\n'' in the string wherever a newline is required. If the command is
+output during filter file testing, newlines in the text are shown as ``\n''.
+
+Note that the keyword for creating a 'Reply-To:' header is ^reply_to^,
+because Exim keywords may contain underscores, but not hyphens. If the ^from^
+keyword is present and the given address does not match the user who owns the
+forward file, Exim normally adds a 'Sender:' header to the message,
+though it can be configured not to do this.
+
+The %extra_headers% keyword allows you to add custom header lines to the
+message. The text supplied must be one or more syntactically valid RFC 2882
+header lines. You can use ``\n'' within quoted text to specify newlines between
+headers, and also to define continued header lines. For example:
+
+  extra_headers "h1: first\nh2: second\n continued\nh3: third"
+
+No newline should appear at the end of the final header line.
+
+If no ^to^ argument appears, the message is sent to the address in the
+$reply_address$ variable (see section <<SECTfilterstringexpansion>> above).
+An 'In-Reply-To:' header is automatically included in the created message,
+giving a reference to the message identification of the incoming message.
+
+If ^return message^ is specified, the incoming message that caused the filter
+file to be run is added to the end of the message, subject to a maximum size
+limitation.
+
+If a log file is specified, a line is added to it for each message sent.
+
+If a ^once^ file is specified, it is used to hold a database for remembering
+who has received a message, and no more than one message is ever sent to any
+particular address, unless ^once_repeat^ is set. This specifies a time
+interval after which another copy of the message is sent. The interval is
+specified as a sequence of numbers, each followed by the initial letter of one
+of ``seconds'', ``minutes'', ``hours'', ``days'', or ``weeks''. For example,
+
+  once_repeat 5d4h
+
+causes a new message to be sent if 5 days and 4 hours have elapsed since the
+last one was sent. There must be no white space in a time interval.
+
+Commonly, the file name specified for ^once^ is used as the base name for
+direct-access (DBM) file operations. There are a number of different DBM
+libraries in existence. Some operating systems provide one as a default, but
+even in this case a different one may have been used when building Exim. With
+some DBM libraries, specifying ^once^ results in two files being created,
+with the suffixes _.dir_ and _.pag_ being added to the given name. With
+some others a single file with the suffix _.db_ is used, or the name is used
+unchanged.
+
+Using a DBM file for implementing the ^once^ feature means that the file
+grows as large as necessary. This is not usually a problem, but some system
+administrators want to put a limit on it. The facility can be configured not to
+use a DBM file, but instead, to use a regular file with a maximum size. The
+data in such a file is searched sequentially, and if the file fills up, the
+oldest entry is deleted to make way for a new one. This means that some
+correspondents may receive a second copy of the message after an unpredictable
+interval. Consult your local information to see if your system is configured
+this way.
+
+More than one ^mail^ or ^vacation^ command may be obeyed in a single filter
+run; they are all honoured, even when they are to the same recipient.
+
+
+
+[[SECTlog]]
+Logging commands
+~~~~~~~~~~~~~~~~
+A log can be kept of actions taken by a filter file. This facility is normally
+available in conventional configurations, but there are some situations where
+it might not be. Also, the system administrator may choose to disable it. Check
+your local information if in doubt.
+
+Logging takes place while the filter file is being interpreted. It does not
+queue up for later like the delivery commands. The reason for this is so that a
+log file need be opened only once for several write operations. There are two
+commands, neither of which constitutes a significant delivery. The first
+defines a file to which logging output is subsequently written:
+
+&&&
+`     logfile `<'file name'>
+`e.g. logfile $home/filter.log`
+&&&
+
+The file name must be fully qualified. You can use $home$, as in this
+example, to refer to your home directory. The file name may optionally be
+followed by a mode for the file, which is used if the file has to be created.
+For example,
+
+  logfile $home/filter.log 0644
+
+The number is interpreted as octal, even if it does not begin with a zero.
+The default for the mode is 600. It is suggested that the ^logfile^ command
+normally appear as the first command in a filter file. Once ^logfile^ has
+been obeyed, the ^logwrite^ command can be used to write to the log file:
+
+&&&
+`     logwrite "`<'some text string'>`"`
+`e.g. logwrite "$tod_log $message_id processed"`
+&&&
+
+It is possible to have more than one ^logfile^ command, to specify writing to
+different log files in different circumstances. Writing takes place at the end
+of the file, and a newline character is added to the end of each string if
+there isn't one already there. Newlines can be put in the middle of the string
+by using the ``\n'' escape sequence. Lines from simultaneous deliveries may get
+interleaved in the file, as there is no interlocking, so you should plan your
+logging with this in mind. However, data should not get lost.
+
+
+
+[[SECTfinish]]
+The finish command
+~~~~~~~~~~~~~~~~~~
+The command ^finish^, which has no arguments, causes Exim to stop
+interpreting the filter file. This is not a significant action unless preceded
+by ^seen^. A filter file containing only ^seen finish^ is a black hole.
+
+
+[[SECTtestprint]]
+The testprint command
+~~~~~~~~~~~~~~~~~~~~~
+It is sometimes helpful to be able to print out the values of variables when
+testing filter files. The command
+
+&&&
+`     testprint `<'text'>
+`e.g. testprint "home=$home reply_address=$reply_address"`
+&&&
+
+does nothing when mail is being delivered. However, when the filtering code is
+being tested by means of the %-bf% option (see section <<SECTtesting>> above),
+the value of the string is written to the standard output.
+
+
+++++++++++++
+<?hard-pagebreak?>
+++++++++++++
+[[SECTfail]]
+The fail command
+~~~~~~~~~~~~~~~~
+When Exim's filtering facilities are being used as a system filter, the
+^fail^ command is available, to force delivery failure. Because this command
+is normally usable only by the system administrator, and not enabled for use by
+ordinary users, it is described in more detail in the main Exim specification
+rather than in this document.
+
+
+[[SECTfreeze]]
+The freeze command
+~~~~~~~~~~~~~~~~~~
+When Exim's filtering facilities are being used as a system filter, the
+^freeze^ command is available, to freeze a message on the queue. Because this
+command is normally usable only by the system administrator, and not enabled
+for use by ordinary users, it is described in more detail in the main Exim
+specification rather than in this document.
+
+
+
+[[SECTheaders]]
+The headers command
+~~~~~~~~~~~~~~~~~~~
+The ^headers^ command can be used to change the target character set that is
+used when translating the contents of encoded header lines for insertion by the
+$header_$ mechanism (see section <<SECTheadervariables>> above). The default
+can be set in the Exim configuration; if not specified, ISO-8859-1 is used. The
+only currently supported format for the ^headers^ command in user filters is as
+in this example:
+
+  headers charset "UTF-8"
+
+That is, ^headers^ is followed by the word ^charset^ and then the name of a
+character set. This particular example would be useful if you wanted to compare
+the contents of a header to a UTF-8 string.
+
+In system filter files, the ^headers^ command can be used to add or remove
+header lines from the message. These features are described in the main Exim
+specification.
+
+
+
+[[SECTif]]
+Obeying commands conditionally
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+Most of the power of filtering comes from the ability to test conditions and
+obey different commands depending on the outcome. The ^if^ command is used to
+specify conditional execution, and its general form is
+
+&&&
+`if    `<'condition'>
+`then  `<'commands'>
+`elif  `<'condition'>
+`then  `<'commands'>
+`else  `<'commands'>
+`endif`
+&&&
+
+There may be any number of ^elif^ and ^then^ sections (including none) and
+the ^else^ section is also optional. Any number of commands, including nested
+^if^ commands, may appear in any of the <'commands'> sections.
+
+Conditions can be combined by using the words ^and^ and ^or^, and round
+brackets (parentheses) can be used to specify how several conditions are to
+combine. Without brackets, ^and^ is more binding than ^or^.
+For example,
+
+  if
+    $h_subject: contains "Make money" or
+    $h_precedence: is "junk" or
+    ($h_sender: matches ^\\d{8}@ and not personal) or
+    $message_body contains "this is not spam"
+  then
+    seen finish
+  endif
+
+A condition can be preceded by ^not^ to negate it, and there are also some
+negative forms of condition that are more English-like.
+
+
+
+++++++++++++
+<?hard-pagebreak?>
+++++++++++++
+String testing conditions
+~~~~~~~~~~~~~~~~~~~~~~~~~
+There are a number of conditions that operate on text strings, using the words
+``begins'', ``ends'', ``is'', ``contains'' and ``matches''. If you want to apply the same
+test to more than one header line, you can easily concatenate them into a
+single string for testing, as in this example:
+
+  if "$h_to:, $h_cc:" contains me@domain.example then ...
+
+If a string-testing condition name is written in lower case, the testing
+of letters is done without regard to case; if it is written in upper case
+(for example, ``CONTAINS''), the case of letters is taken into account.
+
+&&&
+`     `<'text1'>` begins `<'text2'>
+`     `<'text1'>` does not begin `<'text2'>
+`e.g. $header_from: begins "Friend@"`
+&&&
+
+A ``begins'' test checks for the presence of the second string at the start of
+the first, both strings having been expanded.
+
+&&&
+`     `<'text1'>` ends `<'text2'>
+`     `<'text1'>` does not end `<'text2'>
+`e.g. $header_from: ends "public.com.example"`
+&&&
+
+An ``ends'' test checks for the presence of the second string at the end of
+the first, both strings having been expanded.
+
+&&&
+`     `<'text1'>` is `<'text2'>
+`     `<'text1'>` is not `<'text2'>
+`e.g. $local_part_suffix is "-foo"`
+&&&
+
+An ``is'' test does an exact match between the strings, having first expanded
+both strings.
+
+&&&
+`     `<'text1'>` contains `<'text2'>
+`     `<'text1'>` does not contain `<'text2'>
+`e.g. $header_subject: contains "evolution"`
+&&&
+
+A ``contains'' test does a partial string match, having expanded both strings.
+
+&&&
+`     `<'text1'>` matches `<'text2'>
+`     `<'text1'>` does not match `<'text2'>
+`e.g. $sender_address matches "(bill|john)@"`
+&&&
+
+For a ``matches'' test, after expansion of both strings, the second one is
+interpreted as a regular expression. Exim uses the PCRE regular expression
+library, which provides regular expressions that are compatible with Perl.
+
+The match succeeds if the regular expression matches any part of the first
+string. If you want a regular expression to match only at the start or end of
+the subject string, you must encode that requirement explicitly, using the `^`
+or `$` metacharacters. The above example, which is not so constrained, matches
+all these addresses:
+
+  bill@test.example
+  john@some.example
+  spoonbill@example.com
+  littlejohn@example.com
+
+To match only the first two, you could use this:
+
+  if $sender_address matches "^(bill|john)@" then ...
+
+Care must be taken if you need a backslash in a regular expression, because
+backslashes are interpreted as escape characters both by the string expansion
+code and by Exim's normal processing of strings in quotes. For example, if you
+want to test the sender address for a domain ending in '.com' the regular
+expression is
+
+  \.com$
+
+The backslash and dollar sign in that expression have to be escaped when used
+in a filter command, as otherwise they would be interpreted by the expansion
+code. Thus, what you actually write is
+
+  if $sender_address matches \\.com\$
+
+An alternative way of handling this is to make use of the `\N` expansion
+flag for suppressing expansion:
+
+  if $sender_address matches \N\.com$\N
+
+Everything between the two occurrences of `\N` is copied without change by
+the string expander (and in fact you do not need the final one, because it is
+at the end of the string). If the regular expression is given in quotes
+(mandatory only if it contains white space) you have to write either
+
+  if $sender_address matches "\\\\.com\\$"
+
+or
+
+  if $sender_address matches "\\N\\.com$\\N"
+
+
+If the regular expression contains bracketed sub-expressions, numeric
+variable substitutions such as $1$ can be used in the subsequent actions
+after a successful match. If the match fails, the values of the numeric
+variables remain unchanged. Previous values are not restored after ^endif^.
+In other words, only one set of values is ever available. If the condition
+contains several sub-conditions connected by ^and^ or ^or^, it is the
+strings extracted from the last successful match that are available in
+subsequent actions. Numeric variables from any one sub-condition are also
+available for use in subsequent sub-conditions, because string expansion of a
+condition occurs just before it is tested.
+
+
+Numeric testing conditions
+~~~~~~~~~~~~~~~~~~~~~~~~~~
+The following conditions are available for performing numerical tests:
+
+&&&
+`     `<'number1'>` is above `<'number2'>
+`     `<'number1'>` is not above `<'number2'>
+`     `<'number1'>` is below `<'number2'>
+`     `<'number1'>` is not below `<'number2'>
+`e.g. $message_size is not above 10k`
+&&&
+
+The <'number'> arguments must expand to strings of digits, optionally followed
+by one of the letters K or M (upper case or lower case) which cause
+multiplication by 1024 and 1024x1024 respectively.
+
+
+Testing for significant deliveries
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+You can use the ^delivered^ condition to test whether or not any previously
+obeyed filter commands have set up a significant delivery. For example:
+
+  if not delivered then save mail/anomalous endif
+
+``Delivered'' is perhaps a poor choice of name for this condition, because the
+message has not actually been delivered; rather, a delivery has been set up for
+later processing.
+
+
+Testing for error messages
+~~~~~~~~~~~~~~~~~~~~~~~~~~
+The condition ^error_message^ is true if the incoming message is a bounce
+(mail delivery error) message. Putting the command
+
+  if error_message then finish endif
+
+at the head of your filter file is a useful insurance against things going
+wrong in such a way that you cannot receive delivery error reports. *Note*:
+^error_message^ is a condition, not an expansion variable, and therefore is
+not preceded by `$`.
+
+
+Testing a list of addresses
+~~~~~~~~~~~~~~~~~~~~~~~~~~~
+There is a facility for looping through a list of addresses and applying a
+condition to each of them. It takes the form
+
+&&&
+`foranyaddress `<'string'>` (`<'condition'>`)`
+&&&
+
+where <'string'> is interpreted as a list of RFC 2822 addresses, as in a
+typical header line, and <'condition'> is any valid filter condition or
+combination of conditions. The ``group'' syntax that is defined for certain
+header lines that contain addresses is supported.
+
+The parentheses surrounding the condition are mandatory, to delimit it from
+possible further sub-conditions of the enclosing ^if^ command. Within the
+condition, the expansion variable $thisaddress$ is set to the non-comment
+portion of each of the addresses in the string in turn. For example, if the
+string is
+
+  B.Simpson <bart@sfld.example>, lisa@sfld.example (his sister)
+
+then $thisaddress$ would take on the values `bart@sfld.example` and
+`lisa@sfld.example` in turn.
+
+If there are no valid addresses in the list, the whole condition is false. If
+the internal condition is true for any one address, the overall condition is
+true and the loop ends. If the internal condition is false for all addresses in
+the list, the overall condition is false. This example tests for the presence
+of an eight-digit local part in any address in a 'To:' header:
+
+  if foranyaddress $h_to: ( $thisaddress matches ^\\d{8}@ ) then ...
+
+When the overall condition is true, the value of $thisaddress$ in the
+commands that follow ^then^ is the last value it took on inside the loop. At
+the end of the ^if^ command, the value of $thisaddress$ is reset to what it
+was before. It is best to avoid the use of multiple occurrences of
+^foranyaddress^, nested or otherwise, in a single ^if^ command, if the
+value of $thisaddress$ is to be used afterwards, because it isn't always
+clear what the value will be. Nested ^if^ commands should be used instead.
+
+Header lines can be joined together if a check is to be applied to more than
+one of them. For example:
+
+  if foranyaddress $h_to:,$h_cc: ....
+
+scans through the addresses in both the 'To:' and the 'Cc:' headers.
+
+
+[[SECTpersonal]]
+Testing for personal mail
+~~~~~~~~~~~~~~~~~~~~~~~~~
+A common requirement is to distinguish between incoming personal mail and mail
+from a mailing list, or from a robot or other automatic process (for example, a
+bounce message). In particular, this test is normally required for ``vacation
+messages''.
+
+The ^personal^ condition checks that the message is not a bounce message and
+that the current user's email address appears in the 'To:' header. It also
+checks that the sender is not the current user or one of a number of common
+daemons, and that there are no header lines starting 'List-' in the message.
+Finally, it checks the content of the 'Precedence:' header line, if there is
+one.
+
+You should always use the ^personal^ condition when generating automatic
+responses. This example shows the use of ^personal^ in a filter file that is
+sending out vacation messages:
+
+  if personal then
+    mail to $reply_address
+    subject "I am on holiday"
+    file $home/vacation/message
+    once $home/vacation/once
+    once_repeat 10d
+  endif
+
+It is tempting, when writing commands like the above, to quote the original
+subject in the reply. For example:
+
+  subject "Re: $h_subject:"
+
+There is a danger in doing this, however. It may allow a third party to
+subscribe you to an opt-in mailing list, provided that the list accepts bounce
+messages as subscription confirmations. (Messages sent from filters are always
+sent as bounce messages.) Well-managed lists require a non-bounce message to
+confirm a subscription, so the danger is relatively small.
+
+If prefixes or suffixes are in use for local parts -- something which depends
+on the configuration of Exim (see section <<SECTmbox>> below) -- the tests for
+the current user are done with the full address (including the prefix and
+suffix, if any) as well as with the prefix and suffix removed. If the system is
+configured to rewrite local parts of mail addresses, for example, to rewrite
+`dag46` as `Dirk.Gently`, the rewritten form of the address is also used in
+the tests.
+
+
+
+Alias addresses for the personal condition
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+It is quite common for people who have mail accounts on a number of different
+systems to forward all their mail to one system, and in this case a check for
+personal mail should test all their various mail addresses. To allow for this,
+the ^personal^ condition keyword can be followed by
+
+&&&
+`alias `<'address'>
+&&&
+
+any number of times, for example
+
+  if personal alias smith@else.where.example
+              alias jones@other.place.example
+  then ...
+
+The alias addresses are treated as alternatives to the current user's email
+address when testing the contents of header lines.
+
+
+Details of the personal condition
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+The basic ^personal^ test is roughly equivalent to the following:
+
+  not error_message and
+  $message_headers does not contain "\nList-" and
+  $header_auto-submitted: does not contain "auto-" and
+  $header_precedence: does not contain "bulk" and
+  $header_precedence: does not contain "list" and
+  $header_precedence: does not contain "junk" and
+  foranyaddress $header_to:
+    ( $thisaddress contains "$local_part$domain" ) and
+  not foranyaddress $header_from:
+    (
+    $thisaddress contains "$local_partdomain" or
+    $thisaddress contains "server" or
+    $thisaddress contains "daemon" or
+    $thisaddress contains "root" or
+    $thisaddress contains "listserv" or
+    $thisaddress contains "majordomo" or
+    $thisaddress contains "-request" or
+    $thisaddress matches  "^owner-[^]+"
+    )
+
+The variable $local_part$ contains the local part of the mail address of
+the user whose filter file is being run -- it is normally your login id. The
+$domain$ variable contains the mail domain. As explained above, if aliases
+or rewriting are defined, or if prefixes or suffixes are in use, the tests for
+the current user are also done with alternative addresses.
+
+
+
+
+Testing delivery status
+~~~~~~~~~~~~~~~~~~~~~~~
+There are two conditions that are intended mainly for use in system filter
+files, but which are available in users' filter files as well. The condition
+^first_delivery^ is true if this is the first process that is attempting to
+deliver the message, and false otherwise. This indicator is not reset until the
+first delivery process successfully terminates; if there is a crash or a power
+failure (for example), the next delivery attempt is also a ``first delivery''.
+
+In a user filter file ^first_delivery^ will be false if there was previously an
+error in the filter, or if a delivery for the user failed owing to, for
+example, a quota error, or if forwarding to a remote address was deferred for
+some reason.
+
+The condition ^manually_thawed^ is true if the message was ``frozen'' for some
+reason, and was subsequently released by the system administrator. It is
+unlikely to be of use in users' filter files.
+
+
+[[SECTmbox]]
+Multiple personal mailboxes
+~~~~~~~~~~~~~~~~~~~~~~~~~~~
+The system administrator can configure Exim so that users can set up variants
+on their email addresses and handle them separately. Consult your system
+administrator or local documentation to see if this facility is enabled on your
+system, and if so, what the details are.
+
+The facility involves the use of a prefix or a suffix on an email address. For
+example, all mail addressed to 'lg303-'<'something'> would be the property of
+user 'lg303', who could determine how it was to be handled, depending on the
+value of <'something'>.
+
+There are two possible ways in which this can be set up. The first possibility
+is the use of multiple '.forward' files. In this case, mail to 'lg303-foo',
+for example, is handled by looking for a file called _.forward-foo_ in
+'lg303'{ap}s home directory. If such a file does not exist, delivery fails and the
+message is returned to its sender.
+
+The alternative approach is to pass all messages through a single _.forward_
+file, which must be a filter file so that it can distinguish between the
+different cases by referencing the variables $local_part_prefix$ or
+$local_part_suffix$, as in the final example in section <<SECTex>> below.
+
+It is possible to configure Exim to support both schemes at once. In this case,
+a specific _.forward-foo_ file is first sought; if it is not found, the basic
+_.forward_ file is used.
+
+The ^personal^ test (see section <<SECTpersonal>>) includes prefixes and
+suffixes in its checking.
+
+
+
+Ignoring delivery errors
+~~~~~~~~~~~~~~~~~~~~~~~~
+As was explained above, filtering just sets up addresses for delivery -- no
+deliveries are actually done while a filter file is active. If any of the
+generated addresses subsequently suffers a delivery failure, an error message
+is generated in the normal way. However, if a filter command that sets up a
+delivery is preceded by the word ^noerror^, errors for that delivery,
+'and any deliveries consequent on it' (that is, from alias, forwarding, or
+filter files it invokes) are ignored.
+
+
+
+[[SECTex]]
+Examples of Exim filter commands
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+Simple forwarding:
+
+  # Exim filter
+  deliver baggins@rivendell.middle-earth.example
+
+Vacation handling using traditional means, assuming that the _.vacation.msg_
+and other files have been set up in your home directory:
+
+  # Exim filter
+  unseen pipe "/usr/ucb/vacation \"$local_part\""
+
+Vacation handling inside Exim, having first created a file called
+_.vacation.msg_ in your home directory:
+
+  # Exim filter
+  if personal then vacation endif
+
+File some messages by subject:
+
+  # Exim filter
+  if $header_subject: contains "empire" or
+     $header_subject: contains "foundation"
+  then
+     save $home/mail/f+e
+  endif
+
+Save all non-urgent messages by weekday:
+
+  # Exim filter
+  if $header_subject: does not contain "urgent" and
+     $tod_full matches "^(...),"
+  then
+    save $home/mail/$1
+  endif
+
+Throw away all mail from one site, except from postmaster:
+
+  # Exim filter
+  if $reply_address contains "@spam.site.example" and
+     $reply_address does not contain "postmaster@"
+  then
+     seen finish
+  endif
+
+Handle multiple personal mailboxes
+
+  # Exim filter
+  if $local_part_suffix is "-foo"
+  then
+    save $home/mail/foo
+  elif $local_part_suffix is "-bar"
+  then
+    save $home/mail/bar
+  endif
+
+
diff --git a/doc/doc-docbook/spec.ascd b/doc/doc-docbook/spec.ascd
new file mode 100644 (file)
index 0000000..88b6440
--- /dev/null
@@ -0,0 +1,33111 @@
+////////////////////////////////////////////////////////////////////////////
+$Cambridge: exim/doc/doc-docbook/spec.ascd,v 1.1 2005/06/16 10:32:31 ph10 Exp $
+
+This is the primary source of the Exim Manual. It is an AsciiDoc document
+that is converted into DocBook XML for subsequent conversion into printing
+and online formats. The markup used herein is traditional AsciiDoc markup,
+with some extras. The markup is summarized in a file called AdMarkup.txt. A
+private AsciiDoc configuration file specifies how the extra markup is to be
+translated into DocBook XML. You MUST use this private AsciiDoc markup if you
+want to get sensible results from processing this document.
+////////////////////////////////////////////////////////////////////////////
+
+
+
+////////////////////////////////////////////////////////////////////////////
+I am abusing the <abstract> DocBook element as the only trivial way of getting
+this information onto the title verso page in the printed renditions. A better
+title page would be a useful improvement. The <abstract> element is removed by
+preprocessing for the HTML renditions, and the whole <docbookinfo> element is
+removed for ascii output formats.
+////////////////////////////////////////////////////////////////////////////
+
+Specification of the Exim Mail Transfer Agent
+=============================================
+:abstract:        University of Cambridge Computing Service, New Museums Site, Pembroke Street, Cambridge CB2 3QH, England
+:author:          Philip Hazel
+:copyright:       University of Cambridge
+:cpyear:          2005
+:date:            13 May 2005
+:doctitleabbrev:  The Exim MTA
+:revision:        4.50
+
+
+//////////////////////////////////////////////////////////////////////////////
+***WARNING*** Do not put anything, not even a titleabbrev, setting before
+the first chapter (luckily it does not need one) because if you do, AsciiDoc
+creates an empty <preface> element, which we do not want.
+//////////////////////////////////////////////////////////////////////////////
+
+Introduction
+------------
+
+////////////////////////////////////////////////////////////////////////////
+These are definitions of AsciiDoc "attributes" that are in effect "variables"
+whose values can be substituted. The first makes index entries shorter. The
+second avoids problems with literal asterisks getting tangled up with bold
+emphasis quotes. The others are here for convenience of editing.
+
+***WARNING*** The positioning of these definitions, after the first Chapter
+title, seems to be important. If they are placed earlier, they give rise to
+incorrect XML.
+////////////////////////////////////////////////////////////////////////////
+
+:ACL:             access control lists (ACLs)
+:star:            *
+:previousversion: 4.40
+:version:         4.50
+
+
+////////////////////////////////////////////////////////////////////////////
+This chunk of literal XML implements index entries of the form "x, see y" and
+"x, see also y". It didn't seem worth inventing AsciiDoc markup for this,
+because is it not something that is likely to change often.
+////////////////////////////////////////////////////////////////////////////
+
+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
+<indexterm role="concept">
+  <primary>$1, $2, etc.</primary>
+  <see><emphasis>numerical variables</emphasis></see>
+</indexterm>
+<indexterm role="concept">
+  <primary>address</primary>
+  <secondary>rewriting</secondary>
+  <see><emphasis>rewriting</emphasis></see>
+</indexterm>
+<indexterm role="concept">
+  <primary>CR character</primary>
+  <see><emphasis>carriage return</emphasis></see>
+</indexterm>
+<indexterm role="concept">
+  <primary>CRL</primary>
+  <see><emphasis>certificate revocation list</emphasis></see>
+</indexterm>
+<indexterm role="concept">
+  <primary>delivery</primary>
+  <secondary>failure report</secondary>
+  <see><emphasis>bounce message</emphasis></see>
+</indexterm>
+<indexterm role="concept">
+  <primary>dialup</primary>
+  <see><emphasis>intermittently connected hosts</emphasis></see>
+</indexterm>
+<indexterm role="concept">
+  <primary>exiscan</primary>
+  <see><emphasis>content scanning</emphasis></see>
+</indexterm>
+<indexterm role="concept">
+  <primary>failover</primary>
+  <see><emphasis>fallback</emphasis></see>
+</indexterm>
+<indexterm role="concept">
+  <primary>fallover</primary>
+  <see><emphasis>fallback</emphasis></see>
+</indexterm>
+<indexterm role="concept">
+  <primary>filter</primary>
+  <secondary>Sieve</secondary>
+  <see><emphasis>Sieve filter</emphasis></see>
+</indexterm>
+<indexterm role="concept">
+  <primary>ident</primary>
+  <see><emphasis>RFC 1413</emphasis></see>
+</indexterm>
+<indexterm role="concept">
+  <primary>LF character</primary>
+  <see><emphasis>linefeed</emphasis></see>
+</indexterm>
+<indexterm role="concept">
+  <primary>maximum</primary>
+  <see><emphasis>limit</emphasis></see>
+</indexterm>
+<indexterm role="concept">
+  <primary>no_<emphasis>xxx</emphasis></primary>
+  <see>entry for xxx</see>
+</indexterm>
+<indexterm role="concept">
+  <primary>NUL</primary>
+  <see><emphasis>binary zero</emphasis></see>
+</indexterm>
+<indexterm role="concept">
+  <primary>passwd file</primary>
+  <see><emphasis>/etc/passwd</emphasis></see>
+</indexterm>
+<indexterm role="concept">
+  <primary>process id</primary>
+  <see><emphasis>pid</emphasis></see>
+</indexterm>
+<indexterm role="concept">
+  <primary>RBL</primary>
+  <see><emphasis>DNS list</emphasis></see>
+</indexterm>
+<indexterm role="concept">
+  <primary>redirection</primary>
+  <see><emphasis>address redirection</emphasis></see>
+</indexterm>
+<indexterm role="concept">
+  <primary>return path</primary>
+  <seealso><emphasis>envelope sender</emphasis></seealso>
+</indexterm>
+<indexterm role="concept">
+  <primary>scanning</primary>
+  <see><emphasis>content scanning</emphasis></see>
+</indexterm>
+<indexterm role="concept">
+  <primary>SSL</primary>
+  <see><emphasis>TLS</emphasis></see>
+</indexterm>
+<indexterm role="concept">
+  <primary>string</primary>
+  <secondary>expansion</secondary>
+  <see><emphasis>expansion</emphasis></see>
+</indexterm>
+<indexterm role="concept">
+  <primary>top bit</primary>
+  <see><emphasis>8-bit characters</emphasis></see>
+</indexterm>
+<indexterm role="concept">
+  <primary>variables</primary>
+  <see><emphasis>expansion, variables</emphasis></see>
+</indexterm>
+<indexterm role="concept">
+  <primary>zero, binary</primary>
+  <see><emphasis>binary zero</emphasis></see>
+</indexterm>
+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
+
+
+////////////////////////////////////////////////////////////////////////////
+OK, now we start with the real data for this first chapter.
+////////////////////////////////////////////////////////////////////////////
+
+Exim is a mail transfer agent (MTA) for hosts that are running Unix or
+Unix-like operating systems. It was designed on the assumption that it would be
+run on hosts that are permanently connected to the Internet. However, it can be
+used on intermittently connected hosts with suitable configuration adjustments.
+
+Configuration files currently exist for the following operating systems: AIX,
+BSD/OS (aka BSDI), Darwin (Mac OS X), DGUX, FreeBSD, GNU/Hurd, GNU/Linux,
+HI-OSF (Hitachi), HP-UX, IRIX, MIPS RISCOS, NetBSD, OpenBSD, QNX, SCO, SCO
+SVR4.2 (aka UNIX-SV), Solaris (aka SunOS5), SunOS4, Tru64-Unix (formerly
+Digital UNIX, formerly DEC-OSF1), Ultrix, and Unixware. Some of these operating
+systems are no longer current and cannot easily be tested, so the configuration
+files may no longer work in practice.
+
+There are also configuration files for compiling Exim in the Cygwin environment
+that can be installed on systems running Windows. However, this document does
+not contain any information about running Exim in the Cygwin environment.
+
+The terms and conditions for the use and distribution of Exim are contained in
+the file _NOTICE_. Exim is distributed under the terms of the GNU General
+Public Licence, a copy of which may be found in the file _LICENCE_.
+
+The use, supply or promotion of Exim for the purpose of sending bulk,
+unsolicited electronic mail is incompatible with the basic aims of the program,
+which revolve around the free provision of a service that enhances the quality
+of personal communications. The author of Exim regards indiscriminate
+mass-mailing as an antisocial, irresponsible abuse of the Internet.
+
+Exim owes a great deal to Smail 3 and its author, Ron Karr. Without the
+experience of running and working on the Smail 3 code, I could never have
+contemplated starting to write a new MTA. Many of the ideas and user interfaces
+were originally taken from Smail 3, though the actual code of Exim is entirely
+new, and has developed far beyond the initial concept.
+
+Many people, both in Cambridge and around the world, have contributed to the
+development and the testing of Exim, and to porting it to various operating
+systems. I am grateful to them all. The distribution now contains a file called
+_ACKNOWLEDGMENTS_, in which I have started recording the names of
+contributors.
+
+
+
+Exim documentation
+~~~~~~~~~~~~~~~~~~
+[revisionflag="changed"]
+cindex:[documentation]
+This edition of the Exim specification applies to version {version} of Exim.
+Substantive changes from the {previousversion} edition are marked in some
+renditions of the document; this paragraph is so marked if the rendition is
+capable of showing a change indicator.
+
+This document is very much a reference manual; it is not a tutorial. The reader
+is expected to have some familiarity with the SMTP mail transfer protocol and
+with general Unix system administration. Although there are some discussions
+and examples in places, the information is mostly organized in a way that makes
+it easy to look up, rather than in a natural order for sequential reading.
+Furthermore, the manual aims to cover every aspect of Exim in detail, including
+a number of rarely-used, special-purpose features that are unlikely to be of
+very wide interest.
+
+cindex:[books about Exim]
+An ``easier'' discussion of Exim which provides more in-depth explanatory,
+introductory, and tutorial material can be found in a book entitled
+'The Exim SMTP Mail Server', published by UIT Cambridge
+(*http://www.uit.co.uk/exim-book/[]*).
+
+This book also contains a chapter that gives a general introduction to SMTP and
+Internet mail. Inevitably, however, the book is unlikely to be fully up-to-date
+with the latest release of Exim. (Note that the earlier book about Exim,
+published by O'Reilly, covers Exim 3, and many things have changed in Exim 4.)
+
+cindex:[_doc/NewStuff_]
+cindex:[_doc/ChangeLog_]
+cindex:[change log]
+As the program develops, there may be features in newer versions that have not
+yet made it into this document, which is updated only when the most significant
+digit of the fractional part of the version number changes. Specifications of
+new features that are not yet in this manual are placed in the file
+_doc/NewStuff_ in the Exim distribution.
+
+Some features may be classified as ``experimental''. These may change
+incompatibly while they are developing, or even be withdrawn. For this reason,
+they are not documented in this manual. Information about experimental features
+can be found in the file _doc/experimental.txt_.
+
+All changes to the program (whether new features, bug fixes, or other kinds of
+change) are noted briefly in the file called _doc/ChangeLog_.
+
+cindex:[_doc/spec.txt_]
+This specification itself is available as an ASCII file in _doc/spec.txt_ so
+that it can easily be searched with a text editor. Other files in the _doc_
+directory are:
+
+[frame="none"]
+`--------------------`------------------------------------------
+_OptionLists.txt_    list of all options in alphabetical order
+_dbm.discuss.txt_    discussion about DBM libraries
+_exim.8_             a man page of Exim's command line options
+_experimental.txt_   documentation of experimental features
+_filter.txt_         specification of the filter language
+_pcrepattern.txt_    specification of PCRE regular expressions
+_pcretest.txt_       specification of the PCRE testing program
+_Exim3.upgrade_      upgrade notes from release 2 to release 3
+_Exim4.upgrade_      upgrade notes from release 3 to release 4
+----------------------------------------------------------------
+
+The main specification and the specification of the filtering language are also
+available in other formats (HTML, PostScript, PDF, and Texinfo). Section
+<<SECTavail>> below tells you how to get hold of these.
+
+
+
+FTP and web sites
+~~~~~~~~~~~~~~~~~
+cindex:[web site]
+cindex:[FTP site]
+The primary distribution site for Exim is currently the University of
+Cambridge's FTP site, whose contents are described in 'Where to find the Exim
+distribution' below. In addition, there is a web site and an FTP site at
+%exim.org%. These are now also hosted at the University of Cambridge. The
+%exim.org% site was previously hosted for a number of years by Energis Squared,
+formerly Planet Online Ltd, whose support I gratefully acknowledge.
+
+As well as Exim distribution tar files, the Exim web site contains a number of
+differently formatted versions of the documentation, including the
+cindex:[FAQ] FAQ in both text and HTML formats. The HTML version comes with
+a keyword-in-context index. A recent addition to the online information is the
+cindex:[wiki]
+Exim wiki (*http://www.exim.org/eximwiki/[]*).
+We hope that this will make it easier for Exim users to contribute examples,
+tips, and know-how for the benefit of others.
+
+
+
+Mailing lists
+~~~~~~~~~~~~~
+cindex:[mailing lists,for Exim users]
+The following are the three main Exim mailing lists:
+
+[frame="none"]
+`-------------------------------`----------------------------------------
+'exim-users@exim.org'           general discussion list
+'exim-dev@exim.org'             discussion of bugs, enhancements, etc.
+'exim-announce@exim.org'        moderated, low volume announcements list
+-------------------------------------------------------------------------
+
+You can subscribe to these lists, change your existing subscriptions, and view
+or search the archives via the mailing lists link on the Exim home page. The
+'exim-users' mailing list is also forwarded to
+*http://www.egroups.com/list/exim-users[]*, an archiving system with searching
+capabilities.
+
+
+Exim training
+~~~~~~~~~~~~~
+cindex:[training courses]
+From time to time (approximately annually at the time of writing),
+lecture-based training courses are run by the author of Exim in Cambridge, UK.
+Details can be found on the web site
+*http://www-tus.csx.cam.ac.uk/courses/exim/[]*.
+
+
+Bug reports
+~~~~~~~~~~~
+cindex:[bug reports]
+cindex:[reporting bugs]
+Reports of obvious bugs should be emailed to 'bugs@exim.org'. However, if
+you are unsure whether some behaviour is a bug or not, the best thing to do is
+to post a message to the 'exim-users' mailing list and have it discussed.
+
+
+
+[[SECTavail]]
+Where to find the Exim distribution
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+cindex:[FTP site]
+cindex:[distribution,ftp site]
+The master ftp site for the Exim distribution is
+
+&&&
+*ftp://ftp.csx.cam.ac.uk/pub/software/email/exim[]*
+&&&
+
+This is mirrored by
+
+&&&
+*ftp://ftp.exim.org/pub/exim[]*
+&&&
+
+The file references that follow are relative to the _exim_ directories at these
+sites. There are now quite a number of independent mirror sites around the
+world. Those that I know about are listed in the file called _Mirrors_.
+
+Within the _exim_ directory there are subdirectories called _exim3_ (for
+previous Exim 3 distributions), _exim4_ (for the latest Exim 4
+distributions), and _Testing_ for testing versions. In the _exim4_
+subdirectory, the current release can always be found in files called
+
+&&&
+_exim-n.nn.tar.gz_
+_exim-n.nn.tar.bz2_
+&&&
+
+where 'n.nn' is the highest such version number in the directory. The two
+files contain identical data; the only difference is the type of compression.
+The _.bz2_ file is usually a lot smaller than the _.gz_ file.
+
+cindex:[distribution,signing details]
+cindex:[distribution,public key]
+cindex:[public key for signed distribution]
+The distributions are currently signed with Philip Hazel's GPG key. The
+corresponding public key is available from a number of keyservers, and there is
+also a copy in the file _Public-Key_. The signatures for the tar bundles are
+in:
+
+&&&
+_exim-n.nn.tar.gz.sig_
+_exim-n.nn.tar.bz2.sig_
+&&&
+
+For each released version, the log of changes is made separately available in a
+separate file in the directory _ChangeLogs_ so that it is possible to
+find out what has changed without having to download the entire distribution.
+
+cindex:[documentation,available formats]
+The main distribution contains ASCII versions of this specification and other
+documentation; other formats of the documents are available in separate files
+inside the _exim4_ directory of the FTP site:
+
+&&&
+_exim-html-n.nn.tar.gz_
+_exim-pdf-n.nn.tar.gz_
+_exim-postscript-n.nn.tar.gz_
+_exim-texinfo-n.nn.tar.gz_
+&&&
+
+These tar files contain only the _doc_ directory, not the complete
+distribution, and are also available in _.bz2_ as well as _.gz_ forms.
+cindex:[FAQ]
+The FAQ is available for downloading in two different formats in these files:
+
+&&&
+_exim4/FAQ.txt.gz_
+_exim4/FAQ.html.tar.gz_
+&&&
+
+The first of these is a single ASCII file that can be searched with a text
+editor. The second is a directory of HTML files, normally accessed by starting
+at _index.html_. The HTML version of the FAQ (which is also included in the
+HTML documentation tarbundle) includes a keyword-in-context index, which is
+often the most convenient way of finding your way around.
+
+
+Wish list
+~~~~~~~~~
+cindex:[wish list]
+A wish list is maintained, containing ideas for new features that have been
+submitted. From time to time the file is exported to the ftp site into the file
+_exim4/WishList_. Items are removed from the list if they get implemented.
+
+
+
+Contributed material
+~~~~~~~~~~~~~~~~~~~~
+cindex:[contributed material]
+At the ftp site, there is a directory called _Contrib_ that contains
+miscellaneous files contributed to the Exim community by Exim users. There is
+also a collection of contributed configuration examples in
+_exim4/config.samples.tar.gz_. These samples are referenced from the FAQ.
+
+
+
+Limitations
+~~~~~~~~~~~
+- cindex:[limitations of Exim]
+Exim is designed for use as an Internet MTA, and therefore handles addresses
+in RFC 2822 domain format only.
+cindex:[bang paths,not handled by Exim]
+It cannot handle UUCP ``bang paths'', though simple two-component bang paths can
+be converted by a straightforward rewriting configuration. This restriction
+does not prevent Exim from being interfaced to UUCP as a transport mechanism,
+provided that domain addresses are used.
+
+- cindex:[domainless addresses]
+cindex:[address,without domain]
+Exim insists that every address it handles has a domain attached. For incoming
+local messages, domainless addresses are automatically qualified with a
+configured domain value. Configuration options specify from which remote
+systems unqualified addresses are acceptable. These are then qualified on
+arrival.
+
+- cindex:[transport,external]
+cindex:[external transports]
+The only external transport currently implemented is an SMTP transport over a
+TCP/IP network (using sockets, including support for IPv6). However, a pipe
+transport is available, and there are facilities for writing messages to files
+and pipes, optionally in 'batched SMTP' format; these facilities can be used
+to send messages to some other transport mechanism such as UUCP, provided it
+can handle domain-style addresses. Batched SMTP input is also catered for.
+
+- Exim is not designed for storing mail for dial-in hosts. When the volumes of
+such mail are large, it is better to get the messages ``delivered'' into files
+(that is, off Exim's queue) and subsequently passed on to the dial-in hosts by
+other means.
+
+- Although Exim does have basic facilities for scanning incoming messages, these
+are not comprehensive enough to do full virus or spam scanning. Such operations
+are best carried out using additional specialized software packages. If you
+compile Exim with the content-scanning extension, straightforward interfaces to
+a number of common scanners are provided.
+
+
+
+
+
+Run time configuration
+~~~~~~~~~~~~~~~~~~~~~~
+Exim's run time configuration is held in a single text file that is divided
+into a number of sections. The entries in this file consist of keywords and
+values, in the style of Smail 3 configuration files. A default configuration
+file which is suitable for simple online installations is provided in the
+distribution, and is described in chapter <<CHAPdefconfil>> below.
+
+
+
+Calling interface
+~~~~~~~~~~~~~~~~~
+cindex:[Sendmail compatibility,command line interface]
+Like many MTAs, Exim has adopted the Sendmail command line interface so that it
+can be a straight replacement for _/usr/lib/sendmail_ or
+_/usr/sbin/sendmail_ when sending mail, but you do not need to know anything
+about Sendmail in order to run Exim. For actions other than sending messages,
+Sendmail-compatible options also exist, but those that produce output (for
+example, %-bp%, which lists the messages on the queue) do so in Exim's own
+format. There are also some additional options that are compatible with Smail
+3, and some further options that are new to Exim. Chapter <<CHAPcommandline>>
+documents all Exim's command line options. This information is automatically
+made into the man page that forms part of the Exim distribution.
+
+Control of messages on the queue can be done via certain privileged command
+line options. There is also an optional monitor program called 'eximon', which
+displays current information in an X window, and which contains a menu
+interface to Exim's command line administration options.
+
+
+
+Terminology
+~~~~~~~~~~~
+cindex:[terminology definitions]
+cindex:[body of message,definition of]
+The 'body' of a message is the actual data that the sender wants to transmit.
+It is the last part of a message, and is separated from the 'header' (see
+below) by a blank line.
+
+cindex:[bounce message,definition of]
+When a message cannot be delivered, it is normally returned to the sender in a
+delivery failure message or a ``non-delivery report'' (NDR). The term 'bounce'
+is commonly used for this action, and the error reports are often called
+'bounce messages'. This is a convenient shorthand for ``delivery failure error
+report''. Such messages have an empty sender address in the message's
+'envelope' (see below) to ensure that they cannot themselves give rise to
+further bounce messages.
+
+The term 'default' appears frequently in this manual. It is used to qualify a
+value which is used in the absence of any setting in the configuration. It may
+also qualify an action which is taken unless a configuration setting specifies
+otherwise.
+
+The term 'defer' is used when the delivery of a message to a specific
+destination cannot immediately take place for some reason (a remote host may be
+down, or a user's local mailbox may be full). Such deliveries are 'deferred'
+until a later time.
+
+The word 'domain' is sometimes used to mean all but the first component of a
+host's name. It is 'not' used in that sense here, where it normally
+refers to the part of an email address following the @ sign.
+
+cindex:[envelope, definition of]
+cindex:[sender,definition of]
+A message in transit has an associated 'envelope', as well as a header and a
+body. The envelope contains a sender address (to which bounce messages should
+be delivered), and any number of recipient addresses. References to the
+sender or the recipients of a message usually mean the addresses in the
+envelope. An MTA uses these addresses for delivery, and for returning bounce
+messages, not the addresses that appear in the header lines.
+
+cindex:[message header, definition of]
+cindex:[header section,definition of]
+The 'header' of a message is the first part of a message's text, consisting
+of a number of lines, each of which has a name such as 'From:', 'To:',
+'Subject:', etc. Long header lines can be split over several text lines by
+indenting the continuations. The header is separated from the body by a blank
+line.
+
+cindex:[local part,definition of]
+cindex:[domain,definition of]
+The term 'local part', which is taken from RFC 2822, is used to refer to that
+part of an email address that precedes the @ sign. The part that follows the
+@ sign is called the 'domain' or 'mail domain'.
+
+cindex:[local delivery,definition of]
+cindex:[remote delivery, definition of]
+The terms 'local delivery' and 'remote delivery' are used to distinguish
+delivery to a file or a pipe on the local host from delivery by SMTP over
+TCP/IP to a remote host.
+
+cindex:[return path,definition of]
+'Return path' is another name that is used for the sender address in a
+message's envelope.
+
+cindex:[queue,definition of]
+The term 'queue' is used to refer to the set of messages awaiting delivery,
+because this term is in widespread use in the context of MTAs. However, in
+Exim's case the reality is more like a pool than a queue, because there is
+normally no ordering of waiting messages.
+
+cindex:[queue runner,definition of]
+The term 'queue runner' is used to describe a process that scans the queue
+and attempts to deliver those messages whose retry times have come. This term
+is used by other MTAs, and also relates to the command %runq%, but in Exim
+the waiting messages are normally processed in an unpredictable order.
+
+cindex:[spool directory,definition of]
+The term 'spool directory' is used for a directory in which Exim keeps the
+messages on its queue -- that is, those that it is in the process of
+delivering. This should not be confused with the directory in which local
+mailboxes are stored, which is called a ``spool directory'' by some people. In
+the Exim documentation, ``spool'' is always used in the first sense.
+
+
+
+
+
+
+////////////////////////////////////////////////////////////////////////////
+////////////////////////////////////////////////////////////////////////////
+
+Incorporated code
+-----------------
+cindex:[incorporated code]
+cindex:[regular expressions,library]
+cindex:[PCRE]
+A number of pieces of external code are included in the Exim distribution.
+
+- Regular expressions are supported in the main Exim program and in the Exim
+monitor using the freely-distributable PCRE library, copyright (c) University
+of Cambridge. The source is distributed in the directory _src/pcre_. However,
+this is a cut-down version of PCRE. If you want to use the PCRE library in
+other programs, you should obtain and install the full version from
+*ftp://ftp.csx.cam.ac.uk/pub/software/programming/pcre[]*.
+
+- cindex:[cdb,acknowledgement]
+Support for the cdb (Constant DataBase) lookup method is provided by code
+contributed by Nigel Metheringham of (at the time he contributed it) Planet
+Online Ltd. which contains the following statements:
++
+Copyright (c) 1998 Nigel Metheringham, Planet Online Ltd
++
+This program is free software; you can redistribute it and/or modify it under
+the terms of the GNU General Public License as published by the Free Software
+Foundation; either version 2 of the License, or (at your option) any later
+version.
++
+This code implements Dan Bernstein's Constant DataBase (cdb) spec. Information,
+the spec and sample code for cdb can be obtained from
+*http://www.pobox.com/{tl}djb/cdb.html[]*. This implementation borrows some code
+from Dan Bernstein's implementation (which has no license restrictions applied
+to it).
++
+The implementation is completely contained within the code of Exim.
+It does not link against an external cdb library.
+
+- cindex:[SPA authentication]
+cindex:[Samba project]
+cindex:[Microsoft Secure Password Authentication]
+Client support for Microsoft's 'Secure Password Authentication' is provided
+by code contributed by Marc Prud'hommeaux. Server support was contributed by
+Tom Kistner. This includes code taken from the Samba project, which is released
+under the Gnu GPL.
+
+- cindex:[Cyrus]
+cindex:['pwcheck' daemon]
+cindex:['pwauthd' daemon]
+Support for calling the Cyrus 'pwcheck' and 'saslauthd' daemons is provided
+by code taken from the Cyrus-SASL library and adapted by Alexander S.
+Sabourenkov. The permission notice appears below, in accordance with the
+conditions expressed therein.
++
+Copyright (c) 2001 Carnegie Mellon University.  All rights reserved.
++
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions
+are met:
++
+. Redistributions of source code must retain the above copyright
+notice, this list of conditions and the following disclaimer.
+
+. Redistributions in binary form must reproduce the above copyright
+notice, this list of conditions and the following disclaimer in
+the documentation and/or other materials provided with the
+distribution.
+
+. The name ``Carnegie Mellon University'' must not be used to
+endorse or promote products derived from this software without
+prior written permission. For permission or any other legal
+details, please contact
++
+&&&
+Office of Technology Transfer
+Carnegie Mellon University
+5000 Forbes Avenue
+Pittsburgh, PA  15213-3890
+(412) 268-4387, fax: (412) 268-7395
+tech-transfer@andrew.cmu.edu
+&&&
+
+. Redistributions of any form whatsoever must retain the following
+acknowledgment:
++
+'This product includes software developed by Computing Services
+at Carnegie Mellon University (*http://www.cmu.edu/computing/[]*).'
++
+CARNEGIE MELLON UNIVERSITY DISCLAIMS ALL WARRANTIES WITH REGARD TO
+THIS SOFTWARE, INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY
+AND FITNESS, IN NO EVENT SHALL CARNEGIE MELLON UNIVERSITY BE LIABLE
+FOR ANY SPECIAL, INDIRECT OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
+WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN
+AN ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING
+OUT OF OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
+
+. cindex:[monitor]
+cindex:[X-windows]
+cindex:[Athena]
+The Exim Monitor program, which is an X-Window application, includes
+modified versions of the Athena StripChart and TextPop widgets.
+This code is copyright by DEC and MIT, and their permission notice appears
+below, in accordance with the conditions expressed therein.
++
+Copyright 1987, 1988 by Digital Equipment Corporation, Maynard, Massachusetts,
+and the Massachusetts Institute of Technology, Cambridge, Massachusetts.
++
+All Rights Reserved
++
+Permission to use, copy, modify, and distribute this software and its
+documentation for any purpose and without fee is hereby granted,
+provided that the above copyright notice appear in all copies and that
+both that copyright notice and this permission notice appear in
+supporting documentation, and that the names of Digital or MIT not be
+used in advertising or publicity pertaining to distribution of the
+software without specific, written prior permission.
++
+DIGITAL DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS SOFTWARE, INCLUDING
+ALL IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS, IN NO EVENT SHALL
+DIGITAL BE LIABLE FOR ANY SPECIAL, INDIRECT OR CONSEQUENTIAL DAMAGES OR
+ANY DAMAGES WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS,
+WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION,
+ARISING OUT OF OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS
+SOFTWARE.
+
+. Many people have contributed code fragments, some large, some small, that were
+not covered by any specific licence requirements. It is assumed that the
+contributors are happy to see their code incoporated into Exim under the GPL.
+
+
+
+
+
+////////////////////////////////////////////////////////////////////////////
+////////////////////////////////////////////////////////////////////////////
+
+[titleabbrev="Receiving and delivering mail"]
+How Exim receives and delivers mail
+-----------------------------------
+
+
+Overall philosophy
+~~~~~~~~~~~~~~~~~~
+cindex:[design philosophy]
+Exim is designed to work efficiently on systems that are permanently connected
+to the Internet and are handling a general mix of mail. In such circumstances,
+most messages can be delivered immediately. Consequently, Exim does not
+maintain independent queues of messages for specific domains or hosts, though
+it does try to send several messages in a single SMTP connection after a host
+has been down, and it also maintains per-host retry information.
+
+
+
+Policy control
+~~~~~~~~~~~~~~
+cindex:[policy control,overview]
+Policy controls are now an important feature of MTAs that are connected to the
+Internet. Perhaps their most important job is to stop MTAs being abused as
+``open relays'' by misguided individuals who send out vast amounts of unsolicited
+junk, and want to disguise its source. Exim provides flexible facilities for
+specifying policy controls on incoming mail:
+
+- cindex:[{ACL},introduction]
+Exim 4 (unlike previous versions of Exim) implements policy controls on
+incoming mail by means of 'Access Control Lists' (ACLs). Each list is a
+series of statements that may either grant or deny access. ACLs can be used at
+several places in the SMTP dialogue while receiving a message from a remote
+host. However, the most common places are after each RCPT command, and at
+the very end of the message. The sysadmin can specify conditions for accepting
+or rejecting individual recipients or the entire message, respectively, at
+these two points (see chapter <<CHAPACL>>). Denial of access results in an SMTP
+error code.
+
+- An ACL is also available for locally generated, non-SMTP messages. In this
+case, the only available actions are to accept or deny the entire message.
+
+- When Exim is compiled with the content-scanning extension, facilities are
+provided in the ACL mechanism for passing the message to external virus and/or
+spam scanning software. The result of such a scan is passed back to the ACL,
+which can then use it to decide what to do with the message.
+
+- When a message has been received, either from a remote host or from the local
+host, but before the final acknowledgement has been sent, a locally supplied C
+function called 'local_scan()' can be run to inspect the message and decide
+whether to accept it or not (see chapter <<CHAPlocalscan>>). If the message is
+accepted, the list of recipients can be modified by the function.
+
+- Using the 'local_scan()' mechanism is another way of calling external
+scanner software. The %SA-Exim% add-on package works this way. It does not
+require Exim to be compiled with the content-scanning extension.
+
+- After a message has been accepted, a further checking mechanism is available in
+the form of the 'system filter' (see chapter <<CHAPsystemfilter>>). This runs
+at the start of every delivery process.
+
+
+
+User filters
+~~~~~~~~~~~~
+cindex:[filter,introduction]
+cindex:[Sieve filter]
+In a conventional Exim configuration, users are able to run private filters by
+setting up appropriate _.forward_ files in their home directories. See
+chapter <<CHAPredirect>> (about the ^redirect^ router) for the configuration
+needed to support this, and the separate document entitled 'Exim's interfaces
+to mail filtering' for user details. Two different kinds of filtering are
+available:
+
+- Sieve filters are written in the standard filtering language that is defined
+by RFC 3028.
+
+- Exim filters are written in a syntax that is unique to Exim, but which is more
+powerful than Sieve, which it pre-dates.
+
+User filters are run as part of the routing process, described below.
+
+
+
+[[SECTmessiden]]
+Message identification
+~~~~~~~~~~~~~~~~~~~~~~
+cindex:[message ids, details of format]
+cindex:[format,of message id]
+cindex:[id of message]
+cindex:[base62]
+cindex:[base36]
+cindex:[Darwin]
+cindex:[Cygwin]
+Every message handled by Exim is given a 'message id' which is sixteen
+characters long. It is divided into three parts, separated by hyphens, for
+example `16VDhn-0001bo-D3`. Each part is a sequence of letters and digits,
+normally encoding numbers in base 62. However, in the Darwin operating
+system (Mac OS X) and when Exim is compiled to run under Cygwin, base 36
+(avoiding the use of lower case letters) is used instead, because the message
+id is used to construct file names, and the names of files in those systems are
+not case-sensitive.
+
+cindex:[pid (process id),re-use of]
+The detail of the contents of the message id have changed as Exim has evolved.
+Earlier versions relied on the operating system not re-using a process id (pid)
+within one second. On modern operating systems, this assumption can no longer
+be made, so the algorithm had to be changed. To retain backward compatibility,
+the format of the message id was retained, which is why the following rules are
+somewhat eccentric:
+
+- The first six characters of the message id are the time at which the message
+started to be received, to a granularity of one second. That is, this field
+contains the number of seconds since the start of the epoch (the normal Unix
+way of representing the date and time of day).
+
+- After the first hyphen, the next six characters are the id of the process that
+received the message.
+
+- There are two different possibilities for the final two characters:
+
+. cindex:[%localhost_number%]
+If %localhost_number% is not set, this value is the fractional part of the
+time of reception, normally in units of 1/2000 of a second, but for systems
+that must use base 36 instead of base 62 (because of case-insensitive file
+systems), the units are 1/1000 of a second.
+
+. If %localhost_number% is set, it is multiplied by 200 (100) and added to
+the fractional part of the time, which in this case is in units of 1/200
+(1/100) of a second.
+
+After a message has been received, Exim waits for the clock to tick at the
+appropriate resolution before proceeding, so that if another message is
+received by the same process, or by another process with the same (re-used)
+pid, it is guaranteed that the time will be different. In most cases, the clock
+will already have ticked while the message was being received.
+
+
+Receiving mail
+~~~~~~~~~~~~~~
+cindex:[receiving mail]
+cindex:[message,reception]
+The only way Exim can receive mail from a remote host is using SMTP over
+TCP/IP, in which case the sender and recipient addresses are tranferred using
+SMTP commands. However, from a locally running process (such as a user's MUA),
+there are several possibilities:
+
+- If the process runs Exim with the %-bm% option, the message is read
+non-interactively (usually via a pipe), with the recipients taken from the
+command line, or from the body of the message if %-t% is also used.
+
+- If the process runs Exim with the %-bS% option, the message is also read
+non-interactively, but in this case the recipients are listed at the start of
+the message in a series of SMTP RCPT commands, terminated by a DATA
+command. This is so-called ``batch SMTP'' format,
+but it isn't really SMTP. The SMTP commands are just another way of passing
+envelope addresses in a non-interactive submission.
+
+- If the process runs Exim with the %-bs% option, the message is read
+interactively, using the SMTP protocol. A two-way pipe is normally used for
+passing data between the local process and the Exim process.
+This is ``real'' SMTP and is handled in the same way as SMTP over TCP/IP. For
+example, the ACLs for SMTP commands are used for this form of submission.
+
+- A local process may also make a TCP/IP call to the host's loopback address
+(127.0.0.1) or any other of its IP addresses. When receiving messages, Exim
+does not treat the loopback address specially. It treats all such connections
+in the same way as connections from other hosts.
+
+
+cindex:[message sender, constructed by Exim]
+cindex:[sender,constructed by Exim]
+In the three cases that do not involve TCP/IP, the sender address is
+constructed from the login name of the user that called Exim and a default
+qualification domain (which can be set by the %qualify_domain% configuration
+option). For local or batch SMTP, a sender address that is passed using the
+SMTP MAIL command is ignored. However, the system administrator may allow
+certain users (``trusted users'') to specify a different sender address
+unconditionally, or all users to specify certain forms of different sender
+address. The %-f% option or the SMTP MAIL command is used to specify these
+different addresses. See section <<SECTtrustedadmin>> for details of trusted
+users, and the %untrusted_set_sender% option for a way of allowing untrusted
+users to change sender addresses.
+
+Messages received by either of the non-interactive mechanisms are subject to
+checking by the non-SMTP ACL, if one is defined. Messages received using SMTP
+(either over TCP/IP, or interacting with a local process) can be checked by a
+number of ACLs that operate at different times during the SMTP session. Either
+individual recipients, or the entire message, can be rejected if local policy
+requirements are not met. The 'local_scan()' function (see chapter
+<<CHAPlocalscan>>) is run for all incoming messages.
+
+Exim can be configured not to start a delivery process when a message is
+received; this can be unconditional, or depend on the number of incoming SMTP
+connections or the system load. In these situations, new messages wait on the
+queue until a queue runner process picks them up. However, in standard
+configurations under normal conditions, delivery is started as soon as a
+message is received.
+
+
+
+
+
+Handling an incoming message
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+cindex:[spool directory,files that hold a message]
+cindex:[file,how a message is held]
+When Exim accepts a message, it writes two files in its spool directory. The
+first contains the envelope information, the current status of the message, and
+the header lines, and the second contains the body of the message. The names of
+the two spool files consist of the message id, followed by `-H` for the
+file containing the envelope and header, and `-D` for the data file.
+
+cindex:[spool directory,_input_ sub-directory]
+By default all these message files are held in a single directory called
+_input_ inside the general Exim spool directory. Some operating systems do
+not perform very well if the number of files in a directory gets very large; to
+improve performance in such cases, the %split_spool_directory% option can be
+used. This causes Exim to split up the input files into 62 sub-directories
+whose names are single letters or digits.
+
+The envelope information consists of the address of the message's sender and
+the addresses of the recipients. This information is entirely separate from
+any addresses contained in the header lines. The status of the message includes
+a list of recipients who have already received the message. The format of the
+first spool file is described in chapter <<CHAPspool>>.
+
+cindex:[rewriting,addresses]
+Address rewriting that is specified in the rewrite section of the configuration
+(see chapter <<CHAPrewrite>>) is done once and for all on incoming addresses,
+both in the header lines and the envelope, at the time the message is accepted.
+If during the course of delivery additional addresses are generated (for
+example, via aliasing), these new addresses are rewritten as soon as they are
+generated. At the time a message is actually delivered (transported) further
+rewriting can take place; because this is a transport option, it can be
+different for different forms of delivery. It is also possible to specify the
+addition or removal of certain header lines at the time the message is
+delivered (see chapters <<CHAProutergeneric>> and <<CHAPtransportgeneric>>).
+
+
+
+Life of a message
+~~~~~~~~~~~~~~~~~
+cindex:[message,life of]
+cindex:[message,frozen]
+A message remains in the spool directory until it is completely delivered to
+its recipients or to an error address, or until it is deleted by an
+administrator or by the user who originally created it. In cases when delivery
+cannot proceed -- for example, when a message can neither be delivered to its
+recipients nor returned to its sender, the message is marked ``frozen'' on the
+spool, and no more deliveries are attempted.
+
+cindex:[frozen messages,thawing]
+cindex:[message,thawing frozen]
+An administrator can ``thaw'' such messages when the problem has been corrected,
+and can also freeze individual messages by hand if necessary. In addition, an
+administrator can force a delivery error, causing a bounce message to be sent.
+
+cindex:[%auto_thaw%]
+There is an option called %auto_thaw%, which can be used to cause Exim to
+retry frozen messages after a certain time. When this is set, no message will
+remain on the queue for ever, because the delivery timeout will eventually be
+reached. Delivery failure reports (bounce messages) that reach this timeout are
+discarded.
+
+cindex:[%timeout_frozen_after%]
+There is also an option called %timeout_frozen_after%, which discards frozen
+messages after a certain time.
+
+cindex:[message,log file for]
+cindex:[log,file for each message]
+While Exim is working on a message, it writes information about each delivery
+attempt to the main log file. This includes successful, unsuccessful, and
+delayed deliveries for each recipient (see chapter <<CHAPlog>>). The log lines
+are also written to a separate 'message log' file for each message. These
+logs are solely for the benefit of the administrator, and are normally deleted
+along with the spool files when processing of a message is complete.
+The use of individual message logs can be disabled by setting
+%no_message_logs%; this might give an improvement in performance on very
+busy systems.
+
+cindex:[journal file]
+cindex:[file,journal]
+All the information Exim itself needs to set up a delivery is kept in the first
+spool file, along with the header lines. When a successful delivery occurs, the
+address is immediately written at the end of a journal file, whose name is the
+message id followed by `-J`. At the end of a delivery run, if there are some
+addresses left to be tried again later, the first spool file (the `-H` file)
+is updated to indicate which these are, and the journal file is then deleted.
+Updating the spool file is done by writing a new file and renaming it, to
+minimize the possibility of data loss.
+
+Should the system or the program crash after a successful delivery but before
+the spool file has been updated, the journal is left lying around. The next
+time Exim attempts to deliver the message, it reads the journal file and
+updates the spool file before proceeding. This minimizes the chances of double
+deliveries caused by crashes.
+
+
+
+[[SECTprocaddress]]
+Processing an address for delivery
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+cindex:[drivers,definition of]
+cindex:[router,definition of]
+cindex:[transport,definition of]
+The main delivery processing elements of Exim are called 'routers' and
+'transports', and collectively these are known as 'drivers'. Code for a
+number of them is provided in the source distribution, and compile-time options
+specify which ones are included in the binary. Run time options specify which
+ones are actually used for delivering messages.
+
+cindex:[drivers,instance definition]
+Each driver that is specified in the run time configuration is an 'instance'
+of that particular driver type. Multiple instances are allowed; for example,
+you can set up several different ^smtp^ transports, each with different
+option values that might specify different ports or different timeouts. Each
+instance has its own identifying name. In what follows we will normally use the
+instance name when discussing one particular instance (that is, one specific
+configuration of the driver), and the generic driver name when discussing
+the driver's features in general.
+
+A 'router' is a driver that operates on an address, either determining how
+its delivery should happen, by routing it to a specific transport, or
+converting the address into one or more new addresses (for example, via an
+alias file). A router may also explicitly choose to fail an address, causing it
+to be bounced.
+
+A 'transport' is a driver that transmits a copy of the message from Exim's
+spool to some destination. There are two kinds of transport: for a 'local'
+transport, the destination is a file or a pipe on the local host, whereas for a
+'remote' transport the destination is some other host. A message is passed
+to a specific transport as a result of successful routing. If a message has
+several recipients, it may be passed to a number of different transports.
+
+cindex:[preconditions,definition of]
+An address is processed by passing it to each configured router instance in
+turn, subject to certain preconditions, until a router accepts the address or
+specifies that it should be bounced. We will describe this process in more
+detail shortly. As a simple example, the diagram below illustrates how each
+recipient address in a message is processed in a small configuration of three
+routers that are configured in various ways.
+
+To make this a more concrete example, we'll describe it in terms of some actual
+routers, but remember, this is only an example. You can configure Exim's
+routers in many different ways, and there may be any number of routers in a
+configuration.
+
+The first router that is specified in a configuration is often one that handles
+addresses in domains that are not recognized specially by the local host. These
+are typically addresses for arbitrary domains on the Internet. A precondition
+is set up which looks for the special domains known to the host (for example,
+its own domain name), and the router is run for addresses that do 'not'
+match. Typically, this is a router that looks up domains in the DNS in order to
+find the hosts to which this address routes. If it succeeds, the address is
+queued for a suitable SMTP transport; if it does not succeed, the router is
+configured to fail the address.
+
+///
+The example pictured could be a configuration of this type. The second and
+third routers can only be run for addresses for which the preconditions for
+the first router are not met. If one of these preconditions checks the
+domain, the second and third routers are run only for domains that are somehow
+special to the local host.
+///
+
+The second router does redirection -- also known as aliasing and forwarding.
+When it generates one or more new addresses from the original, each of them is
+routed independently from the start. Otherwise, the router may cause an address
+to fail, or it may simply decline to handle the address, in which case the
+address is passed to the next router.
+
+The final router in many configurations is one that checks to see if the
+address belongs to a local mailbox. The precondition may involve a check to
+see if the local part is the name of a login account, or it may look up the
+local part in a file or a database. If its preconditions are not met, or if
+the router declines, we have reached the end of the routers. When this happens,
+the address is bounced.
+
+
+
+Processing an address for verification
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+cindex:[router,for verification]
+cindex:[verifying address, overview]
+As well as being used to decide how to deliver to an address, Exim's routers
+are also used for 'address verification'. Verification can be requested as
+one of the checks to be performed in an ACL for incoming messages, on both
+sender and recipient addresses, and it can be tested using the %-bv% and
+%-bvs% command line options.
+
+When an address is being verified, the routers are run in ``verify mode''. This
+does not affect the way the routers work, but it is a state that can be
+detected. By this means, a router can be skipped or made to behave differently
+when verifying. A common example is a configuration in which the first router
+sends all messages to a message-scanning program, unless they have been
+previously scanned. Thus, the first router accepts all addresses without any
+checking, making it useless for verifying. Normally, the %no_verify% option
+would be set for such a router, causing it to be skipped in verify mode.
+
+
+
+
+[[SECTrunindrou]]
+Running an individual router
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+cindex:[router,running details]
+cindex:[preconditions,checking]
+cindex:[router,result of running]
+As explained in the example above, a number of preconditions are checked before
+running a router. If any are not met, the router is skipped, and the address is
+passed to the next router. When all the preconditions on a router 'are' met,
+the router is run. What happens next depends on the outcome, which is one of
+the following:
+
+- 'accept': The router accepts the address, and either queues it for a
+transport, or generates one or more ``child'' addresses. Processing the original
+address ceases,
+cindex:[%unseen% option]
+unless the %unseen% option is set on the router. This option
+can be used to set up multiple deliveries with different routing (for example,
+for keeping archive copies of messages). When %unseen% is set, the address is
+passed to the next router. Normally, however, an 'accept' return marks the
+end of routing.
++
+cindex:[case of local parts]
+cindex:[address duplicate, discarding]
+If child addresses are generated, Exim checks to see whether they are
+duplicates of any existing recipient addresses. During this check, local parts
+are treated as case-sensitive. Duplicate addresses are discarded. Each of the
+remaining child addresses is then processed independently, starting with the
+first router by default. It is possible to change this by setting the
+%redirect_router% option to specify which router to start at for child
+addresses. Unlike %pass_router% (see below) the router specified by
+%redirect_router% may be anywhere in the router configuration.
+
+- 'pass': The router recognizes the address, but cannot handle it itself. It
+requests that the address be passed to another router. By default the address
+is passed to the next router, but this can be changed by setting the
+%pass_router% option. However, (unlike %redirect_router%) the named router
+must be below the current router (to avoid loops).
+
+- 'decline': The router declines to accept the address because it does not
+recognize it at all. By default, the address is passed to the next router, but
+this can be prevented by setting the %no_more% option. When %no_more% is set,
+all the remaining routers are skipped.
+
+- 'fail': The router determines that the address should fail, and queues it for
+the generation of a bounce message. There is no further processing of the
+original address unless %unseen% is set on the router.
+
+- 'defer': The router cannot handle the address at the present time. (A database
+may be offline, or a DNS lookup may have timed out.) No further processing of
+the address happens in this delivery attempt. It is tried again next time the
+message is considered for delivery.
+
+- 'error': There is some error in the router (for example, a syntax error in
+its configuration). The action is as for defer.
+
+If an address reaches the end of the routers without having been accepted by
+any of them, it is bounced as unrouteable.
+The default error message in this situation is ``unrouteable address'', but you
+can set your own message by making use of the %cannot_route_message% option.
+This can be set for any router; the value from the last router that ``saw''
+the address is used.
+
+Sometimes while routing you want to fail a delivery when some conditions are
+met but others are not, instead of passing the address on for further routing.
+You can do this by having a second router that explicitly fails the delivery
+when the relevant conditions are met. The ^redirect^ router has a ``fail''
+facility for this purpose.
+
+
+
+
+[[SECTrouprecon]]
+Router preconditions
+~~~~~~~~~~~~~~~~~~~~
+cindex:[router preconditions, order of processing]
+cindex:[preconditions,order of processing]
+The preconditions that are tested for each router are listed below, in the
+order in which they are tested. The individual configuration options are
+described in more detail in chapter <<CHAProutergeneric>>.
+
+- The %local_part_prefix% and %local_part_suffix% options can specify that
+the local parts handled by the router may or must have certain prefixes and/or
+suffixes. If a mandatory affix (prefix or suffix) is not present, the router is
+skipped. These conditions are tested first. When an affix is present, it is
+removed from the local part before further processing, including the evaluation
+of any other conditions.
+
+- Routers can be designated for use only when not verifying an address, that is,
+only when routing it for delivery (or testing its delivery routing). If the
+%verify% option is set false, the router is skipped when Exim is verifying an
+address.
+Setting the %verify% option actually sets two options, %verify_sender% and
+%verify_recipient%, which independently control the use of the router for
+sender and recipient verification. You can set these options directly if
+you want a router to be used for only one type of verification.
+
+- If the %address_test% option is set false, the router is skipped when Exim is
+run with the %-bt% option to test an address routing. This can be helpful when
+the first router sends all new messages to a scanner of some sort; it makes it
+possible to use %-bt% to test subsequent delivery routing without having to
+simulate the effect of the scanner.
+
+- Routers can be designated for use only when verifying an address, as
+opposed to routing it for delivery. The %verify_only% option controls this.
+
+- Certain routers can be explicitly skipped when running the routers to check an
+address given in the SMTP EXPN command (see the %expn% option).
+
+- If the %domains% option is set, the domain of the address must be in the set of
+domains that it defines.
+
+- If the %local_parts% option is set, the local part of the address must be in
+the set of local parts that it defines. If %local_part_prefix% or
+%local_part_suffix% is in use, the prefix or suffix is removed from the local
+part before this check. If you want to do precondition tests on local parts
+that include affixes, you can do so by using a %condition% option (see below)
+that uses the variables $local_part$, $local_part_prefix$, and
+$local_part_suffix$ as necessary.
+
+- If the %check_local_user% option is set, the local part must be the name of
+an account on the local host.
+If this check succeeds, the uid and gid of the local user are placed in
+$local_user_uid$ and $local_user_gid$; these values can be used in the
+remaining preconditions.
+
+- If the %router_home_directory% option is set, it is expanded at this point,
+because it overrides the value of $home$. If this expansion were left till
+later, the value of $home$ as set by %check_local_user% would be used in
+subsequent tests. Having two different values of $home$ in the same router
+could lead to confusion.
+
+- If the %senders% option is set, the envelope sender address must be in the set
+of addresses that it defines.
+
+- If the %require_files% option is set, the existence or non-existence of
+specified files is tested.
+
+- cindex:[customizing,precondition]
+If the %condition% option is set, it is evaluated and tested. This option uses
+an expanded string to allow you to set up your own custom preconditions.
+Expanded strings are described in chapter <<CHAPexpand>>.
+
+
+Note that %require_files% comes near the end of the list, so you cannot use it
+to check for the existence of a file in which to lookup up a domain, local
+part, or sender. However, as these options are all expanded, you can use the
+%exists% expansion condition to make such tests within each condition. The
+%require_files% option is intended for checking files that the router may be
+going to use internally, or which are needed by a specific transport (for
+example, _.procmailrc_).
+
+
+
+Delivery in detail
+~~~~~~~~~~~~~~~~~~
+cindex:[delivery,in detail]
+When a message is to be delivered, the sequence of events is as follows:
+
+- If a system-wide filter file is specified, the message is passed to it. The
+filter may add recipients to the message, replace the recipients, discard the
+message, cause a new message to be generated, or cause the message delivery to
+fail. The format of the system filter file is the same as for Exim user filter
+files, described in the separate document entitled
+'Exim's interfaces to mail filtering'.
+cindex:[Sieve filter,not available for system filter]
+(*Note*: Sieve cannot be used for system filter files.)
++
+Some additional features are available in system filters -- see chapter
+<<CHAPsystemfilter>> for details. Note that a message is passed to the system
+filter only once per delivery attempt, however many recipients it has. However,
+if there are several delivery attempts because one or more addresses could not
+be immediately delivered, the system filter is run each time. The filter
+condition %first_delivery% can be used to detect the first run of the system
+filter.
+
+- Each recipient address is offered to each configured router in turn, subject
+to its preconditions, until one is able to handle it. If no router can handle
+the address, that is, if they all decline, the address is failed. Because
+routers can be targeted at particular domains, several locally handled domains
+can be processed entirely independently of each other.
+
+- cindex:[routing,loops in]
+cindex:[loop,while routing]
+A router that accepts an address may set up a local or a remote transport for
+it. However, the transport is not run at this time. Instead, the address is
+placed on a list for the particular transport, to be run later. Alternatively,
+the router may generate one or more new addresses (typically from alias,
+forward, or filter files). New addresses are fed back into this process from
+the top, but in order to avoid loops, a router ignores any address which has an
+identically-named ancestor that was processed by itself.
+
+- When all the routing has been done, addresses that have been successfully
+handled are passed to their assigned transports. When local transports are
+doing real local deliveries, they handle only one address at a time, but if a
+local transport is being used as a pseudo-remote transport (for example, to
+collect batched SMTP messages for transmission by some other means) multiple
+addresses can be handled. Remote transports can always handle more than one
+address at a time, but can be configured not to do so, or to restrict multiple
+addresses to the same domain.
+
+- Each local delivery to a file or a pipe runs in a separate process under a
+non-privileged uid, and these deliveries are run one at a time. Remote
+deliveries also run in separate processes, normally under a uid that is private
+to Exim (``the Exim user''), but in this case, several remote deliveries can be
+run in parallel. The maximum number of simultaneous remote deliveries for any
+one message is set by the %remote_max_parallel% option.
+The order in which deliveries are done is not defined, except that all local
+deliveries happen before any remote deliveries.
+
+- cindex:[queue runner]
+When it encounters a local delivery during a queue run, Exim checks its retry
+database to see if there has been a previous temporary delivery failure for the
+address before running the local transport. If there was a previous failure,
+Exim does not attempt a new delivery until the retry time for the address is
+reached. However, this happens only for delivery attempts that are part of a
+queue run. Local deliveries are always attempted when delivery immediately
+follows message reception, even if retry times are set for them. This makes for
+better behaviour if one particular message is causing problems (for example,
+causing quota overflow, or provoking an error in a filter file).
+
+- cindex:[delivery,retry in remote transports]
+Remote transports do their own retry handling, since an address may be
+deliverable to one of a number of hosts, each of which may have a different
+retry time. If there have been previous temporary failures and no host has
+reached its retry time, no delivery is attempted, whether in a queue run or
+not. See chapter <<CHAPretry>> for details of retry strategies.
+
+- If there were any permanent errors, a bounce message is returned to an
+appropriate address (the sender in the common case), with details of the error
+for each failing address. Exim can be configured to send copies of bounce
+messages to other addresses.
+
+- cindex:[delivery,deferral]
+If one or more addresses suffered a temporary failure, the message is left on
+the queue, to be tried again later. Delivery of these addresses is said to be
+'deferred'.
+
+- When all the recipient addresses have either been delivered or bounced,
+handling of the message is complete. The spool files and message log are
+deleted, though the message log can optionally be preserved if required.
+
+
+
+
+Retry mechanism
+~~~~~~~~~~~~~~~
+cindex:[delivery,retry mechanism]
+cindex:[retry,description of mechanism]
+cindex:[queue runner]
+Exim's mechanism for retrying messages that fail to get delivered at the first
+attempt is the queue runner process. You must either run an Exim daemon that
+uses the %-q% option with a time interval to start queue runners at regular
+intervals, or use some other means (such as 'cron') to start them. If you do
+not arrange for queue runners to be run, messages that fail temporarily at the
+first attempt will remain on your queue for ever. A queue runner process works
+it way through the queue, one message at a time, trying each delivery that has
+passed its retry time.
+You can run several queue runners at once.
+
+Exim uses a set of configured rules to determine when next to retry the failing
+address (see chapter <<CHAPretry>>). These rules also specify when Exim should
+give up trying to deliver to the address, at which point it generates a bounce
+message. If no retry rules are set for a particular host, address, and error
+combination, no retries are attempted, and temporary errors are treated as
+permanent.
+
+
+
+Temporary delivery failure
+~~~~~~~~~~~~~~~~~~~~~~~~~~
+cindex:[delivery,temporary failure]
+There are many reasons why a message may not be immediately deliverable to a
+particular address. Failure to connect to a remote machine (because it, or the
+connection to it, is down) is one of the most common. Temporary failures may be
+detected during routing as well as during the transport stage of delivery.
+Local deliveries may be delayed if NFS files are unavailable, or if a mailbox
+is on a file system where the user is over quota. Exim can be configured to
+impose its own quotas on local mailboxes; where system quotas are set they will
+also apply.
+
+If a host is unreachable for a period of time, a number of messages may be
+waiting for it by the time it recovers, and sending them in a single SMTP
+connection is clearly beneficial. Whenever a delivery to a remote host is
+deferred,
+
+cindex:[hints database]
+Exim makes a note in its hints database, and whenever a successful
+SMTP delivery has happened, it looks to see if any other messages are waiting
+for the same host. If any are found, they are sent over the same SMTP
+connection, subject to a configuration limit as to the maximum number in any
+one connection.
+
+
+
+
+Permanent delivery failure
+~~~~~~~~~~~~~~~~~~~~~~~~~~
+cindex:[delivery,permanent failure]
+cindex:[bounce message,when generated]
+When a message cannot be delivered to some or all of its intended recipients, a
+bounce message is generated. Temporary delivery failures turn into permanent
+errors when their timeout expires. All the addresses that fail in a given
+delivery attempt are listed in a single message. If the original message has
+many recipients, it is possible for some addresses to fail in one delivery
+attempt and others to fail subsequently, giving rise to more than one bounce
+message. The wording of bounce messages can be customized by the administrator.
+See chapter <<CHAPemsgcust>> for details.
+
+cindex:['X-Failed-Recipients:' header line]
+Bounce messages contain an 'X-Failed-Recipients:' header line that lists the
+failed addresses, for the benefit of programs that try to analyse such messages
+automatically.
+
+cindex:[bounce message,recipient of]
+A bounce message is normally sent to the sender of the original message, as
+obtained from the message's envelope. For incoming SMTP messages, this is the
+address given in the MAIL command. However, when an address is
+expanded via a forward or alias file, an alternative address can be specified
+for delivery failures of the generated addresses. For a mailing list expansion
+(see section <<SECTmailinglists>>) it is common to direct bounce messages to the
+manager of the list.
+
+
+
+
+Failures to deliver bounce messages
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+cindex:[bounce message,failure to deliver]
+If a bounce message (either locally generated or received from a remote host)
+itself suffers a permanent delivery failure, the message is left on the queue,
+but it is frozen, awaiting the attention of an administrator. There are options
+which can be used to make Exim discard such failed messages, or to keep them
+for only a short time (see %timeout_frozen_after% and
+%ignore_bounce_errors_after%).
+
+
+
+
+
+////////////////////////////////////////////////////////////////////////////
+////////////////////////////////////////////////////////////////////////////
+
+Building and installing Exim
+----------------------------
+
+cindex:[building Exim]
+
+Unpacking
+~~~~~~~~~
+Exim is distributed as a gzipped or bzipped tar file which, when upacked,
+creates a directory with the name of the current release (for example,
+_exim-{version}_) into which the following files are placed:
+
+[frame="none"]
+`--------------------`--------------------------------------------------------
+_ACKNOWLEDGMENTS_    contains some acknowledgments
+_CHANGES_            contains a reference to where changes are documented
+_LICENCE_            the GNU General Public Licence
+_Makefile_           top-level make file
+_NOTICE_             conditions for the use of Exim
+_README_             list of files, directories and simple build instructions
+------------------------------------------------------------------------------
+
+Other files whose names begin with _README_ may also be present. The
+following subdirectories are created:
+
+[frame="none"]
+`--------------------`------------------------------------------------
+_Local_              an empty directory for local configuration files
+_OS_                 OS-specific files
+_doc_                documentation files
+_exim_monitor_       source files for the Exim monitor
+_scripts_            scripts used in the build process
+_src_                remaining source files
+_util_               independent utilities
+----------------------------------------------------------------------
+
+The main utility programs are contained in the _src_ directory, and are built
+with the Exim binary. The _util_ directory contains a few optional scripts
+that may be useful to some sites.
+
+
+Multiple machine architectures and operating systems
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+cindex:[building Exim,multiple OS/architectures]
+The building process for Exim is arranged to make it easy to build binaries for
+a number of different architectures and operating systems from the same set of
+source files. Compilation does not take place in the _src_ directory. Instead,
+a 'build directory' is created for each architecture and operating system.
+
+cindex:[symbolic link,to build directory]
+Symbolic links to the sources are installed in this directory, which is where
+the actual building takes place.
+
+In most cases, Exim can discover the machine architecture and operating system
+for itself, but the defaults can be overridden if necessary.
+
+
+[[SECTdb]]
+DBM libraries
+~~~~~~~~~~~~~
+cindex:[DBM libraries, discussion of]
+cindex:[hints database,DBM files used for]
+Even if you do not use any DBM files in your configuration, Exim still needs a
+DBM library in order to operate, because it uses indexed files for its hints
+databases. Unfortunately, there are a number of DBM libraries in existence, and
+different operating systems often have different ones installed.
+
+cindex:[Solaris,DBM library for]
+cindex:[IRIX, DBM library for]
+cindex:[BSD, DBM library for]
+cindex:[Linux, DBM library for]
+If you are using Solaris, IRIX, one of the modern BSD systems, or a modern
+Linux distribution, the DBM configuration should happen automatically, and you
+may be able to ignore this section. Otherwise, you may have to learn more than
+you would like about DBM libraries from what follows.
+
+cindex:['ndbm' DBM library]
+Licensed versions of Unix normally contain a library of DBM functions operating
+via the 'ndbm' interface, and this is what Exim expects by default. Free
+versions of Unix seem to vary in what they contain as standard. In particular,
+some early versions of Linux have no default DBM library, and different
+distributors have chosen to bundle different libraries with their packaged
+versions. However, the more recent releases seem to have standardised on the
+Berkeley DB library.
+
+Different DBM libraries have different conventions for naming the files they
+use. When a program opens a file called _dbmfile_, there are four
+possibilities:
+
+. A traditional 'ndbm' implementation, such as that supplied as part of
+Solaris, operates on two files called _dbmfile.dir_ and _dbmfile.pag_.
+
+. cindex:['gdbm' DBM library]
+The GNU library, 'gdbm', operates on a single file. If used via its 'ndbm'
+compatibility interface it makes two different hard links to it with names
+_dbmfile.dir_ and _dbmfile.pag_, but if used via its native interface, the
+file name is used unmodified.
+
+. cindex:[Berkeley DB library]
+The Berkeley DB package, if called via its 'ndbm' compatibility interface,
+operates on a single file called _dbmfile.db_, but otherwise looks to the
+programmer exactly the same as the traditional 'ndbm' implementation.
+
+. If the Berkeley package is used in its native mode, it operates on a single
+file called _dbmfile_; the programmer's interface is somewhat different to
+the traditional 'ndbm' interface.
+
+. To complicate things further, there are several very different versions of the
+Berkeley DB package. Version 1.85 was stable for a very long time, releases
+2.'x' and 3.'x' were current for a while, but the latest versions are now
+numbered 4.'x'. Maintenance of some of the earlier releases has ceased. All
+versions of Berkeley DB can be obtained from
++
+&&&
+*http://www.sleepycat.com/[]*
+&&&
+
+. cindex:['tdb' DBM library]
+Yet another DBM library, called 'tdb', has become available from
++
+&&&
+*http://download.sourceforge.net/tdb[]*
+&&&
++
+It has its own interface, and also operates on a single file.
+
+cindex:[USE_DB]
+cindex:[DBM libraries, configuration for building]
+Exim and its utilities can be compiled to use any of these interfaces. In order
+to use any version of the Berkeley DB package in native mode, you must set
+USE_DB in an appropriate configuration file (typically
+_Local/Makefile_). For example:
+
+  USE_DB=yes
+
+Similarly, for gdbm you set USE_GDBM, and for tdb you set USE_TDB. An
+error is diagnosed if you set more than one of these.
+
+At the lowest level, the build-time configuration sets none of these options,
+thereby assuming an interface of type (1). However, some operating system
+configuration files (for example, those for the BSD operating systems and
+Linux) assume type (4) by setting USE_DB as their default, and the
+configuration files for Cygwin set USE_GDBM. Anything you set in
+_Local/Makefile_, however, overrides these system defaults.
+
+As well as setting USE_DB, USE_GDBM, or USE_TDB, it may also be
+necessary to set DBMLIB, to cause inclusion of the appropriate library, as
+in one of these lines:
+
+  DBMLIB = -ldb
+  DBMLIB = -ltdb
+
+Settings like that will work if the DBM library is installed in the standard
+place. Sometimes it is not, and the library's header file may also not be in
+the default path. You may need to set INCLUDE to specify where the header
+file is, and to specify the path to the library more fully in DBMLIB, as in
+this example:
+
+  INCLUDE=-I/usr/local/include/db-4.1
+  DBMLIB=/usr/local/lib/db-4.1/libdb.a
+
+
+There is further detailed discussion about the various DBM libraries in the
+file _doc/dbm.discuss.txt_ in the Exim distribution.
+
+
+
+Pre-building configuration
+~~~~~~~~~~~~~~~~~~~~~~~~~~
+cindex:[building Exim,pre-building configuration]
+cindex:[configuration for building Exim]
+cindex:[_Local/Makefile_]
+cindex:[_src/EDITME_]
+Before building Exim, a local configuration file that specifies options
+independent of any operating system has to be created with the name
+_Local/Makefile_. A template for this file is supplied as the file
+_src/EDITME_, and it contains full descriptions of all the option settings
+therein. These descriptions are therefore not repeated here. If you are
+building Exim for the first time, the simplest thing to do is to copy
+_src/EDITME_ to _Local/Makefile_, then read it and edit it appropriately.
+
+There are three settings that you must supply, because Exim will not build
+without them. They are the location of the run time configuration file
+(CONFIGURE_FILE), the directory in which Exim binaries will be installed
+(BIN_DIRECTORY), and the identity of the Exim user (EXIM_USER and
+maybe EXIM_GROUP as well). The value of CONFIGURE_FILE can in fact be
+a colon-separated list of file names; Exim uses the first of them that exists.
+
+There are a few other parameters that can be specified either at build time or
+at run time, to enable the same binary to be used on a number of different
+machines. However, if the locations of Exim's spool directory and log file
+directory (if not within the spool directory) are fixed, it is recommended that
+you specify them in _Local/Makefile_ instead of at run time, so that errors
+detected early in Exim's execution (such as a malformed configuration file) can
+be logged.
+
+cindex:[content scanning,specifying at build time]
+Exim's interfaces for calling virus and spam scanning sofware directly from
+access control lists are not compiled by default. If you want to include these
+facilities, you need to set
+
+  WITH_CONTENT_SCAN=yes
+
+in your _Local/Makefile_. For details of the facilities themselves, see
+chapter <<CHAPexiscan>>.
+
+
+cindex:[_Local/eximon.conf_]
+cindex:[_exim_monitor/EDITME_]
+If you are going to build the Exim monitor, a similar configuration process is
+required. The file _exim_monitor/EDITME_ must be edited appropriately for
+your installation and saved under the name _Local/eximon.conf_. If you are
+happy with the default settings described in _exim_monitor/EDITME_,
+_Local/eximon.conf_ can be empty, but it must exist.
+
+This is all the configuration that is needed in straightforward cases for known
+operating systems. However, the building process is set up so that it is easy
+to override options that are set by default or by operating-system-specific
+configuration files, for example to change the name of the C compiler, which
+defaults to %gcc%. See section <<SECToverride>> below for details of how to do
+this.
+
+
+
+Support for iconv()
+~~~~~~~~~~~~~~~~~~~
+cindex:['iconv()' support]
+The contents of header lines in messages may be encoded according to the rules
+described RFC 2047. This makes it possible to transmit characters that are not
+in the ASCII character set, and to label them as being in a particular
+character set. When Exim is inspecting header lines by means of the %\$h_%
+mechanism, it decodes them, and translates them into a specified character set
+(default ISO-8859-1). The translation is possible only if the operating system
+supports the 'iconv()' function.
+
+However, some of the operating systems that supply 'iconv()' do not support
+very many conversions. The GNU %libiconv% library (available from
+*http://www.gnu.org/software/libiconv/[]*) can be installed on such systems to
+remedy this deficiency, as well as on systems that do not supply 'iconv()' at
+all. After installing %libiconv%, you should add
+
+  HAVE_ICONV=yes
+
+to your _Local/Makefile_ and rebuild Exim.
+
+
+
+[[SECTinctlsssl]]
+Including TLS/SSL encryption support
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+cindex:[TLS,including support for TLS]
+cindex:[encryption,including support for]
+cindex:[SUPPORT_TLS]
+cindex:[OpenSSL,building Exim with]
+cindex:[GnuTLS,building Exim with]
+Exim can be built to support encrypted SMTP connections, using the STARTTLS
+command as per RFC 2487. It can also support legacy clients that expect to
+start a TLS session immediately on connection to a non-standard port (see the
+%tls_on_connect_ports% runtime option and the %-tls-on-connect% command
+line option).
+
+If you want to build Exim with TLS support, you must first install either the
+OpenSSL or GnuTLS library. There is no cryptographic code in Exim itself for
+implementing SSL.
+
+If OpenSSL is installed, you should set
+
+  SUPPORT_TLS=yes
+  TLS_LIBS=-lssl -lcrypto
+
+in _Local/Makefile_. You may also need to specify the locations of the
+OpenSSL library and include files. For example:
+
+  SUPPORT_TLS=yes
+  TLS_LIBS=-L/usr/local/openssl/lib -lssl -lcrypto
+  TLS_INCLUDE=-I/usr/local/openssl/include/
+
+cindex:[USE_GNUTLS]
+If GnuTLS is installed, you should set
+
+  SUPPORT_TLS=yes
+  USE_GNUTLS=yes
+  TLS_LIBS=-lgnutls -ltasn1 -lgcrypt
+
+in _Local/Makefile_, and again you may need to specify the locations of the
+library and include files. For example:
+
+  SUPPORT_TLS=yes
+  USE_GNUTLS=yes
+  TLS_LIBS=-L/usr/gnu/lib -lgnutls -ltasn1 -lgcrypt
+  TLS_INCLUDE=-I/usr/gnu/include
+
+You do not need to set TLS_INCLUDE if the relevant directory is already
+specified in INCLUDE. Details of how to configure Exim to make use of TLS
+are given in chapter <<CHAPTLS>>.
+
+
+
+
+Use of tcpwrappers
+~~~~~~~~~~~~~~~~~~
+cindex:[tcpwrappers, building Exim to support]
+cindex:[USE_TCP_WRAPPERS]
+Exim can be linked with the 'tcpwrappers' library in order to check incoming
+SMTP calls using the 'tcpwrappers' control files. This may be a convenient
+alternative to Exim's own checking facilities for installations that are
+already making use of 'tcpwrappers' for other purposes. To do this, you should
+set USE_TCP_WRAPPERS in _Local/Makefile_, arrange for the file
+_tcpd.h_ to be available at compile time, and also ensure that the library
+_libwrap.a_ is available at link time, typically by including %-lwrap% in
+EXTRALIBS_EXIM. For example, if 'tcpwrappers' is installed in
+_/usr/local_, you might have
+
+  USE_TCP_WRAPPERS=yes
+  CFLAGS=-O -I/usr/local/include
+  EXTRALIBS_EXIM=-L/usr/local/lib -lwrap
+
+in _Local/Makefile_. The name to use in the 'tcpwrappers' control files is
+``exim''. For example, the line
+
+  exim : LOCAL  192.168.1.  .friendly.domain.example
+
+in your _/etc/hosts.allow_ file allows connections from the local host, from
+the subnet 192.168.1.0/24, and from all hosts in 'friendly.domain.example'.
+All other connections are denied. Consult the 'tcpwrappers' documentation for
+further details.
+
+
+
+Including support for IPv6
+~~~~~~~~~~~~~~~~~~~~~~~~~~
+cindex:[IPv6,including support for]
+Exim contains code for use on systems that have IPv6 support. Setting
+`HAVE_IPV6=YES` in _Local/Makefile_ causes the IPv6 code to be included;
+it may also be necessary to set IPV6_INCLUDE and IPV6_LIBS on systems
+where the IPv6 support is not fully integrated into the normal include and
+library files.
+
+Two different types of DNS record for handling IPv6 addresses have been
+defined. AAAA records (analagous to A records for IPv4) are in use, and are
+currently seen as the mainstream. Another record type called A6 was proposed
+as better than AAAA because it had more flexibility. However, it was felt to be
+over-complex, and its status was reduced to ``experimental''. It is not known
+if anyone is actually using A6 records. Exim has support for A6 records, but
+this is included only if you set `SUPPORT_A6=YES` in _Local/Makefile_. The
+support has not been tested for some time.
+
+
+
+The building process
+~~~~~~~~~~~~~~~~~~~~
+cindex:[build directory]
+Once _Local/Makefile_ (and _Local/eximon.conf_, if required) have been
+created, run 'make' at the top level. It determines the architecture and
+operating system types, and creates a build directory if one does not exist.
+For example, on a Sun system running Solaris 8, the directory
+_build-SunOS5-5.8-sparc_ is created.
+cindex:[symbolic link,to source files]
+Symbolic links to relevant source files are installed in the build directory.
+
+*Warning*: The %-j% (parallel) flag must not be used with 'make'; the
+building process fails if it is set.
+
+If this is the first time 'make' has been run, it calls a script that builds
+a make file inside the build directory, using the configuration files from the
+_Local_ directory. The new make file is then passed to another instance of
+'make'. This does the real work, building a number of utility scripts, and
+then compiling and linking the binaries for the Exim monitor (if configured), a
+number of utility programs, and finally Exim itself. The command 'make
+makefile' can be used to force a rebuild of the make file in the build
+directory, should this ever be necessary.
+
+If you have problems building Exim, check for any comments there may be in the
+_README_ file concerning your operating system, and also take a look at the
+FAQ, where some common problems are covered.
+
+
+
+
+[[SECToverride]]
+Overriding build-time options for Exim
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+cindex:[build-time options, overriding]
+The main make file that is created at the beginning of the building process
+consists of the concatenation of a number of files which set configuration
+values, followed by a fixed set of 'make' instructions. If a value is set
+more than once, the last setting overrides any previous ones. This provides a
+convenient way of overriding defaults. The files that are concatenated are, in
+order:
+
+&&&
+_OS/Makefile-Default_
+_OS/Makefile-_<'ostype'>
+_Local/Makefile_
+_Local/Makefile-_<'ostype'>
+_Local/Makefile-_<'archtype'>
+_Local/Makefile-_<'ostype'>-<'archtype'>
+_OS/Makefile-Base_
+&&&
+
+cindex:[_Local/Makefile_]
+cindex:[building Exim,operating system type]
+cindex:[building Exim,architecture type]
+where <'ostype'> is the operating system type and <'archtype'> is the
+architecture type. _Local/Makefile_ is required to exist, and the building
+process fails if it is absent. The other three _Local_ files are optional,
+and are often not needed.
+
+The values used for <'ostype'> and <'archtype'> are obtained from scripts
+called _scripts/os-type_ and _scripts/arch-type_ respectively. If either of
+the environment variables EXIM_OSTYPE or EXIM_ARCHTYPE is set, their
+values are used, thereby providing a means of forcing particular settings.
+Otherwise, the scripts try to get values from the %uname% command. If this
+fails, the shell variables OSTYPE and ARCHTYPE are inspected. A number
+of 'ad hoc' transformations are then applied, to produce the standard names
+that Exim expects. You can run these scripts directly from the shell in order
+to find out what values are being used on your system.
+
+
+_OS/Makefile-Default_ contains comments about the variables that are set
+therein. Some (but not all) are mentioned below. If there is something that
+needs changing, review the contents of this file and the contents of the make
+file for your operating system (_OS/Makefile-<ostype>_) to see what the
+default values are.
+
+
+cindex:[building Exim,overriding default settings]
+If you need to change any of the values that are set in _OS/Makefile-Default_
+or in _OS/Makefile-<ostype>_, or to add any new definitions, you do not
+need to change the original files. Instead, you should make the changes by
+putting the new values in an appropriate _Local_ file. For example,
+cindex:[Tru64-Unix build-time settings]
+when building Exim in many releases of the Tru64-Unix (formerly Digital UNIX,
+formerly DEC-OSF1) operating system, it is necessary to specify that the C
+compiler is called 'cc' rather than 'gcc'. Also, the compiler must be
+called with the option %-std1%, to make it recognize some of the features of
+Standard C that Exim uses. (Most other compilers recognize Standard C by
+default.) To do this, you should create a file called _Local/Makefile-OSF1_
+containing the lines
+
+  CC=cc
+  CFLAGS=-std1
+
+If you are compiling for just one operating system, it may be easier to put
+these lines directly into _Local/Makefile_.
+
+Keeping all your local configuration settings separate from the distributed
+files makes it easy to transfer them to new versions of Exim simply by copying
+the contents of the _Local_ directory.
+
+
+cindex:[NIS lookup type,including support for]
+cindex:[NIS+ lookup type,including support for]
+cindex:[LDAP,including support for]
+cindex:[lookup,inclusion in binary]
+Exim contains support for doing LDAP, NIS, NIS+, and other kinds of file
+lookup, but not all systems have these components installed, so the default is
+not to include the relevant code in the binary. All the different kinds of file
+and database lookup that Exim supports are implemented as separate code modules
+which are included only if the relevant compile-time options are set. In the
+case of LDAP, NIS, and NIS+, the settings for _Local/Makefile_ are:
+
+  LOOKUP_LDAP=yes
+  LOOKUP_NIS=yes
+  LOOKUP_NISPLUS=yes
+
+and similar settings apply to the other lookup types. They are all listed in
+_src/EDITME_. In most cases the relevant include files and interface
+libraries need to be installed before compiling Exim.
+cindex:[cdb,including support for]
+However, in the case of cdb, which is included in the binary only if
+
+  LOOKUP_CDB=yes
+
+is set, the code is entirely contained within Exim, and no external include
+files or libraries are required. When a lookup type is not included in the
+binary, attempts to configure Exim to use it cause run time configuration
+errors.
+
+cindex:[Perl,including support for]
+Exim can be linked with an embedded Perl interpreter, allowing Perl
+subroutines to be called during string expansion. To enable this facility,
+
+  EXIM_PERL=perl.o
+
+must be defined in _Local/Makefile_. Details of this facility are given in
+chapter <<CHAPperl>>.
+
+cindex:[X11 libraries, location of]
+The location of the X11 libraries is something that varies a lot between
+operating systems, and of course there are different versions of X11 to cope
+with. Exim itself makes no use of X11, but if you are compiling the Exim
+monitor, the X11 libraries must be available.
+The following three variables are set in _OS/Makefile-Default_:
+
+  X11=/usr/X11R6
+  XINCLUDE=-I$(X11)/include
+  XLFLAGS=-L$(X11)/lib
+
+These are overridden in some of the operating-system configuration files. For
+example, in _OS/Makefile-SunOS5_ there is
+
+  X11=/usr/openwin
+  XINCLUDE=-I$(X11)/include
+  XLFLAGS=-L$(X11)/lib -R$(X11)/lib
+
+If you need to override the default setting for your operating system, place a
+definition of all three of these variables into your
+_Local/Makefile-<ostype>_ file.
+
+cindex:[EXTRALIBS]
+If you need to add any extra libraries to the link steps, these can be put in a
+variable called EXTRALIBS, which appears in all the link commands, but by
+default is not defined. In contrast, EXTRALIBS_EXIM is used only on the
+command for linking the main Exim binary, and not for any associated utilities.
+
+cindex:[DBM libraries, configuration for building]
+There is also DBMLIB, which appears in the link commands for binaries that
+use DBM functions (see also section <<SECTdb>>). Finally, there is
+EXTRALIBS_EXIMON, which appears only in the link step for the Exim monitor
+binary, and which can be used, for example, to include additional X11
+libraries.
+
+cindex:[configuration file,editing]
+The make file copes with rebuilding Exim correctly if any of the configuration
+files are edited. However, if an optional configuration file is deleted, it is
+necessary to touch the associated non-optional file (that is, _Local/Makefile_
+or _Local/eximon.conf_) before rebuilding.
+
+
+OS-specific header files
+~~~~~~~~~~~~~~~~~~~~~~~~
+cindex:[_os.h_]
+cindex:[building Exim,OS-specific C header files]
+The _OS_ directory contains a number of files with names of the form
+_os.h-<ostype>_. These are system-specific C header files that should not
+normally need to be changed. There is a list of macro settings that are
+recognized in the file _OS/os.configuring_, which should be consulted if you
+are porting Exim to a new operating system.
+
+
+
+Overriding build-time options for the monitor
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+cindex:[building Eximon,overriding default options]
+A similar process is used for overriding things when building the Exim monitor,
+where the files that are involved are
+
+&&&
+_OS/eximon.conf-Default_
+_OS/eximon.conf-_<'ostype'>
+_Local/eximon.conf_
+_Local/eximon.conf-_<'ostype'>
+_Local/eximon.conf-_<'archtype'>
+_Local/eximon.conf-_<'ostype'>-<'archtype'>
+&&&
+
+cindex:[_Local/eximon.conf_]
+As with Exim itself, the final three files need not exist, and in this case the
+_OS/eximon.conf-<ostype>_ file is also optional. The default values in
+_OS/eximon.conf-Default_ can be overridden dynamically by setting environment
+variables of the same name, preceded by EXIMON_. For example, setting
+EXIMON_LOG_DEPTH in the environment overrides the value of
+LOG_DEPTH at run time.
+
+
+
+
+Installing Exim binaries and scripts
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+cindex:[installing Exim]
+cindex:[BIN_DIRECTORY]
+The command 'make install' runs the 'exim_install' script with no
+arguments. The script copies binaries and utility scripts into the directory
+whose name is specified by the BIN_DIRECTORY setting in
+_Local/Makefile_.
+
+cindex:[CONFIGURE_FILE]
+Exim's run time configuration file is named by the CONFIGURE_FILE setting
+in _Local/Makefile_. If this names a single file, and the file does not
+exist, the default configuration file _src/configure.default_ is copied there
+by the installation script. If a run time configuration file already exists, it
+is left alone. If CONFIGURE_FILE is a colon-separated list, naming several
+alternative files, no default is installed.
+
+cindex:[system aliases file]
+cindex:[_/etc/aliases_]
+One change is made to the default configuration file when it is installed: the
+default configuration contains a router that references a system aliases file.
+The path to this file is set to the value specified by
+SYSTEM_ALIASES_FILE in _Local/Makefile_ (_/etc/aliases_ by default).
+If the system aliases file does not exist, the installation script creates it,
+and outputs a comment to the user.
+
+The created file contains no aliases, but it does contain comments about the
+aliases a site should normally have. Mail aliases have traditionally been
+kept in _/etc/aliases_. However, some operating systems are now using
+_/etc/mail/aliases_. You should check if yours is one of these, and change
+Exim's configuration if necessary.
+
+The default configuration uses the local host's name as the only local domain,
+and is set up to do local deliveries into the shared directory _/var/mail_,
+running as the local user. System aliases and _.forward_ files in users' home
+directories are supported, but no NIS or NIS+ support is configured. Domains
+other than the name of the local host are routed using the DNS, with delivery
+over SMTP.
+
+cindex:[setuid,installing Exim with]
+The install script copies files only if they are newer than the files they are
+going to replace. The Exim binary is required to be owned by root and have the
+'setuid' bit set, for normal configurations. Therefore, you must run 'make
+install' as root so that it can set up the Exim binary in this way. However, in
+some special situations (for example, if a host is doing no local deliveries)
+it may be possible to run Exim without making the binary setuid root (see
+chapter <<CHAPsecurity>> for details).
+
+It is possible to install Exim for special purposes (such as building a binary
+distribution) in a private part of the file system. You can do this by a
+command such as
+
+  make DESTDIR=/some/directory/ install
+
+This has the effect of pre-pending the specified directory to all the file
+paths, except the name of the system aliases file that appears in the default
+configuration. (If a default alias file is created, its name 'is' modified.)
+For backwards compatibility, ROOT is used if DESTDIR is not set,
+but this usage is deprecated.
+
+cindex:[installing Exim,what is not installed]
+Running 'make install' does not copy the Exim 4 conversion script
+'convert4r4', or the 'pcretest' test program. You will probably run the
+first of these only once (if you are upgrading from Exim 3), and the second
+isn't really part of Exim. None of the documentation files in the _doc_
+directory are copied, except for the info files when you have set
+INFO_DIRECTORY, as described in section <<SECTinsinfdoc>> below.
+
+For the utility programs, old versions are renamed by adding the suffix _.O_
+to their names. The Exim binary itself, however, is handled differently. It is
+installed under a name that includes the version number and the compile number,
+for example _exim-{version}-1_. The script then arranges for a symbolic link
+called _exim_ to point to the binary. If you are updating a previous version
+of Exim, the script takes care to ensure that the name _exim_ is never absent
+from the directory (as seen by other processes).
+
+cindex:[installing Exim,testing the script]
+If you want to see what the 'make install' will do before running it for
+real, you can pass the %-n% option to the installation script by this command:
+
+  make INSTALL_ARG=-n install
+
+The contents of the variable INSTALL_ARG are passed to the installation
+script. You do not need to be root to run this test. Alternatively, you can run
+the installation script directly, but this must be from within the build
+directory. For example, from the top-level Exim directory you could use this
+command:
+
+  (cd build-SunOS5-5.5.1-sparc; ../scripts/exim_install -n)
+
+cindex:[installing Exim,install script options]
+There are two other options that can be supplied to the installation script.
+
+- %-no_chown% bypasses the call to change the owner of the installed binary
+to root, and the call to make it a setuid binary.
+
+- %-no_symlink% bypasses the setting up of the symbolic link _exim_ to the
+installed binary.
+
+INSTALL_ARG can be used to pass these options to the script. For example:
+
+  make INSTALL_ARG=-no_symlink install
+
+
+The installation script can also be given arguments specifying which files are
+to be copied. For example, to install just the Exim binary, and nothing else,
+without creating the symbolic link, you could use:
+
+  make INSTALL_ARG='-no_symlink exim' install
+
+
+
+
+[[SECTinsinfdoc]]
+Installing info documentation
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+cindex:[installing Exim,'info' documentation]
+Not all systems use the GNU 'info' system for documentation, and for this
+reason, the Texinfo source of Exim's documentation is not included in the main
+distribution. Instead it is available separately from the ftp site (see section
+<<SECTavail>>).
+
+If you have defined INFO_DIRECTORY in _Local/Makefile_ and the Texinfo
+source of the documentation is found in the source tree, running 'make
+install' automatically builds the info files and installs them.
+
+
+
+Setting up the spool directory
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+cindex:[spool directory,creating]
+When it starts up, Exim tries to create its spool directory if it does not
+exist. The Exim uid and gid are used for the owner and group of the spool
+directory. Sub-directories are automatically created in the spool directory as
+necessary.
+
+
+
+
+Testing
+~~~~~~~
+cindex:[testing,installation]
+Having installed Exim, you can check that the run time configuration file is
+syntactically valid by running the following command, which assumes that the
+Exim binary directory is within your PATH environment variable:
+
+  exim -bV
+
+If there are any errors in the configuration file, Exim outputs error messages.
+Otherwise it outputs the version number and build date,
+the DBM library that is being used, and information about which drivers and
+other optional code modules are included in the binary.
+Some simple routing tests can be done by using the address testing option. For
+example,
+
+  exim -bt <local username>
+
+should verify that it recognizes a local mailbox, and
+
+  exim -bt <remote address>
+
+a remote one. Then try getting it to deliver mail, both locally and remotely.
+This can be done by passing messages directly to Exim, without going through a
+user agent. For example:
+
+  exim -v postmaster@your.domain.example
+  From: user@your.domain.example
+  To: postmaster@your.domain.example
+  Subject: Testing Exim
+
+  This is a test message.
+  ^D
+
+The %-v% option causes Exim to output some verification of what it is doing.
+In this case you should see copies of three log lines, one for the message's
+arrival, one for its delivery, and one containing ``Completed''.
+
+cindex:[delivery,problems with]
+If you encounter problems, look at Exim's log files ('mainlog' and
+'paniclog') to see if there is any relevant information there. Another source
+of information is running Exim with debugging turned on, by specifying the
+%-d% option. If a message is stuck on Exim's spool, you can force a delivery
+with debugging turned on by a command of the form
+
+  exim -d -M <message-id>
+
+You must be root or an ``admin user'' in order to do this. The %-d% option
+produces rather a lot of output, but you can cut this down to specific areas.
+For example, if you use %-d-all+route% only the debugging information relevant
+to routing is included. (See the %-d% option in chapter <<CHAPcommandline>> for
+more details.)
+
+cindex:[``sticky'' bit]
+cindex:[lock files]
+One specific problem that has shown up on some sites is the inability to do
+local deliveries into a shared mailbox directory, because it does not have the
+``sticky bit'' set on it. By default, Exim tries to create a lock file before
+writing to a mailbox file, and if it cannot create the lock file, the delivery
+is deferred. You can get round this either by setting the ``sticky bit'' on the
+directory, or by setting a specific group for local deliveries and allowing
+that group to create files in the directory (see the comments above the
+^local_delivery^ transport in the default configuration file). Another
+approach is to configure Exim not to use lock files, but just to rely on
+'fcntl()' locking instead. However, you should do this only if all user
+agents also use 'fcntl()' locking. For further discussion of locking issues,
+see chapter <<CHAPappendfile>>.
+
+One thing that cannot be tested on a system that is already running an MTA is
+the receipt of incoming SMTP mail on the standard SMTP port. However, the
+%-oX% option can be used to run an Exim daemon that listens on some other
+port, or 'inetd' can be used to do this. The %-bh% option and the
+'exim_checkaccess' utility can be used to check out policy controls on
+incoming SMTP mail.
+
+Testing a new version on a system that is already running Exim can most easily
+be done by building a binary with a different CONFIGURE_FILE setting. From
+within the run time configuration, all other file and directory names
+that Exim uses can be altered, in order to keep it entirely clear of the
+production version.
+
+
+Replacing another MTA with Exim
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+cindex:[replacing another MTA]
+Building and installing Exim for the first time does not of itself put it in
+general use. The name by which the system's MTA is called by mail user agents
+is either _/usr/sbin/sendmail_, or _/usr/lib/sendmail_ (depending on the
+operating system), and it is necessary to make this name point to the 'exim'
+binary in order to get the user agents to pass messages to Exim. This is
+normally done by renaming any existing file and making _/usr/sbin/sendmail_
+or _/usr/lib/sendmail_
+
+cindex:[symbolic link,to 'exim' binary]
+a symbolic link to the 'exim' binary. It is a good idea to remove any setuid
+privilege and executable status from the old MTA. It is then necessary to stop
+and restart the mailer daemon, if one is running.
+
+cindex:[FreeBSD, MTA indirection]
+cindex:[_/etc/mail/mailer.conf_]
+Some operating systems have introduced alternative ways of switching MTAs. For
+example, if you are running FreeBSD, you need to edit the file
+_/etc/mail/mailer.conf_ instead of setting up a symbolic link as just
+described. A typical example of the contents of this file for running Exim is
+as follows:
+
+  sendmail            /usr/exim/bin/exim
+  send-mail           /usr/exim/bin/exim
+  mailq               /usr/exim/bin/exim -bp
+  newaliases          /usr/bin/true
+
+
+Once you have set up the symbolic link, or edited _/etc/mail/mailer.conf_,
+your Exim installation is ``live''. Check it by sending a message from your
+favourite user agent.
+
+You should consider what to tell your users about the change of MTA. Exim may
+have different capabilities to what was previously running, and there are
+various operational differences such as the text of messages produced by
+command line options and in bounce messages. If you allow your users to make
+use of Exim's filtering capabilities, you should make the document entitled
+'Exim's interface to mail filtering'
+available to them.
+
+
+
+Upgrading Exim
+~~~~~~~~~~~~~~
+cindex:[upgrading Exim]
+If you are already running Exim on your host, building and installing a new
+version automatically makes it available to MUAs, or any other programs that
+call the MTA directly. However, if you are running an Exim daemon, you do need
+to send it a HUP signal, to make it re-exec itself, and thereby pick up the new
+binary. You do not need to stop processing mail in order to install a new
+version of Exim.
+
+
+
+Stopping the Exim daemon on Solaris
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+cindex:[Solaris,stopping Exim on]
+The standard command for stopping the mailer daemon on Solaris is
+
+  /etc/init.d/sendmail stop
+
+If _/usr/lib/sendmail_ has been turned into a symbolic link, this script
+fails to stop Exim because it uses the command 'ps -e' and greps the output
+for the text ``sendmail''; this is not present because the actual program name
+(that is, ``exim'') is given by the 'ps' command with these options. A solution
+is to replace the line that finds the process id with something like
+
+  pid=`cat /var/spool/exim/exim-daemon.pid`
+
+to obtain the daemon's pid directly from the file that Exim saves it in.
+
+Note, however, that stopping the daemon does not ``stop Exim''. Messages can
+still be received from local processes, and if automatic delivery is configured
+(the normal case), deliveries will still occur.
+
+
+
+
+////////////////////////////////////////////////////////////////////////////
+////////////////////////////////////////////////////////////////////////////
+
+[[CHAPcommandline]]
+The Exim command line
+---------------------
+cindex:[command line,options]
+cindex:[options,command line]
+Exim's command line takes the standard Unix form of a sequence of options,
+each starting with a hyphen character, followed by a number of arguments. The
+options are compatible with the main options of Sendmail, and there are also
+some additional options, some of which are compatible with Smail 3. Certain
+combinations of options do not make sense, and provoke an error if used.
+The form of the arguments depends on which options are set.
+
+
+Setting options by program name
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+cindex:['mailq']
+If Exim is called under the name 'mailq', it behaves as if the option %-bp%
+were present before any other options.
+The %-bp% option requests a listing of the contents of the mail queue on the
+standard output.
+This feature is for compatibility with some systems that contain a command of
+that name in one of the standard libraries, symbolically linked to
+_/usr/sbin/sendmail_ or _/usr/lib/sendmail_.
+
+cindex:['rsmtp']
+If Exim is called under the name 'rsmtp' it behaves as if the option %-bS%
+were present before any other options, for compatibility with Smail. The %-bS%
+option is used for reading in a number of messages in batched SMTP format.
+
+cindex:['rmail']
+If Exim is called under the name 'rmail' it behaves as if the %-i% and
+%-oee% options were present before any other options, for compatibility with
+Smail. The name 'rmail' is used as an interface by some UUCP systems.
+
+cindex:['runq']
+cindex:[queue runner]
+If Exim is called under the name 'runq' it behaves as if the option %-q% were
+present before any other options, for compatibility with Smail. The %-q%
+option causes a single queue runner process to be started.
+
+cindex:['newaliases']
+cindex:[alias file,building]
+cindex:[Sendmail compatibility,calling Exim as 'newaliases']
+If Exim is called under the name 'newaliases' it behaves as if the option
+%-bi% were present before any other options, for compatibility with Sendmail.
+This option is used for rebuilding Sendmail's alias file. Exim does not have
+the concept of a single alias file, but can be configured to run a given
+command if called with the %-bi% option.
+
+
+[[SECTtrustedadmin]]
+Trusted and admin users
+~~~~~~~~~~~~~~~~~~~~~~~
+Some Exim options are available only to 'trusted users' and others are
+available only to 'admin users'. In the description below, the phrases ``Exim
+user'' and ``Exim group'' mean the user and group defined by EXIM_USER and
+EXIM_GROUP in _Local/Makefile_ or set by the %exim_user% and
+%exim_group% options. These do not necessarily have to use the name ``exim''.
+
+- cindex:[trusted user,definition of]
+cindex:[user, trusted definition of]
+The trusted users are root, the Exim user, any user listed in the
+%trusted_users% configuration option, and any user whose current group or any
+supplementary group is one of those listed in the %trusted_groups%
+configuration option. Note that the Exim group is not automatically trusted.
++
+cindex:[``From'' line]
+cindex:[envelope sender]
+Trusted users are always permitted to use the %-f% option or a leading ``From ''
+line to specify the envelope sender of a message that is passed to Exim through
+the local interface (see the %-bm% and %-f% options below). See the
+%untrusted_set_sender% option for a way of permitting non-trusted users to
+set envelope senders.
++
+cindex:['From:' header line]
+cindex:['Sender:' header line]
+For a trusted user, there is never any check on the contents of the 'From:'
+header line, and a 'Sender:' line is never added. Furthermore, any existing
+'Sender:' line in incoming local (non-TCP/IP) messages is not removed.
++
+Trusted users may also specify a host name, host address, interface address,
+protocol name, ident value, and authentication data when submitting a message
+locally. Thus, they are able to insert messages into Exim's queue locally that
+have the characteristics of messages received from a remote host. Untrusted
+users may in some circumstances use %-f%, but can never set the other values
+that are available to trusted users.
+
+- cindex:[user, admin definition of]
+cindex:[admin user,definition of]
+The admin users are root, the Exim user, and any user that is a member of the
+Exim group or of any group listed in the %admin_groups% configuration option.
+The current group does not have to be one of these groups.
++
+Admin users are permitted to list the queue, and to carry out certain
+operations on messages, for example, to force delivery failures. It is also
+necessary to be an admin user in order to see the full information provided by
+the Exim monitor, and full debugging output.
++
+By default, the use of the %-M%, %-q%, %-R%, and %-S% options to cause Exim
+to attempt delivery of messages on its queue is restricted to admin users.
+However, this restriction can be relaxed by setting the %prod_requires_admin%
+option false (that is, specifying %no_prod_requires_admin%).
++
+Similarly, the use of the %-bp% option to list all the messages in the queue
+is restricted to admin users unless %queue_list_requires_admin% is set
+false.
+
+
+*Warning*: If you configure your system so that admin users are able to
+edit Exim's configuration file, you are giving those users an easy way of
+getting root. There is further discussion of this issue at the start of chapter
+<<CHAPconf>>.
+
+
+
+
+Command line options
+~~~~~~~~~~~~~~~~~~~~
+The command options are described in alphabetical order below.
+
+///
+We insert a stylized DocBook comment here, to identify the start of the command
+line options. This is for the benefit of the Perl script that automatically
+creates a man page for the options.
+///
+
+++++
+<!-- === Start of command line options === -->
+++++
+
+
+*{hh}*::
+oindex:[{hh}]
+cindex:[options, command line; terminating]
+This is a pseudo-option whose only purpose is to terminate the options and
+therefore to cause subsequent command line items to be treated as arguments
+rather than options, even if they begin with hyphens.
+
+*--help*::
+oindex:[%{hh}help%]
+This option causes Exim to output a few sentences stating what it is.
+The same output is generated if the Exim binary is called with no options and
+no arguments.
+
+*-B*<'type'>::
+oindex:[%-B%]
+cindex:[8-bit characters]
+cindex:[Sendmail compatibility,8-bit characters]
+This is a Sendmail option for selecting 7 or 8 bit processing. Exim is 8-bit
+clean; it ignores this option.
+
+*-bd*::
+oindex:[%-bd%]
+cindex:[daemon]
+cindex:[SMTP listener]
+cindex:[queue runner]
+This option runs Exim as a daemon, awaiting incoming SMTP connections. Usually
+the %-bd% option is combined with the %-q%<'time'> option, to specify that
+the daemon should also initiate periodic queue runs.
++
+The %-bd% option can be used only by an admin user. If either of the %-d%
+(debugging) or %-v% (verifying) options are set, the daemon does not
+disconnect from the controlling terminal. When running this way, it can be
+stopped by pressing ctrl-C.
++
+By default, Exim listens for incoming connections to the standard SMTP port on
+all the host's running interfaces. However, it is possible to listen on other
+ports, on multiple ports, and only on specific interfaces. Chapter
+<<CHAPinterfaces>> contains a description of the options that control this.
++
+When a listening daemon
+cindex:[daemon,process id (pid)]
+cindex:[pid (process id),of daemon]
+is started without the use of %-oX% (that is, without overriding the normal
+configuration), it writes its process id to a file called _exim-daemon.pid_ in
+Exim's spool directory. This location can be overridden by setting
+PID_FILE_PATH in _Local/Makefile_. The file is written while Exim is still
+running as root.
++
+When %-oX% is used on the command line to start a listening daemon, the
+process id is not written to the normal pid file path. However, %-oP% can be
+used to specify a path on the command line if a pid file is required.
++
+The SIGHUP signal
+cindex:[SIGHUP]
+can be used to cause the daemon to re-exec itself. This should be done whenever
+Exim's configuration file, or any file that is incorporated into it by means of
+the %.include% facility, is changed, and also whenever a new version of Exim is
+installed. It is not necessary to do this when other files that are referenced
+from the configuration (for example, alias files) are changed, because these
+are reread each time they are used.
+
+*-bdf*::
+oindex:[%-bdf%]
+This option has the same effect as %-bd% except that it never disconnects from
+the controlling terminal, even when no debugging is specified.
+
+*-be*::
+oindex:[%-be%]
+cindex:[testing,string expansion]
+cindex:[expansion,testing]
+Run Exim in expansion testing mode. Exim discards its root privilege, to
+prevent ordinary users from using this mode to read otherwise inaccessible
+files. If no arguments are given, Exim runs interactively, prompting for lines
+of data.
++
+If Exim was built with USE_READLINE=yes in _Local/Makefile_, it tries
+to load the %libreadline% library dynamically whenever the %-be% option is
+used without command line arguments. If successful, it uses the 'readline()'
+function, which provides extensive line-editing facilities, for reading the
+test data. A line history is supported.
++
+Long expansion expressions can be split over several lines by using backslash
+continuations. As in Exim's run time configuration, whitespace at the start of
+continuation lines is ignored. Each argument or data line is passed through the
+string expansion mechanism, and the result is output. Variable values from the
+configuration file (for example, $qualify_domain$) are available, but no
+message-specific values (such as $domain$) are set, because no message is
+being processed.
+
+*-bF*~<'filename'>::
+oindex:[%-bF%]
+cindex:[system filter,testing]
+cindex:[testing,system filter]
+This option is the same as %-bf% except that it assumes that the filter being
+tested is a system filter. The additional commands that are available only in
+system filters are recognized.
+
+*-bf*~<'filename'>::
+oindex:[%-bf%]
+cindex:[filter,testing]
+cindex:[testing,filter file]
+cindex:[forward file,testing]
+cindex:[testing,forward file]
+cindex:[Sieve filter,testing]
+This option runs Exim in user filter testing mode; the file is the filter file
+to be tested, and a test message must be supplied on the standard input. If
+there are no message-dependent tests in the filter, an empty file can be
+supplied.
++
+If you want to test a system filter file, use %-bF% instead of %-bf%. You can
+use both %-bF% and %-bf% on the same command, in order to
+test a system filter and a user filter in the same run. For example:
+
+  exim -bF /system/filter -bf /user/filter </test/message
++
+This is helpful when the system filter adds header lines or sets filter
+variables that are used by the user filter.
++
+If the test filter file does not begin with one of the special lines
+
+  # Exim filter
+  # Sieve filter
++
+it is taken to be a normal _.forward_ file, and is tested for validity under
+that interpretation. See sections <<SECTitenonfilred>> to <<SECTspecitredli>> for a
+description of the possible contents of non-filter redirection lists.
++
+The result of an Exim command that uses %-bf%, provided no errors are
+detected, is a list of the actions that Exim would try to take if presented
+with the message for real. More details of filter testing are given in the
+separate document entitled 'Exim's interfaces to mail filtering'.
++
+When testing a filter file,
+cindex:[``From'' line]
+cindex:[envelope sender]
+cindex:[%-f% option,for filter testing]
+the envelope sender can be set by the %-f% option,
+or by a ``From '' line at the start of the test message. Various parameters that
+would normally be taken from the envelope recipient address of the message can
+be set by means of additional command line options (see the next four options).
+
+*-bfd*~<'domain'>::
+oindex:[%-bfd%]
+This sets the domain of the recipient address when a filter file is being
+tested by means of the %-bf% option. The default is the value of
+$qualify_domain$.
+
+*-bfl*~<'local~part'>::
+oindex:[%-bfl%]
+This sets the local part of the recipient address when a filter file is being
+tested by means of the %-bf% option. The default is the username of the
+process that calls Exim. A local part should be specified with any prefix or
+suffix stripped, because that is how it appears to the filter when a message is
+actually being delivered.
+
+*-bfp*~<'prefix'>::
+oindex:[%-bfp%]
+This sets the prefix of the local part of the recipient address when a filter
+file is being tested by means of the %-bf% option. The default is an empty
+prefix.
+
+*-bfs*~<'suffix'>::
+oindex:[%-bfs%]
+This sets the suffix of the local part of the recipient address when a filter
+file is being tested by means of the %-bf% option. The default is an empty
+suffix.
+
+*-bh*~<'IP~address'>::
+oindex:[%-bh%]
+cindex:[testing,incoming SMTP]
+cindex:[SMTP,testing incoming]
+cindex:[testing,relay control]
+cindex:[relaying,testing configuration]
+cindex:[policy control,testing]
+cindex:[debugging,%-bh% option]
+This option runs a fake SMTP session as if from the given IP address, using the
+standard input and output. The IP address may include a port number at the end,
+after a full stop. For example:
+
+  exim -bh 10.9.8.7.1234
+  exim -bh fe80::a00:20ff:fe86:a061.5678
++
+When an IPv6 address is given, it is converted into canonical form. In the case
+of the second example above, the value of $sender_host_address$ after
+conversion to the canonical form is `fe80:0000:0000:0a00:20ff:fe86:a061.5678`.
++
+Comments as to what is going on are written to the standard error file. These
+include lines beginning with ``LOG'' for anything that would have been logged.
+This facility is provided for testing configuration options for incoming
+messages, to make sure they implement the required policy. For example, you can
+test your relay controls using %-bh%.
++
+*Warning 1*:
+cindex:[RFC 1413]
+You cannot test features of the configuration that rely on
+ident (RFC 1413) callouts. These cannot be done when testing using
+%-bh% because there is no incoming SMTP connection.
++
+*Warning 2*: Address verification callouts (see section <<SECTcallver>>) are
+also skipped when testing using %-bh%. If you want these callouts to occur,
+use %-bhc% instead.
++
+Messages supplied during the testing session are discarded, and nothing is
+written to any of the real log files. There may be pauses when DNS (and other)
+lookups are taking place, and of course these may time out. The %-oMi% option
+can be used to specify a specific IP interface and port if this is important.
++
+The 'exim_checkaccess' utility is a ``packaged'' version of %-bh% whose
+output just states whether a given recipient address from a given host is
+acceptable or not. See section <<SECTcheckaccess>>.
+
+*-bhc*~<'IP~address'>::
+oindex:[%-bhc%]
+This option operates in the same way as %-bh%, except that address
+verification callouts are performed if required. This includes consulting and
+updating the callout cache database.
+
+*-bi*::
+oindex:[%-bi%]
+cindex:[alias file,building]
+cindex:[building alias file]
+cindex:[Sendmail compatibility,%-bi% option]
+Sendmail interprets the %-bi% option as a request to rebuild its alias file.
+Exim does not have the concept of a single alias file, and so it cannot mimic
+this behaviour. However, calls to _/usr/lib/sendmail_ with the %-bi% option
+tend to appear in various scripts such as NIS make files, so the option must be
+recognized.
++
+If %-bi% is encountered, the command specified by the %bi_command%
+configuration option is run, under the uid and gid of the caller of Exim. If
+the %-oA% option is used, its value is passed to the command as an argument.
+The command set by %bi_command% may not contain arguments. The command can use
+the 'exim_dbmbuild' utility, or some other means, to rebuild alias files if
+this is required. If the %bi_command% option is not set, calling Exim with
+%-bi% is a no-op.
+
+*-bm*::
+oindex:[%-bm%]
+cindex:[local message reception]
+This option runs an Exim receiving process that accepts an incoming,
+locally-generated message on the current input. The recipients are given as the
+command arguments (except when %-t% is also present -- see below). Each
+argument can be a comma-separated list of RFC 2822 addresses. This is the
+default option for selecting the overall action of an Exim call; it is assumed
+if no other conflicting option is present.
++
+If any addresses in the message are unqualified (have no domain), they are
+qualified by the values of the %qualify_domain% or %qualify_recipient%
+options, as appropriate. The %-bnq% option (see below) provides a way of
+suppressing this for special cases.
++
+Policy checks on the contents of local messages can be enforced by means of
+the non-SMTP ACL. See chapter <<CHAPACL>> for details.
++
+The return code
+cindex:[return code,for %-bm%]
+is zero if the message is successfully accepted. Otherwise, the
+action is controlled by the %-oe'x'% option setting -- see below.
++
+The format
+cindex:[message,format]
+cindex:[format,message]
+cindex:[``From'' line]
+cindex:[UUCP,``From'' line]
+cindex:[Sendmail compatibility,``From'' line]
+of the message must be as defined in RFC 2822, except that, for
+compatibility with Sendmail and Smail, a line in one of the forms
+
+  From sender Fri Jan  5 12:55 GMT 1997
+  From sender Fri, 5 Jan 97 12:55:01
++
+(with the weekday optional, and possibly with additional text after the date)
+is permitted to appear at the start of the message. There appears to be no
+authoritative specification of the format of this line. Exim recognizes it by
+matching against the regular expression defined by the %uucp_from_pattern%
+option, which can be changed if necessary.
++
+The
+cindex:[%-f% option,overriding ``From'' line]
+specified sender is treated as if it were given as the argument to the
+%-f% option, but if a %-f% option is also present, its argument is used in
+preference to the address taken from the message. The caller of Exim must be a
+trusted user for the sender of a message to be set in this way.
+
+*-bnq*::
+oindex:[%-bnq%]
+cindex:[address qualification, suppressing]
+By default, Exim automatically qualifies unqualified addresses (those
+without domains) that appear in messages that are submitted locally (that
+is, not over TCP/IP). This qualification applies both to addresses in
+envelopes, and addresses in header lines. Sender addresses are qualified using
+%qualify_domain%, and recipient addresses using %qualify_recipient% (which
+defaults to the value of %qualify_domain%).
++
+Sometimes, qualification is not wanted. For example, if %-bS% (batch SMTP) is
+being used to re-submit messages that originally came from remote hosts after
+content scanning, you probably do not want to qualify unqualified addresses in
+header lines. (Such lines will be present only if you have not enabled a header
+syntax check in the appropriate ACL.)
++
+The %-bnq% option suppresses all qualification of unqualified addresses in
+messages that originate on the local host. When this is used, unqualified
+addresses in the envelope provoke errors (causing message rejection) and
+unqualified addresses in header lines are left alone.
+
+
+*-bP*::
+oindex:[%-bP%]
+cindex:[configuration options, extracting]
+cindex:[options,configuration -- extracting]
+If this option is given with no arguments, it causes the values of all Exim's
+main configuration options to be written to the standard output. The values
+of one or more specific options can be requested by giving their names as
+arguments, for example:
+
+  exim -bP qualify_domain hold_domains
++
+However, any option setting that is preceded by the word ``hide'' in the
+configuration file is not shown in full, except to an admin user. For other
+users, the output is as in this example:
+
+  mysql_servers = <value not displayable>
++
+If %configure_file% is given as an argument, the name of the run time
+configuration file is output.
+If a list of configuration files was supplied, the value that is output here
+is the name of the file that was actually used.
++
+cindex:[daemon,process id (pid)]
+cindex:[pid (process id),of daemon]
+If %log_file_path% or %pid_file_path% are given, the names of the directories
+where log files and daemon pid files are written are output, respectively. If
+these values are unset, log files are written in a sub-directory of the spool
+directory called %log%, and the pid file is written directly into the spool
+directory.
++
+If %-bP% is followed by a name preceded by `+`, for example,
+
+  exim -bP +local_domains
++
+it searches for a matching named list of any type (domain, host, address, or
+local part) and outputs what it finds.
++
+If
+cindex:[options,router -- extracting]
+cindex:[options,transport -- extracting]
+one of the words %router%, %transport%, or %authenticator% is given,
+followed by the name of an appropriate driver instance, the option settings for
+that driver are output. For example:
+
+  exim -bP transport local_delivery
++
+The generic driver options are output first, followed by the driver's private
+options. A list of the names of drivers of a particular type can be obtained by
+using one of the words %router_list%, %transport_list%, or
+%authenticator_list%, and a complete list of all drivers with their option
+settings can be obtained by using %routers%, %transports%, or %authenticators%.
+
+
+*-bp*::
+oindex:[%-bp%]
+cindex:[queue,listing messages on]
+cindex:[listing,messages on the queue]
+This option requests a listing of the contents of the mail queue on the
+standard output. If the %-bp% option is followed by a list of message ids,
+just those messages are listed. By default, this option can be used only by an
+admin user. However, the %queue_list_requires_admin% option can be set false
+to allow any user to see the queue.
++
+Each message on the queue is displayed as in the following example:
+
+  25m  2.9K 0t5C6f-0000c8-00 <alice@wonderland.fict.example>
+            red.king@looking-glass.fict.example
+            <other addresses>
++
+The
+cindex:[message,size in queue listing]
+cindex:[size,of message]
+first line contains the length of time the message has been on the queue
+(in this case 25 minutes), the size of the message (2.9K), the unique local
+identifier for the message, and the message sender, as contained in the
+envelope. For bounce messages, the sender address is empty, and appears as
+``<>''. If the message was submitted locally by an untrusted user who overrode
+the default sender address, the user's login name is shown in parentheses
+before the sender address.
++
+If
+cindex:[frozen messages,in queue listing]
+the message is frozen (attempts to deliver it are suspended) then the text
+``\*\*\* frozen \*\*\*'' is displayed at the end of this line.
++
+The recipients of the message (taken from the envelope, not the headers) are
+displayed on subsequent lines. Those addresses to which the message has already
+been delivered are marked with the letter D. If an original address gets
+expanded into several addresses via an alias or forward file, the original is
+displayed with a D only when deliveries for all of its child addresses are
+complete.
+
+
+*-bpa*::
+oindex:[%-bpa%]
+This option operates like %-bp%, but in addition it shows delivered addresses
+that were generated from the original top level address(es) in each message by
+alias or forwarding operations. These addresses are flagged with ``+D'' instead
+of just ``D''.
+
+
+*-bpc*::
+oindex:[%-bpc%]
+cindex:[queue,count of messages on]
+This option counts the number of messages on the queue, and writes the total
+to the standard output. It is restricted to admin users, unless
+%queue_list_requires_admin% is set false.
+
+
+*-bpr*::
+oindex:[%-bpr%]
+This option operates like %-bp%, but the output is not sorted into
+chronological order of message arrival. This can speed it up when there are
+lots of messages on the queue, and is particularly useful if the output is
+going to be post-processed in a way that doesn't need the sorting.
+
+*-bpra*::
+oindex:[%-bpra%]
+This option is a combination of %-bpr% and %-bpa%.
+
+*-bpru*::
+oindex:[%-bpru%]
+This option is a combination of %-bpr% and %-bpu%.
+
+
+*-bpu*::
+oindex:[%-bpu%]
+This option operates like %-bp% but shows only undelivered top-level addresses
+for each message displayed. Addresses generated by aliasing or forwarding are
+not shown, unless the message was deferred after processing by a router with
+the %one_time% option set.
+
+
+*-brt*::
+oindex:[%-brt%]
+cindex:[testing,retry configuration]
+cindex:[retry,configuration testing]
+This option is for testing retry rules, and it must be followed by up to three
+arguments. It causes Exim to look for a retry rule that matches the values
+and to write it to the standard output. For example:
+
+  exim -brt bach.comp.mus.example
+  Retry rule: *.comp.mus.example  F,2h,15m; F,4d,30m;
++
+See chapter <<CHAPretry>> for a description of Exim's retry rules. The first
+argument, which is required, can be a complete address in the form
+'local_part@domain', or it can be just a domain name. The second argument is
+an optional second domain name; if no retry rule is found for the first
+argument, the second is tried. This ties in with Exim's behaviour when looking
+for retry rules for remote hosts -- if no rule is found that matches the host,
+one that matches the mail domain is sought. The final argument is the name of a
+specific delivery error, as used in setting up retry rules, for example
+``quota_3d''.
+
+*-brw*::
+oindex:[%-brw%]
+cindex:[testing,rewriting]
+cindex:[rewriting,testing]
+This option is for testing address rewriting rules, and it must be followed by
+a single argument, consisting of either a local part without a domain, or a
+complete address with a fully qualified domain. Exim outputs how this address
+would be rewritten for each possible place it might appear. See chapter
+<<CHAPrewrite>> for further details.
+
+*-bS*::
+oindex:[%-bS%]
+cindex:[SMTP,batched incoming]
+cindex:[batched SMTP input]
+This option is used for batched SMTP input, which is an alternative interface
+for non-interactive local message submission. A number of messages can be
+submitted in a single run. However, despite its name, this is not really SMTP
+input. Exim reads each message's envelope from SMTP commands on the standard
+input, but generates no responses. If the caller is trusted, or
+%untrusted_set_sender% is set, the senders in the SMTP MAIL commands are
+believed; otherwise the sender is always the caller of Exim.
++
+The message itself is read from the standard input, in SMTP format (leading
+dots doubled), terminated by a line containing just a single dot. An error is
+provoked if the terminating dot is missing. A further message may then follow.
++
+As for other local message submissions, the contents of incoming batch SMTP
+messages can be checked using the non-SMTP ACL (see chapter <<CHAPACL>>).
+Unqualified addresses are automatically qualified using %qualify_domain% and
+%qualify_recipient%, as appropriate, unless the %-bnq% option is used.
++
+Some other SMTP commands are recognized in the input. HELO and EHLO act
+as RSET; VRFY, EXPN, ETRN, and HELP act as NOOP;
+QUIT quits, ignoring the rest of the standard input.
++
+cindex:[return code,for %-bS%]
+If any error is encountered, reports are written to the standard output and
+error streams, and Exim gives up immediately. The return code is 0 if no error
+was detected; it is 1 if one or more messages were accepted before the error
+was detected; otherwise it is 2.
++
+More details of input using batched SMTP are given in section
+<<SECTincomingbatchedSMTP>>.
+
+*-bs*::
+oindex:[%-bs%]
+cindex:[SMTP,local input]
+cindex:[local SMTP input]
+This option causes Exim to accept one or more messages by reading SMTP commands
+on the standard input, and producing SMTP replies on the standard output. SMTP
+policy controls, as defined in ACLs (see chapter <<CHAPACL>>) are applied.
+Some user agents use this interface as a way of passing locally-generated
+messages to the MTA.
++
+In
+cindex:[sender,source of]
+this usage, if the caller of Exim is trusted, or %untrusted_set_sender% is
+set, the senders of messages are taken from the SMTP MAIL commands.
+Otherwise the content of these commands is ignored and the sender is set up as
+the calling user. Unqualified addresses are automatically qualified using
+%qualify_domain% and %qualify_recipient%, as appropriate, unless the %-bnq%
+option is used.
++
+cindex:[inetd]
+The
+%-bs% option is also used to run Exim from 'inetd', as an alternative to using
+a listening daemon. Exim can distinguish the two cases by checking whether the
+standard input is a TCP/IP socket. When Exim is called from 'inetd', the source
+of the mail is assumed to be remote, and the comments above concerning senders
+and qualification do not apply. In this situation, Exim behaves in exactly the
+same way as it does when receiving a message via the listening daemon.
+
+*-bt*::
+oindex:[%-bt%]
+cindex:[testing,addresses]
+cindex:[address,testing]
+This option runs Exim in address testing mode, in which each argument is taken
+as an address to be tested for deliverability. The results are written to the
+standard output. If a test fails, and the caller is not an admin user, no
+details of the failure are output, because these might contain sensitive
+information such as usernames and passwords for database lookups.
++
+If no arguments are given, Exim runs in an interactive manner, prompting with a
+right angle bracket for addresses to be tested.
++
+Unlike the %-be% test option, you cannot arrange for Exim to use the
+'readline()' function, because it is running as 'root' and there are
+security issues.
++
+Each address is handled as if it were the recipient address of a message
+(compare the %-bv% option). It is passed to the routers and the result is
+written to the standard output. However, any router that has
+%no_address_test% set is bypassed. This can make %-bt% easier to use for
+genuine routing tests if your first router passes everything to a scanner
+program.
++
+The
+cindex:[return code,for %-bt%]
+return code is 2 if any address failed outright; it is 1 if no address
+failed outright but at least one could not be resolved for some reason. Return
+code 0 is given only when all addresses succeed.
++
+*Warning*: %-bt% can only do relatively simple testing. If any of the
+routers in the configuration makes any tests on the sender address of a
+message,
+cindex:[%-f% option,for address testing]
+you can use the %-f% option to set an appropriate sender when running
+%-bt% tests. Without it, the sender is assumed to be the calling user at the
+default qualifying domain. However, if you have set up (for example) routers
+whose behaviour depends on the contents of an incoming message, you cannot test
+those conditions using %-bt%. The %-N% option provides a possible way of
+doing such tests.
+
+*-bV*::
+oindex:[%-bV%]
+cindex:[version number of Exim, verifying]
+This option causes Exim to write the current version number, compilation
+number, and compilation date of the 'exim' binary to the standard output.
+It also lists the DBM library this is being used, the optional modules (such as
+specific lookup types), the drivers that are included in the binary, and the
+name of the run time configuration file that is in use.
++
+As part of its operation, %-bV% causes Exim to read and syntax check its
+configuration file. However, this is a static check only. It cannot check
+values that are to be expanded. For example, although a misspelt ACL verb is
+detected, an error in the verb's arguments is not. You cannot rely on %-bV%
+alone to discover (for example) all the typos in the configuration; some
+realistic testing is needed. The %-bh% and %-N% options provide more dynamic
+testing facilities.
+
+*-bv*::
+oindex:[%-bv%]
+cindex:[verifying address, using %-bv%]
+cindex:[address,verification]
+This option runs Exim in address verification mode, in which each argument is
+taken as an address to be verified. During normal operation, verification
+happens mostly as a consequence processing a %verify% condition in an ACL (see
+chapter <<CHAPACL>>). If you want to test an entire ACL, see the %-bh% option.
++
+If verification fails, and the caller is not an admin user, no details of the
+failure are output, because these might contain sensitive information such as
+usernames and passwords for database lookups.
++
+If no arguments are given, Exim runs in an interactive manner, prompting with a
+right angle bracket for addresses to be verified.
++
+Unlike the %-be% test option, you cannot arrange for Exim to use the
+'readline()' function, because it is running as 'exim' and there are
+security issues.
++
+Verification differs from address testing (the %-bt% option) in that routers
+that have %no_verify% set are skipped, and if the address is accepted by a
+router that has %fail_verify% set, verification fails. The address is verified
+as a recipient if %-bv% is used; to test verification for a sender address,
+%-bvs% should be used.
++
+If the %-v% option is not set, the output consists of a single line for each
+address, stating whether it was verified or not, and giving a reason in the
+latter case. Otherwise, more details are given of how the address has been
+handled, and in the case of address redirection, all the generated addresses
+are also considered. Without %-v%, generating more than one address by
+redirection causes verification to end sucessfully.
++
+The
+cindex:[return code,for %-bv%]
+return code is 2 if any address failed outright; it is 1 if no address
+failed outright but at least one could not be resolved for some reason. Return
+code 0 is given only when all addresses succeed.
++
+If any of the routers in the configuration makes any tests on the sender
+address of a message, you should use the %-f% option to set an appropriate
+sender when running %-bv% tests. Without it, the sender is assumed to be the
+calling user at the default qualifying domain.
+
+*-bvs*::
+oindex:[%-bvs%]
+This option acts like %-bv%, but verifies the address as a sender rather
+than a recipient address. This affects any rewriting and qualification that
+might happen.
+
+*-C*~<'filelist'>::
+oindex:[%-C%]
+cindex:[configuration file,alternate]
+cindex:[CONFIGURE_FILE]
+cindex:[alternate configuration file]
+This option causes Exim to find the run time configuration file from the given
+list instead of from the list specified by the CONFIGURE_FILE
+compile-time setting. Usually, the list will consist of just a single file
+name, but it can be a colon-separated list of names. In this case, the first
+file that exists is used. Failure to open an existing file stops Exim from
+proceeding any further along the list, and an error is generated.
++
+When this option is used by a caller other than root or the Exim user, and the
+list is different from the compiled-in list, Exim gives up its root privilege
+immediately, and runs with the real and effective uid and gid set to those of
+the caller. However, if ALT_CONFIG_ROOT_ONLY is defined in
+_Local/Makefile_, root privilege is retained for %-C% only if the caller of
+Exim is root.
++
+That is, the Exim user is no longer privileged in this regard. This build-time
+option is not set by default in the Exim source distribution tarbundle.
+However, if you are using a ``packaged'' version of Exim (source or binary), the
+packagers might have enabled it.
++
+Setting ALT_CONFIG_ROOT_ONLY locks out the possibility of testing a
+configuration using %-C% right through message reception and delivery, even if
+the caller is root. The reception works, but by that time, Exim is running as
+the Exim user, so when it re-execs to regain privilege for the delivery, the
+use of %-C% causes privilege to be lost. However, root can test reception and
+delivery using two separate commands (one to put a message on the queue, using
+%-odq%, and another to do the delivery, using %-M%).
++
+If ALT_CONFIG_PREFIX is defined _in Local/Makefile_, it specifies a
+prefix string with which any file named in a %-C% command line option
+must start. In addition, the file name must not contain the sequence `/../`.
+However, if the value of the %-C% option is identical to the value of
+CONFIGURE_FILE in _Local/Makefile_, Exim ignores %-C% and proceeds as
+usual. There is no default setting for ALT_CONFIG_PREFIX; when it is
+unset, any file name can be used with %-C%.
++
+ALT_CONFIG_PREFIX can be used to confine alternative configuration files
+to a directory to which only root has access. This prevents someone who has
+broken into the Exim account from running a privileged Exim with an arbitrary
+configuration file.
++
+The %-C% facility is useful for ensuring that configuration files are
+syntactically correct, but cannot be used for test deliveries, unless the
+caller is privileged, or unless it is an exotic configuration that does not
+require privilege. No check is made on the owner or group of the files
+specified by this option.
+
+*-D*<'macro'>=<'value'>::
+oindex:[%-D%]
+cindex:[macro,setting on command line]
+This option can be used to override macro definitions in the configuration file
+(see section <<SECTmacrodefs>>). However, like %-C%, if it is used by an
+unprivileged caller, it causes Exim to give up its root privilege.
+If DISABLE_D_OPTION is defined in _Local/Makefile_, the use of %-D% is
+completely disabled, and its use causes an immediate error exit.
++
+The entire option (including equals sign if present) must all be within one
+command line item. %-D% can be used to set the value of a macro to the empty
+string, in which case the equals sign is optional. These two commands are
+synonymous:
+
+  exim -DABC  ...
+  exim -DABC= ...
++
+To include spaces in a macro definition item, quotes must be used. If you use
+quotes, spaces are permitted around the macro name and the equals sign. For
+example:
+
+  exim '-D ABC = something' ...
++
+%-D% may be repeated up to 10 times on a command line.
+
+*-d*<'debug~options'>::
+oindex:[%-d%]
+cindex:[debugging,list of selectors]
+cindex:[debugging,%-d% option]
+This option causes debugging information to be written to the standard
+error stream. It is restricted to admin users because debugging output may show
+database queries that contain password information. Also, the details of users'
+filter files should be protected. When %-d% is used, %-v% is assumed. If
+%-d% is given on its own, a lot of standard debugging data is output. This can
+be reduced, or increased to include some more rarely needed information, by
+following %-d% with a string made up of names preceded by plus or minus
+characters. These add or remove sets of debugging data, respectively. For
+example, %-d+filter% adds filter debugging, whereas %-d-all+filter% selects
+only filter debugging. The available debugging categories are:
++
+&&&
+`acl            ` ACL interpretation
+`auth           ` authenticators
+`deliver        ` general delivery logic
+`dns            ` DNS lookups (see also resolver)
+`dnsbl          ` DNS black list (aka RBL) code
+`exec           ` arguments for ^^execv()^^ calls
+`expand         ` detailed debugging for string expansions
+`filter         ` filter handling
+`hints_lookup   ` hints data lookups
+`host_lookup    ` all types of name-to-IP address handling
+`ident          ` ident lookup
+`interface      ` lists of local interfaces
+`lists          ` matching things in lists
+`load           ` system load checks
+`local_scan     ` can be used by ^^local_scan()^^ (see chapter <<CHAPlocalscan>>)
+`lookup         ` general lookup code and all lookups
+`memory         ` memory handling
+`pid            ` add pid to debug output lines
+`process_info   ` setting info for the process log
+`queue_run      ` queue runs
+`receive        ` general message reception logic
+`resolver       ` turn on the DNS resolver's debugging output
+`retry          ` retry handling
+`rewrite        ` address rewriting
+`route          ` address routing
+`timestamp      ` add timestamp to debug output lines
+`tls            ` TLS logic
+`transport      ` transports
+`uid            ` changes of uid/gid and looking up uid/gid
+`verify         ` address verification logic
+`all            ` all of the above, and also %-v%
+&&&
++
+The
+cindex:[resolver, debugging output]
+cindex:[DNS resolver, debugging output]
+`resolver` option produces output only if the DNS resolver was compiled
+with DEBUG enabled. This is not the case in some operating systems. Also,
+unfortunately, debugging output from the DNS resolver is written to stdout
+rather than stderr.
++
+The default (%-d% with no argument) omits `expand`, `filter`,
+`interface`, `load`, `memory`, `pid`, `resolver`, and `timestamp`.
+However, the `pid` selector is forced when debugging is turned on for a
+daemon, which then passes it on to any re-executed Exims. Exim also
+automatically adds the pid to debug lines when several remote deliveries are
+run in parallel.
++
+The `timestamp` selector causes the current time to be inserted at the start
+of all debug output lines. This can be useful when trying to track down delays
+in processing.
++
+If the %debug_print% option is set in any driver, it produces output whenever
+any debugging is selected, or if %-v% is used.
+
+*-dd*<'debug~options'>::
+oindex:[%-dd%]
+This option behaves exactly like %-d% except when used on a command that
+starts a daemon process. In that case, debugging is turned off for the
+subprocesses that the daemon creates. Thus, it is useful for monitoring the
+behaviour of the daemon without creating as much output as full debugging does.
+
+*-dropcr*::
+oindex:[%-dropcr%]
+This is an obsolete option that is now a no-op. It used to affect the way Exim
+handled CR and LF characters in incoming messages. What happens now is
+described in section <<SECTlineendings>>.
+
+*-E*::
+oindex:[%-E%]
+cindex:[bounce message,generating]
+This option specifies that an incoming message is a locally-generated delivery
+failure report. It is used internally by Exim when handling delivery failures
+and is not intended for external use. Its only effect is to stop Exim
+generating certain messages to the postmaster, as otherwise message cascades
+could occur in some situations. As part of the same option, a message id may
+follow the characters %-E%. If it does, the log entry for the receipt of the
+new message contains the id, following ``R='', as a cross-reference.
+
+*-e*'x'::
+oindex:[%-e'x'%]
+There are a number of Sendmail options starting with %-oe% which seem to be
+called by various programs without the leading %o% in the option. For example,
+the %vacation% program uses %-eq%. Exim treats all options of the form
+%-e'x'% as synonymous with the corresponding %-oe'x'% options.
+
+*-F*~<'string'>::
+oindex:[%-F%]
+cindex:[sender,name]
+cindex:[name,of sender]
+This option sets the sender's full name for use when a locally-generated
+message is being accepted. In the absence of this option, the user's 'gecos'
+entry from the password data is used. As users are generally permitted to alter
+their 'gecos' entries, no security considerations are involved. White space
+between %-F% and the <'string'> is optional.
+
+*-f*~<'address'>::
+oindex:[%-f%]
+cindex:[sender,address]
+cindex:[address,sender]
+cindex:[trusted user]
+cindex:[envelope sender]
+cindex:[user,trusted]
+This option sets the address of the envelope sender of a locally-generated
+message (also known as the return path). The option can normally be used only
+by a trusted user, but %untrusted_set_sender% can be set to allow untrusted
+users to use it.
++
+Processes running as root or the Exim user are always trusted. Other
+trusted users are defined by the %trusted_users% or %trusted_groups% options.
+In the absence of %-f%, or if the caller is not trusted, the sender of a local
+message is set to the caller's login name at the default qualify domain.
++
+There is one exception to the restriction on the use of %-f%: an empty sender
+can be specified by any user, trusted or not, to create a message that can
+never provoke a bounce. An empty sender can be specified either as an empty
+string, or as a pair of angle brackets with nothing between them, as in these
+examples of shell commands:
+
+  exim -f '<>' user@domain
+  exim -f "" user@domain
++
+In addition, the use of %-f% is not restricted when testing a filter file with
+%-bf% or when testing or verifying addresses using the %-bt% or %-bv%
+options.
++
+Allowing untrusted users to change the sender address does not of itself make
+it possible to send anonymous mail. Exim still checks that the 'From:' header
+refers to the local user, and if it does not, it adds a 'Sender:' header,
+though this can be overridden by setting %no_local_from_check%.
++
+White
+cindex:[``From'' line]
+space between %-f% and the <'address'> is optional (that is, they can be given
+as two arguments or one combined argument). The sender of a locally-generated
+message can also be set (when permitted) by an initial ``From '' line in the
+message -- see the description of %-bm% above -- but if %-f% is also present,
+it overrides ``From''.
+
+*-G*::
+oindex:[%-G%]
+cindex:[Sendmail compatibility,%-G% option ignored]
+This is a Sendmail option which is ignored by Exim.
+
+*-h*~<'number'>::
+oindex:[%-h%]
+cindex:[Sendmail compatibility,%-h% option ignored]
+This option is accepted for compatibility with Sendmail, but has no effect. (In
+Sendmail it overrides the ``hop count'' obtained by counting 'Received:'
+headers.)
+
+*-i*::
+oindex:[%-i%]
+cindex:[Solaris,'mail' command]
+cindex:[dot in incoming, non-SMTP message]
+This option, which has the same effect as %-oi%, specifies that a dot on a line
+by itself should not terminate an incoming, non-SMTP message. I can find no
+documentation for this option in Solaris 2.4 Sendmail, but the 'mailx' command
+in Solaris 2.4 uses it. See also %-ti%.
+
+*-M*~<'message~id'>~<'message~id'>~...::
+oindex:[%-M%]
+cindex:[forcing delivery]
+cindex:[delivery,forcing attempt]
+cindex:[frozen messages,forcing delivery]
+This option requests Exim to run a delivery attempt on each message in turn. If
+any of the messages are frozen, they are automatically thawed before the
+delivery attempt. The settings of %queue_domains%, %queue_smtp_domains%, and
+%hold_domains% are ignored.
++
+Retry
+cindex:[hints database,overriding retry hints]
+hints for any of the addresses are overridden -- Exim tries to deliver even if
+the normal retry time has not yet been reached. This option requires the caller
+to be an admin user. However, there is an option called %prod_requires_admin%
+which can be set false to relax this restriction (and also the same requirement
+for the %-q%, %-R%, and %-S% options).
+
+*-Mar*~<'message~id'>~<'address'>~<'address'>~...::
+oindex:[%-Mar%]
+cindex:[message,adding recipients]
+cindex:[recipient,adding]
+This option requests Exim to add the addresses to the list of recipients of the
+message (``ar'' for ``add recipients''). The first argument must be a message id,
+and the remaining ones must be email addresses. However, if the message is
+active (in the middle of a delivery attempt), it is not altered. This option
+can be used only by an admin user.
+
+*-MC*~<'transport'>~<'hostname'>~<'sequence~number'>~<'message~id'>::
+oindex:[%-MC%]
+cindex:[SMTP,passed connection]
+cindex:[SMTP,multiple deliveries]
+cindex:[multiple SMTP deliveries]
+This option is not intended for use by external callers. It is used internally
+by Exim to invoke another instance of itself to deliver a waiting message using
+an existing SMTP connection, which is passed as the standard input. Details are
+given in chapter <<CHAPSMTP>>. This must be the final option, and the caller must
+be root or the Exim user in order to use it.
+
+*-MCA*::
+oindex:[%-MCA%]
+This option is not intended for use by external callers. It is used internally
+by Exim in conjunction with the %-MC% option. It signifies that the connection
+to the remote host has been authenticated.
+
+*-MCP*::
+oindex:[%-MCP%]
+This option is not intended for use by external callers. It is used internally
+by Exim in conjunction with the %-MC% option. It signifies that the server to
+which Exim is connected supports pipelining.
+
+*-MCQ*~<'process~id'>~<'pipe~fd'>::
+oindex:[%-MCQ%]
+This option is not intended for use by external callers. It is used internally
+by Exim in conjunction with the %-MC% option when the original delivery was
+started by a queue runner. It passes on the process id of the queue runner,
+together with the file descriptor number of an open pipe. Closure of the pipe
+signals the final completion of the sequence of processes that are passing
+messages through the same SMTP connection.
+
+*-MCS*::
+oindex:[%-MCS%]
+This option is not intended for use by external callers. It is used internally
+by Exim in conjunction with the %-MC% option, and passes on the fact that the
+SMTP SIZE option should be used on messages delivered down the existing
+connection.
+
+*-MCT*::
+oindex:[%-MCT%]
+This option is not intended for use by external callers. It is used internally
+by Exim in conjunction with the %-MC% option, and passes on the fact that the
+host to which Exim is connected supports TLS encryption.
+
+*-Mc*~<'message~id'>~<'message~id'>~...::
+oindex:[%-Mc%]
+cindex:[hints database,not overridden by %-Mc%]
+cindex:[delivery,manually started -- not forced]
+This option requests Exim to run a delivery attempt on each message in turn,
+but unlike the %-M% option, it does check for retry hints, and respects any
+that are found. This option is not very useful to external callers. It is
+provided mainly for internal use by Exim when it needs to re-invoke itself in
+order to regain root privilege for a delivery (see chapter <<CHAPsecurity>>).
+However, %-Mc% can be useful when testing, in order to run a delivery that
+respects retry times and other options such as %hold_domains% that are
+overridden when %-M% is used. Such a delivery does not count as a queue run.
+If you want to run a specific delivery as if in a queue run, you should use
+%-q% with a message id argument. A distinction between queue run deliveries
+and other deliveries is made in one or two places.
+
+*-Mes*~<'message~id'>~<'address'>::
+oindex:[%-Mes%]
+cindex:[message,changing sender]
+cindex:[sender,changing]
+This option requests Exim to change the sender address in the message to the
+given address, which must be a fully qualified address or ``<>'' (``es'' for ``edit
+sender''). There must be exactly two arguments. The first argument must be a
+message id, and the second one an email address. However, if the message is
+active (in the middle of a delivery attempt), its status is not altered. This
+option can be used only by an admin user.
+
+*-Mf*~<'message~id'>~<'message~id'>~...::
+oindex:[%-Mf%]
+cindex:[freezing messages]
+cindex:[message,manually freezing]
+This option requests Exim to mark each listed message as ``frozen''. This
+prevents any delivery attempts taking place until the message is ``thawed'',
+either manually or as a result of the %auto_thaw% configuration option.
+However, if any of the messages are active (in the middle of a delivery
+attempt), their status is not altered. This option can be used only by an admin
+user.
+
+*-Mg*~<'message~id'>~<'message~id'>~...::
+oindex:[%-Mg%]
+cindex:[giving up on messages]
+cindex:[message,abandoning delivery attempts]
+cindex:[delivery,abandoning further attempts]
+This option requests Exim to give up trying to deliver the listed messages,
+including any that are frozen. However, if any of the messages are active,
+their status is not altered. For non-bounce messages, a delivery error message
+is sent to the sender, containing the text ``cancelled by administrator''.
+Bounce messages are just discarded. This option can be used only by an admin
+user.
+
+*-Mmad*~<'message~id'>~<'message~id'>~...::
+oindex:[%-Mmad%]
+cindex:[delivery,cancelling all]
+This option requests Exim to mark all the recipient addresses in the messages
+as already delivered (``mad'' for ``mark all delivered''). However, if any
+message is active (in the middle of a delivery attempt), its status is not
+altered. This option can be used only by an admin user.
+
+*-Mmd*~<'message~id'>~<'address'>~<'address'>~...::
+oindex:[%-Mmd%]
+cindex:[delivery,cancelling by address]
+cindex:[recipient,removing]
+cindex:[removing recipients]
+This option requests Exim to mark the given addresses as already delivered
+(``md'' for ``mark delivered''). The first argument must be a message id, and
+the remaining ones must be email addresses. These are matched to recipient
+addresses in the message in a case-sensitive manner. If the message is active
+(in the middle of a delivery attempt), its status is not altered. This option
+can be used only by an admin user.
+
+*-Mrm*~<'message~id'>~<'message~id'>~...::
+oindex:[%-Mrm%]
+cindex:[removing messages]
+cindex:[abandoning mail]
+cindex:[message,manually discarding]
+This option requests Exim to remove the given messages from the queue. No
+bounce messages are sent; each message is simply forgotten. However, if any of
+the messages are active, their status is not altered. This option can be used
+only by an admin user or by the user who originally caused the message to be
+placed on the queue.
+
+*-Mt*~<'message~id'>~<'message~id'>~...::
+oindex:[%-Mt%]
+cindex:[thawing messages]
+cindex:[unfreezing messages]
+cindex:[frozen messages,thawing]
+cindex:[message,thawing frozen]
+This option requests Exim to ``thaw'' any of the listed messages that are
+``frozen'', so that delivery attempts can resume. However, if any of the messages
+are active, their status is not altered. This option can be used only by an
+admin user.
+
+*-Mvb*~<'message~id'>::
+oindex:[%-Mvb%]
+cindex:[listing,message body]
+cindex:[message,listing body of]
+This option causes the contents of the message body (-D) spool file to be
+written to the standard output. This option can be used only by an admin user.
+
+*-Mvh*~<'message~id'>::
+oindex:[%-Mvh%]
+cindex:[listing,message headers]
+cindex:[header lines,listing]
+cindex:[message,listing header lines]
+This option causes the contents of the message headers (-H) spool file to be
+written to the standard output. This option can be used only by an admin user.
+
+*-Mvl*~<'message~id'>::
+oindex:[%-Mvl%]
+cindex:[listing,message log]
+cindex:[message,listing message log]
+This option causes the contents of the message log spool file to be written to
+the standard output. This option can be used only by an admin user.
+
+*-m*::
+oindex:[%-m%]
+This is apparently a synonym for %-om% that is accepted by Sendmail, so Exim
+treats it that way too.
+
+*-N*::
+oindex:[%-N%]
+cindex:[debugging,%-N% option]
+cindex:[debugging,suppressing delivery]
+This is a debugging option that inhibits delivery of a message at the transport
+level. It implies %-v%. Exim goes through many of the motions of delivery --
+it just doesn't actually transport the message, but instead behaves as if it
+had successfully done so. However, it does not make any updates to the retry
+database, and the log entries for deliveries are flagged with ``\*>'' rather
+than ``=>''.
++
+Because %-N% discards any message to which it applies, only root or the Exim
+user are allowed to use it with %-bd%, %-q%, %-R% or %-M%. In other words,
+an ordinary user can use it only when supplying an incoming message to which it
+will apply. Although transportation never fails when %-N% is set, an address
+may be deferred because of a configuration problem on a transport, or a routing
+problem. Once %-N% has been used for a delivery attempt, it sticks to the
+message, and applies to any subsequent delivery attempts that may happen for
+that message.
+
+*-n*::
+oindex:[%-n%]
+cindex:[Sendmail compatibility,%-n% option ignored]
+This option is interpreted by Sendmail to mean ``no aliasing''. It is ignored by
+Exim.
+
+*-O*~<'data'>::
+oindex:[%-O%]
+This option is interpreted by Sendmail to mean `set option`. It is ignored by
+Exim.
+
+*-oA*~<'file~name'>::
+oindex:[%-oA%]
+cindex:[Sendmail compatibility,%-oA% option]
+This option is used by Sendmail in conjunction with %-bi% to specify an
+alternative alias file name. Exim handles %-bi% differently; see the
+description above.
+
+*-oB*~<'n'>::
+oindex:[%-oB%]
+cindex:[SMTP,passed connection]
+cindex:[SMTP,multiple deliveries]
+cindex:[multiple SMTP deliveries]
+This is a debugging option which limits the maximum number of messages that can
+be delivered down one SMTP connection, overriding the value set in any ^smtp^
+transport. If <'n'> is omitted, the limit is set to 1.
+
+*-odb*::
+oindex:[%-odb%]
+cindex:[background delivery]
+cindex:[delivery,in the background]
+This option applies to all modes in which Exim accepts incoming messages,
+including the listening daemon. It requests ``background'' delivery of such
+messages, which means that the accepting process automatically starts a
+delivery process for each message received, but does not wait for the delivery
+processes to finish.
++
+When all the messages have been received, the reception process exits,
+leaving the delivery processes to finish in their own time. The standard output
+and error streams are closed at the start of each delivery process.
+This is the default action if none of the %-od% options are present.
++
+If one of the queueing options in the configuration file
+(%queue_only% or %queue_only_file%, for example) is in effect, %-odb%
+overrides it if %queue_only_override% is set true, which is the default
+setting. If %queue_only_override% is set false, %-odb% has no effect.
+
+*-odf*::
+oindex:[%-odf%]
+cindex:[foreground delivery]
+cindex:[delivery,in the foreground]
+This option requests ``foreground'' (synchronous) delivery when Exim has accepted
+a locally-generated message. (For the daemon it is exactly the same as
+%-odb%.) A delivery process is automatically started to deliver the
+message, and Exim waits for it to complete before proceeding.
++
+The original Exim reception process does not finish until the delivery
+process for the final message has ended. The standard error stream is left open
+during deliveries.
++
+However, like %-odb%, this option has no effect if %queue_only_override% is
+false and one of the queueing options in the configuration file is in effect.
++
+If there is a temporary delivery error during foreground delivery, the
+message is left on the queue for later delivery, and the original reception
+process exists. See chapter <<CHAPnonqueueing>> for a way of setting up a
+restricted configuration that never queues messages.
+
+
+*-odi*::
+oindex:[%-odi%]
+This option is synonymous with %-odf%. It is provided for compatibility with
+Sendmail.
+
+*-odq*::
+oindex:[%-odq%]
+cindex:[non-immediate delivery]
+cindex:[delivery,suppressing immediate]
+cindex:[queueing incoming messages]
+This option applies to all modes in which Exim accepts incoming messages,
+including the listening daemon. It specifies that the accepting process should
+not automatically start a delivery process for each message received. Messages
+are placed on the queue, and remain there until a subsequent queue runner
+process encounters them. There are several configuration options (such as
+%queue_only%) that can be used to queue incoming messages under certain
+conditions. This option overrides all of them and also %-odqs%. It always
+forces queueing.
+
+*-odqs*::
+oindex:[%-odqs%]
+cindex:[SMTP,delaying delivery]
+This option is a hybrid between %-odb%/%-odi% and %-odq%.
+However, like %-odb% and %-odi%, this option has no effect if
+%queue_only_override% is false and one of the queueing options in the
+configuration file is in effect.
++
+When %-odqs% does operate, a delivery process is started for each incoming
+message, in the background by default, but in the foreground if %-odi% is also
+present. The recipient addresses are routed, and local deliveries are done in
+the normal way. However, if any SMTP deliveries are required, they are not done
+at this time, so the message remains on the queue until a subsequent queue
+runner process encounters it. Because routing was done, Exim knows which
+messages are waiting for which hosts, and so a number of messages for the same
+host can be sent in a single SMTP connection. The %queue_smtp_domains%
+configuration option has the same effect for specific domains. See also the
+%-qq% option.
+
+*-oee*::
+oindex:[%-oee%]
+cindex:[error,reporting]
+If an error is detected while a non-SMTP message is being received (for
+example, a malformed address), the error is reported to the sender in a mail
+message.
++
+Provided
+cindex:[return code,for %-oee%]
+this error message is successfully sent, the Exim receiving process
+exits with a return code of zero. If not, the return code is 2 if the problem
+is that the original message has no recipients, or 1 any other error. This is
+the default %-oe'x'% option if Exim is called as 'rmail'.
+
+*-oem*::
+oindex:[%-oem%]
+cindex:[error,reporting]
+cindex:[return code,for %-oem%]
+This is the same as %-oee%, except that Exim always exits with a non-zero
+return code, whether or not the error message was successfully sent.
+This is the default %-oe'x'% option, unless Exim is called as 'rmail'.
+
+*-oep*::
+oindex:[%-oep%]
+cindex:[error,reporting]
+If an error is detected while a non-SMTP message is being received, the
+error is reported by writing a message to the standard error file (stderr).
+cindex:[return code,for %-oep%]
+The return code is 1 for all errors.
+
+*-oeq*::
+oindex:[%-oeq%]
+cindex:[error,reporting]
+This option is supported for compatibility with Sendmail, but has the same
+effect as %-oep%.
+
+*-oew*::
+oindex:[%-oew%]
+cindex:[error,reporting]
+This option is supported for compatibility with Sendmail, but has the same
+effect as %-oem%.
+
+*-oi*::
+oindex:[%-oi%]
+cindex:[dot in incoming, non-SMTP message]
+This option, which has the same effect as %-i%, specifies that a dot on a line
+by itself should not terminate an incoming, non-SMTP message.
+Otherwise, a single dot does terminate, though Exim does no special processing
+for other lines that start with a dot.
+This option is set by default if Exim is called as 'rmail'. See also %-ti%.
+
+*-oitrue*::
+oindex:[%-oitrue%]
+This option is treated as synonymous with %-oi%.
+
+*-oMa*~<'host~address'>::
+oindex:[%-oMa%]
+cindex:[sender host address, specifying for local message]
+A number of options starting with %-oM% can be used to set values associated
+with remote hosts on locally-submitted messages (that is, messages not received
+over TCP/IP). These options can be used by any caller in conjunction with the
+%-bh%, %-be%, %-bf%, %-bF%, %-bt%, or %-bv% testing options. In other
+circumstances, they are ignored unless the caller is trusted.
++
+The %-oMa% option sets the sender host address. This may include a port number
+at the end, after a full stop (period). For example:
+
+  exim -bs -oMa 10.9.8.7.1234
++
+An alternative syntax is to enclose the IP address in square brackets,
+followed by a colon and the port number:
+
+  exim -bs -oMa [10.9.8.7]:1234
++
+The IP address is placed in the $sender_host_address$ variable, and the
+port, if present, in $sender_host_port$.
+
+*-oMaa*~<'name'>::
+oindex:[%-oMaa%]
+cindex:[authentication name, specifying for local message]
+See %-oMa% above for general remarks about the %-oM% options. The %-oMaa%
+option sets the value of $sender_host_authenticated$ (the authenticator
+name). See chapter <<CHAPSMTPAUTH>> for a discussion of SMTP authentication.
+
+*-oMai*~<'string'>::
+oindex:[%-oMai%]
+cindex:[authentication id, specifying for local message]
+See %-oMa% above for general remarks about the %-oM% options. The %-oMai%
+option sets the value of $authenticated_id$ (the id that was authenticated).
+This overrides the default value (the caller's login id) for messages from
+local sources. See chapter <<CHAPSMTPAUTH>> for a discussion of authenticated
+ids.
+
+*-oMas*~<'address'>::
+oindex:[%-oMas%]
+cindex:[authentication sender, specifying for local message]
+See %-oMa% above for general remarks about the %-oM% options. The %-oMas%
+option sets the authenticated sender value in $authenticated_sender$. It
+overrides the sender address that is created from the caller's login id for
+messages from local sources. See chapter <<CHAPSMTPAUTH>> for a discussion of
+authenticated senders.
+
+*-oMi*~<'interface~address'>::
+oindex:[%-oMi%]
+cindex:[interface address, specifying for local message]
+See %-oMa% above for general remarks about the %-oM% options. The %-oMi% option
+sets the IP interface address value. A port number may be included, using the
+same syntax as for %-oMa%. The interface address is placed in
+$interface_address$ and the port number, if present, in $interface_port$.
+
+*-oMr*~<'protocol~name'>::
+oindex:[%-oMr%]
+cindex:[protocol,incoming -- specifying for local message]
+See %-oMa% above for general remarks about the %-oM% options. The %-oMr% option
+sets the received protocol value that is stored in $received_protocol$.
+However, this applies only when %-bs% is not used. For interactive SMTP input
+(%-bs%), the protocol is always ``local-'' followed by one of the standard SMTP
+protocol names (see the description of $received_protocol$ in section
+<<SECTexpvar>>). For %-bS% (batch SMTP) however, the protocol can be set by
+<<%-oMr%.
+
+*-oMs*~<'host~name'>::
+oindex:[%-oMs%]
+cindex:[sender host name, specifying for local message]
+See %-oMa% above for general remarks about the %-oM% options. The %-oMs% option
+sets the sender host name in $sender_host_name$. When this option is present,
+Exim does not attempt to look up a host name from an IP address; it uses the
+name it is given.
+
+*-oMt*~<'ident~string'>::
+oindex:[%-oMt%]
+cindex:[sender ident string, specifying for local message]
+See %-oMa% above for general remarks about the %-oM% options. The %-oMt% option
+sets the sender ident value in $sender_ident$. The default setting for local
+callers is the login id of the calling process.
+
+*-om*::
+oindex:[%-om%]
+cindex:[Sendmail compatibility,%-om% option ignored]
+In Sendmail, this option means ``me too'', indicating that the sender of a
+message should receive a copy of the message if the sender appears in an alias
+expansion. Exim always does this, so the option does nothing.
+
+*-oo*::
+oindex:[%-oo%]
+cindex:[Sendmail compatibility,%-oo% option ignored]
+This option is ignored. In Sendmail it specifies ``old style headers'', whatever
+that means.
+
+*-oP*~<'path'>::
+oindex:[%-oP%]
+cindex:[pid (process id),of daemon]
+cindex:[daemon,process id (pid)]
+This option is useful only in conjunction with %-bd% or %-q% with a time
+value. The option specifies the file to which the process id of the daemon is
+written. When %-oX% is used with %-bd%, or when %-q% with a time is used
+without %-bd%, this is the only way of causing Exim to write a pid file,
+because in those cases, the normal pid file is not used.
+
+*-or*~<'time'>::
+oindex:[%-or%]
+cindex:[timeout,for non-SMTP input]
+This option sets a timeout value for incoming non-SMTP messages. If it is not
+set, Exim will wait forever for the standard input. The value can also be set
+by the %receive_timeout% option. The format used for specifying times is
+described in section <<SECTtimeformat>>.
+
+*-os*~<'time'>::
+oindex:[%-os%]
+cindex:[timeout,for SMTP input]
+cindex:[SMTP timeout, input]
+This option sets a timeout value for incoming SMTP messages. The timeout
+applies to each SMTP command and block of data. The value can also be set by
+the %smtp_receive_timeout% option; it defaults to 5 minutes. The format used
+for specifying times is described in section <<SECTtimeformat>>.
+
+*-ov*::
+oindex:[%-ov%]
+This option has exactly the same effect as %-v%.
+
+*-oX*~<'number~or~string'>::
+oindex:[%-oX%]
+cindex:[TCP/IP,setting listening ports]
+cindex:[TCP/IP,setting listening interfaces]
+cindex:[port,receiving TCP/IP]
+This option is relevant only when the %-bd% (start listening daemon) option is
+also given. It controls which ports and interfaces the daemon uses. Details of
+the syntax, and how it interacts with configuration file options, are given in
+chapter <<CHAPinterfaces>>. When %-oX% is used to start a daemon, no pid file is
+written unless %-oP% is also present to specify a pid file name.
+
+*-pd*::
+oindex:[%-pd%]
+cindex:[Perl,starting the interpreter]
+This option applies when an embedded Perl interpreter is linked with Exim (see
+chapter <<CHAPperl>>). It overrides the setting of the %perl_at_start% option,
+forcing the starting of the interpreter to be delayed until it is needed.
+
+*-ps*::
+oindex:[%-ps%]
+cindex:[Perl,starting the interpreter]
+This option applies when an embedded Perl interpreter is linked with Exim (see
+chapter <<CHAPperl>>). It overrides the setting of the %perl_at_start% option,
+forcing the starting of the interpreter to occur as soon as Exim is started.
+
+*-p*<'rval'>:<'sval'>::
+oindex:[%-p%]
+For compatibility with Sendmail, this option is equivalent to
+
+  -oMr <rval> -oMs <sval>
++
+It sets the incoming protocol and host name (for trusted callers). The
+host name and its colon can be omitted when only the protocol is to be set.
+Note the Exim already has two private options, %-pd% and %-ps%, that refer to
+embedded Perl. It is therefore impossible to set a protocol value of `p` or
+`s` using this option (but that does not seem a real limitation).
+
+*-q*::
+oindex:[%-q%]
+cindex:[queue runner,starting manually]
+This option is normally restricted to admin users. However, there is a
+configuration option called %prod_requires_admin% which can be set false to
+relax this restriction (and also the same requirement for the %-M%, %-R%, and
+%-S% options).
++
+The
+cindex:[queue runner,description of operation]
+%-q% option starts one queue runner process. This scans the queue of
+waiting messages, and runs a delivery process for each one in turn. It waits
+for each delivery process to finish before starting the next one. A delivery
+process may not actually do any deliveries if the retry times for the addresses
+have not been reached. Use %-qf% (see below) if you want to override this.
++
+If
+cindex:[SMTP,passed connection]
+cindex:[SMTP,multiple deliveries]
+cindex:[multiple SMTP deliveries]
+the delivery process spawns other processes to deliver other messages down
+passed SMTP connections, the queue runner waits for these to finish before
+proceeding.
++
+When all the queued messages have been considered, the original queue runner
+process terminates. In other words, a single pass is made over the waiting
+mail, one message at a time. Use %-q% with a time (see below) if you want this
+to be repeated periodically.
++
+Exim processes the waiting messages in an unpredictable order. It isn't very
+random, but it is likely to be different each time, which is all that matters.
+If one particular message screws up a remote MTA, other messages to the same
+MTA have a chance of getting through if they get tried first.
++
+It is possible to cause the messages to be processed in lexical message id
+order, which is essentially the order in which they arrived, by setting the
+%queue_run_in_order% option, but this is not recommended for normal use.
+
+*-q*<'qflags'>::
+The %-q% option may be followed by one or more flag letters that change its
+behaviour. They are all optional, but if more than one is present, they must
+appear in the correct order. Each flag is described in a separate item below.
+
+*-qq...*::
+oindex:[%-qq%]
+cindex:[queue,double scanning]
+cindex:[queue,routing]
+cindex:[routing,whole queue before delivery]
+An option starting with %-qq% requests a two-stage queue run. In the first
+stage, the queue is scanned as if the %queue_smtp_domains% option matched
+every domain. Addresses are routed, local deliveries happen, but no remote
+transports are run.
++
+The
+cindex:[hints database,remembering routing]
+hints database that remembers which messages are waiting for specific hosts is
+updated, as if delivery to those hosts had been deferred. After this is
+complete, a second, normal queue scan happens, with routing and delivery taking
+place as normal. Messages that are routed to the same host should mostly be
+delivered down a single SMTP
+cindex:[SMTP,passed connection]
+cindex:[SMTP,multiple deliveries]
+cindex:[multiple SMTP deliveries]
+connection because of the hints that were set up during the first queue scan.
+This option may be useful for hosts that are connected to the Internet
+intermittently.
+
+*-q[q]i...*::
+oindex:[%-qi%]
+cindex:[queue,initial delivery]
+If the 'i' flag is present, the queue runner runs delivery processes only for
+those messages that haven't previously been tried. ('i' stands for ``initial
+delivery''.) This can be helpful if you are putting messages on the queue using
+%-odq% and want a queue runner just to process the new messages.
+
+*-q[q][i]f...*::
+oindex:[%-qf%]
+cindex:[queue,forcing delivery]
+cindex:[delivery,forcing in queue run]
+If one 'f' flag is present, a delivery attempt is forced for each non-frozen
+message, whereas without %f% only those non-frozen addresses that have passed
+their retry times are tried.
+
+*-q[q][i]ff...*::
+oindex:[%-qff%]
+cindex:[frozen messages,forcing delivery]
+If 'ff' is present, a delivery attempt is forced for every message, whether
+frozen or not.
+
+*-q[q][i][f[f]]l*::
+oindex:[%-ql%]
+cindex:[queue,local deliveries only]
+The 'l' (the letter ``ell'') flag specifies that only local deliveries are to be
+done. If a message requires any remote deliveries, it remains on the queue for
+later delivery.
+
+*-q*<'qflags'>~<'start~id'>~<'end~id'>::
+cindex:[queue,delivering specific messages]
+When scanning the queue, Exim can be made to skip over messages whose ids are
+lexically less than a given value by following the %-q% option with a starting
+message id. For example:
+
+  exim -q 0t5C6f-0000c8-00
++
+Messages that arrived earlier than `0t5C6f-0000c8-00` are not inspected. If a
+second message id is given, messages whose ids are lexically greater than it
+are also skipped. If the same id is given twice, for example,
+
+  exim -q 0t5C6f-0000c8-00 0t5C6f-0000c8-00
++
+just one delivery process is started, for that message. This differs from %-M%
+in that retry data is respected, and it also differs from %-Mc% in that it
+counts as a delivery from a queue run. Note that the selection mechanism does
+not affect the order in which the messages are scanned. There are also other
+ways of selecting specific sets of messages for delivery in a queue run -- see
+%-R% and %-S%.
+
+*-q*<'qflags'><'time'>::
+cindex:[queue runner,starting periodically]
+cindex:[periodic queue running]
+When a time value is present, the %-q% option causes Exim to run as a daemon,
+starting a queue runner process at intervals specified by the given time value
+(whose format is described in section <<SECTtimeformat>>). This form of the %-q%
+option is commonly combined with the %-bd% option, in which case a single
+daemon process handles both functions. A common way of starting up a combined
+daemon at system boot time is to use a command such as
+
+  /usr/exim/bin/exim -bd -q30m
++
+Such a daemon listens for incoming SMTP calls, and also starts a queue runner
+process every 30 minutes.
++
+When a daemon is started by %-q% with a time value, but without %-bd%, no pid
+file is written unless one is explicitly requested by the %-oP% option.
+
+*-qR*<'rsflags'>~<'string'>::
+oindex:[%-qR%]
+This option is synonymous with %-R%. It is provided for Sendmail compatibility.
+
+*-qS*<'rsflags'>~<'string'>::
+oindex:[%-qS%]
+This option is synonymous with %-S%.
+
+*-R*<'rsflags'>~<'string'>::
+oindex:[%-R%]
+cindex:[queue runner,for specific recipients]
+cindex:[delivery,to given domain]
+cindex:[domain,delivery to]
+The <'rsflags'> may be empty, in which case the white space before the string
+is optional, unless the string is 'f', 'ff', 'r', 'rf', or 'rff', which are the
+possible values for <'rsflags'>. White space is required if <'rsflags'> is not
+empty.
++
+This option is similar to %-q% with no time value, that is, it causes Exim to
+perform a single queue run, except that, when scanning the messages on the
+queue, Exim processes only those that have at least one undelivered recipient
+address containing the given string, which is checked in a case-independent
+way. If the <'rsflags'> start with 'r', <'string'> is interpreted as a regular
+expression; otherwise it is a literal string.
++
+Once a message is selected, all its addresses are processed. For the first
+selected message, Exim overrides any retry information and forces a delivery
+attempt for each undelivered address. This means that if delivery of any
+address in the first message is successful, any existing retry information is
+deleted, and so delivery attempts for that address in subsequently selected
+messages (which are processed without forcing) will run. However, if delivery
+of any address does not succeed, the retry information is updated, and in
+subsequently selected messages, the failing address will be skipped.
++
+If the <'rsflags'> contain 'f' or 'ff', the delivery forcing applies to all
+selected messages, not just the first;
+cindex:[frozen messages,forcing delivery]
+frozen messages are included when 'ff' is present.
++
+The %-R% option makes it straightforward to initiate delivery of all messages
+to a given domain after a host has been down for some time. When the SMTP
+command ETRN is accepted by its ACL (see chapter <<CHAPACL>>), its default
+effect is to run Exim with the %-R% option, but it can be configured to run an
+arbitrary command instead.
+
+*-r*::
+oindex:[%-r%]
+This is a documented (for Sendmail) obsolete alternative name for %-f%.
+
+*-S*<'rsflags'>~<'string'>::
+oindex:[%-S%]
+cindex:[delivery,from given sender]
+cindex:[queue runner,for specific senders]
+This option acts like %-R% except that it checks the string against each
+message's sender instead of against the recipients. If %-R% is also set, both
+conditions must be met for a message to be selected. If either of the options
+has 'f' or 'ff' in its flags, the associated action is taken.
+
+*-Tqt*~<'times'>::
+oindex:[%-Tqt%]
+This an option that is exclusively for use by the Exim testing suite. It is not
+recognized when Exim is run normally. It allows for the setting up of explicit
+``queue times'' so that various warning/retry features can be tested.
+
+*-t*::
+oindex:[%-t%]
+cindex:[recipient,extracting from header lines]
+cindex:['Bcc:' header line]
+cindex:['Cc:' header line]
+cindex:['To:' header line]
+When Exim is receiving a locally-generated, non-SMTP message on its standard
+input, the %-t% option causes the recipients of the message to be obtained
+from the 'To:', 'Cc:', and 'Bcc:' header lines in the message instead of from
+the command arguments. The addresses are extracted before any rewriting takes
+place.
++
+If
+cindex:[Sendmail compatibility,%-t% option]
+the command has any arguments, they specify addresses to which the message
+is 'not' to be delivered. That is, the argument addresses are removed from
+the recipients list obtained from the headers. This is compatible with Smail 3
+and in accordance with the documented behaviour of several versions of
+Sendmail, as described in man pages on a number of operating systems (e.g.
+Solaris 8, IRIX 6.5, HP-UX 11). However, some versions of Sendmail 'add'
+argument addresses to those obtained from the headers, and the O'Reilly
+Sendmail book documents it that way. Exim can be made to add argument addresses
+instead of subtracting them by setting the option
+%extract_addresses_remove_arguments% false.
++
+If a 'Bcc:' header line is present, it is removed from the message unless
+there is no 'To:' or 'Cc:', in which case a 'Bcc:' line with no data is
+created. This is necessary for conformity with the original RFC 822 standard;
+the requirement has been removed in RFC 2822, but that is still very new.
++
+If
+cindex:[%Resent-% header lines,with %-t%]
+there are any %Resent-% header lines in the message, Exim extracts
+recipients from all 'Resent-To:', 'Resent-Cc:', and 'Resent-Bcc:' header
+lines instead of from 'To:', 'Cc:', and 'Bcc:'. This is for compatibility
+with Sendmail and other MTAs. (Prior to release 4.20, Exim gave an error if
+%-t% was used in conjunction with %Resent-% header lines.)
++
+RFC 2822 talks about different sets of %Resent-% header lines (for when a
+message is resent several times). The RFC also specifies that they should be
+added at the front of the message, and separated by 'Received:' lines. It is
+not at all clear how %-t% should operate in the present of multiple sets,
+nor indeed exactly what constitutes a ``set''.
+In practice, it seems that MUAs do not follow the RFC. The %Resent-% lines are
+often added at the end of the header, and if a message is resent more than
+once, it is common for the original set of %Resent-% headers to be renamed as
+%X-Resent-% when a new set is added. This removes any possible ambiguity.
+
+*-ti*::
+oindex:[%-ti%]
+This option is exactly equivalent to %-t% %-i%. It is provided for
+compatibility with Sendmail.
+
+*-tls-on-connect*::
+oindex:[%-tls-on-connect%]
+cindex:[TLS,use without STARTTLS]
+cindex:[TLS,automatic start]
+This option is available when Exim is compiled with TLS support. It forces all
+incoming SMTP connections to behave as if the incoming port is listed in the
+%tls_on_connect_ports% option. See section <<SECTsupobssmt>> and chapter
+<<CHAPTLS>> for further details.
+
+
+*-U*::
+oindex:[%-U%]
+cindex:[Sendmail compatibility,%-U% option ignored]
+Sendmail uses this option for ``initial message submission'', and its
+documentation states that in future releases, it may complain about
+syntactically invalid messages rather than fixing them when this flag is not
+set. Exim ignores this option.
+
+*-v*::
+oindex:[%-v%]
+This option causes Exim to write information to the standard error stream,
+describing what it is doing. In particular, it shows the log lines for
+receiving and delivering a message, and if an SMTP connection is made, the SMTP
+dialogue is shown. Some of the log lines shown may not actually be written to
+the log if the setting of %log_selector% discards them. Any relevant selectors
+are shown with each log line. If none are shown, the logging is unconditional.
+
+*-x*::
+oindex:[%-x%]
+AIX uses %-x% for a private purpose (``mail from a local mail program has
+National Language Support extended characters in the body of the mail item'').
+It sets %-x% when calling the MTA from its %mail% command. Exim ignores this
+option.
+
+///
+We insert a stylized DocBook comment here, to identify the end of the command
+line options. This is for the benefit of the Perl script that automatically
+creates a man page for the options.
+///
+
+++++
+<!-- === End of command line options === -->
+++++
+
+
+
+
+
+////////////////////////////////////////////////////////////////////////////
+////////////////////////////////////////////////////////////////////////////
+
+
+[[CHAPconf]]
+[titleabbrev="The runtime configuration file"]
+The Exim run time configuration file
+------------------------------------
+
+cindex:[run time configuration]
+cindex:[configuration file,general description]
+cindex:[CONFIGURE_FILE]
+cindex:[configuration file,errors in]
+cindex:[error,in configuration file]
+cindex:[return code,for bad configuration]
+Exim uses a single run time configuration file that is read whenever an Exim
+binary is executed. Note that in normal operation, this happens frequently,
+because Exim is designed to operate in a distributed manner, without central
+control.
+
+If a syntax error is detected while reading the configuration file, Exim
+writes a message on the standard error, and exits with a non-zero return code.
+The message is also written to the panic log. *Note*: only simple syntax
+errors can be detected at this time. The values of any expanded options are
+not checked until the expansion happens, even when the expansion does not
+actually alter the string.
+
+
+
+The name of the configuration file is compiled into the binary for security
+reasons, and is specified by the CONFIGURE_FILE compilation option. In
+most configurations, this specifies a single file. However, it is permitted to
+give a colon-separated list of file names, in which case Exim uses the first
+existing file in the list.
+
+cindex:[EXIM_USER]
+cindex:[EXIM_GROUP]
+cindex:[CONFIGURE_OWNER]
+cindex:[CONFIGURE_GROUP]
+cindex:[configuration file,ownership]
+cindex:[ownership,configuration file]
+The run time configuration file must be owned by root or by the user that is
+specified at compile time by the EXIM_USER option, or by the user that is
+specified at compile time by the CONFIGURE_OWNER option (if set). The
+configuration file must not be world-writeable or group-writeable, unless its
+group is the one specified at compile time by the EXIM_GROUP option
+
+or by the CONFIGURE_GROUP option.
+
+
+*Warning*: In a conventional configuration, where the Exim binary is setuid
+to root, anybody who is able to edit the run time configuration file has an
+easy way to run commands as root. If you make your mail administrators members
+of the Exim group, but do not trust them with root, make sure that the run time
+configuration is not group writeable.
+
+A default configuration file, which will work correctly in simple situations,
+is provided in the file _src/configure.default_. If CONFIGURE_FILE
+defines just one file name, the installation process copies the default
+configuration to a new file of that name if it did not previously exist. If
+CONFIGURE_FILE is a list, no default is automatically installed. Chapter
+<<CHAPdefconfil>> is a ``walk-through'' discussion of the default configuration.
+
+
+
+Using a different configuration file
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+cindex:[configuration file,alternate]
+A one-off alternate configuration can be specified by the %-C% command line
+option, which may specify a single file or a list of files. However, when %-C%
+is used, Exim gives up its root privilege, unless called by root or the Exim
+user (or unless the argument for %-C% is identical to the built-in value from
+CONFIGURE_FILE). %-C% is useful mainly for checking the syntax of
+configuration files before installing them. No owner or group checks are done
+on a configuration file specified by %-C%.
+
+The privileged use of %-C% by the Exim user can be locked out by setting
+ALT_CONFIG_ROOT_ONLY in _Local/Makefile_ when building Exim. However,
+if you do this, you also lock out the possibility of testing a
+configuration using %-C% right through message reception and delivery, even if
+the caller is root. The reception works, but by that time, Exim is running as
+the Exim user, so when it re-execs to regain privilege for the delivery, the
+use of %-C% causes privilege to be lost. However, root can test reception and
+delivery using two separate commands (one to put a message on the queue, using
+%-odq%, and another to do the delivery, using %-M%).
+
+If ALT_CONFIG_PREFIX is defined _in Local/Makefile_, it specifies a
+prefix string with which any file named in a %-C% command line option must
+start. In addition, the file name must not contain the sequence `/../`. There
+is no default setting for ALT_CONFIG_PREFIX; when it is unset, any file
+name can be used with %-C%.
+
+One-off changes to a configuration can be specified by the %-D% command line
+option, which defines and overrides values for macros used inside the
+configuration file. However, like %-C%, the use of this option by a
+non-privileged user causes Exim to discard its root privilege.
+If DISABLE_D_OPTION is defined in _Local/Makefile_, the use of %-D% is
+completely disabled, and its use causes an immediate error exit.
+
+Some sites may wish to use the same Exim binary on different machines that
+share a file system, but to use different configuration files on each machine.
+If CONFIGURE_FILE_USE_NODE is defined in _Local/Makefile_, Exim first
+looks for a file whose name is the configuration file name followed by a dot
+and the machine's node name, as obtained from the 'uname()' function. If this
+file does not exist, the standard name is tried. This processing occurs for
+each file name in the list given by CONFIGURE_FILE or %-C%.
+
+In some esoteric situations different versions of Exim may be run under
+different effective uids and the CONFIGURE_FILE_USE_EUID is defined to
+help with this. See the comments in _src/EDITME_ for details.
+
+
+
+[[SECTconffilfor]]
+Configuration file format
+~~~~~~~~~~~~~~~~~~~~~~~~~
+cindex:[configuration file,format of]
+cindex:[format,configuration file]
+Exim's configuration file is divided into a number of different parts. General
+option settings must always appear at the start of the file. The other parts
+are all optional, and may appear in any order. Each part other than the first
+is introduced by the word ``begin'' followed by the name of the part. The
+optional parts are:
+
+- 'ACL': Access control lists for controlling incoming SMTP mail.
+
+- cindex:[AUTH,configuration]
+'authenticators': Configuration settings for the authenticator drivers. These
+are concerned with the SMTP AUTH command (see chapter <<CHAPSMTPAUTH>>).
+
+- 'routers': Configuration settings for the router drivers. Routers process
+addresses and determine how the message is to be delivered.
+
+- 'transports': Configuration settings for the transport drivers. Transports
+define mechanisms for copying messages to destinations.
+
+- 'retry': Retry rules, for use when a message cannot be immediately delivered.
+
+- 'rewrite': Global address rewriting rules, for use when a message arrives and
+when new addresses are generated during delivery.
+
+- 'local_scan': Private options for the 'local_scan()' function. If you
+want to use this feature, you must set
+
+  LOCAL_SCAN_HAS_OPTIONS=yes
++
+in _Local/Makefile_ before building Exim. Full details of the
+'local_scan()' facility are given in chapter <<CHAPlocalscan>>.
+
+cindex:[configuration file,leading whitespace in]
+cindex:[configuration file,trailing whitespace in]
+cindex:[whitespace,in configuration file]
+Leading and trailing whitespace in configuration lines is always ignored.
+
+Blank lines in the file, and lines starting with a # character (ignoring
+leading white space) are treated as comments and are ignored. *Note*: a
+# character other than at the beginning of a line is not treated specially,
+and does not introduce a comment.
+
+Any non-comment line can be continued by ending it with a backslash. Note that
+the general rule for whitespace means that trailing white space after the
+backslash is ignored, and leading white space at the start of continuation
+lines is also ignored. Comment lines beginning with # (but not empty lines) may
+appear in the middle of a sequence of continuation lines.
+
+A convenient way to create a configuration file is to start from the
+default, which is supplied in _src/configure.default_, and add, delete, or
+change settings as required.
+
+The ACLs, retry rules, and rewriting rules have their own syntax which is
+described in chapters <<CHAPACL>>, <<CHAPretry>>, and <<CHAPrewrite>>,
+respectively. The other parts of the configuration file have some syntactic
+items in common, and these are described below, from section <<SECTcos>>
+onwards. Before that, the inclusion, macro, and conditional facilities are
+described.
+
+
+
+File inclusions in the configuration file
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+cindex:[inclusions in configuration file]
+cindex:[configuration file,including other files]
+cindex:[.include in configuration file]
+cindex:[.include_if_exists in configuration file]
+You can include other files inside Exim's run time configuration file by
+using this syntax:
+
+  .include <file name>
+
+or
+
+  .include_if_exists <file name>
+
+on a line by itself. Double quotes round the file name are optional. If you use
+the first form, a configuration error occurs if the file does not exist; the
+second form does nothing for non-existent files.
+
+Includes may be nested to any depth, but remember that Exim reads its
+configuration file often, so it is a good idea to keep them to a minimum.
+If you change the contents of an included file, you must HUP the daemon,
+because an included file is read only when the configuration itself is read.
+
+The processing of inclusions happens early, at a physical line level, so, like
+comment lines, an inclusion can be used in the middle of an option setting,
+for example:
+
+....
+hosts_lookup = a.b.c \
+               .include /some/file
+....
+
+Include processing happens after macro processing (see below). Its effect is to
+process the lines of the file as if they occurred inline where the inclusion
+appears.
+
+
+
+[[SECTmacrodefs]]
+Macros in the configuration file
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+cindex:[macro,description of]
+cindex:[configuration file,macros]
+If a line in the main part of the configuration (that is, before the first
+``begin'' line) begins with an upper case letter, it is taken as a macro
+definition, and must be of the form
+
+&&&
+<'name'> = <'rest of line'>
+&&&
+
+The name must consist of letters, digits, and underscores, and need not all be
+in upper case, though that is recommended. The rest of the line, including any
+continuations, is the replacement text, and has leading and trailing white
+space removed. Quotes are not removed. The replacement text can never end with
+a backslash character, but this doesn't seem to be a serious limitation.
+
+Once a macro is defined, all subsequent lines in the file (and any included
+files) are scanned for the macro name; if there are several macros, the line is
+scanned for each in turn, in the order in which they are defined. The
+replacement text is not re-scanned for the current macro, though it is scanned
+for subsequently defined macros. For this reason, a macro name may not contain
+the name of a previously defined macro as a substring. You could, for example,
+define
+
+&&&
+`ABCD_XYZ = `<'something'>
+`ABCD = `<'something else'>
+&&&
+
+but putting the definitions in the opposite order would provoke a configuration
+error.
+
+Macro expansion is applied to individual lines from the file, before checking
+for line continuation or file inclusion (see below). If a line consists solely
+of a macro name, and the expansion of the macro is empty, the line is ignored.
+A macro at the start of a line may turn the line into a comment line or a
+`.include` line.
+
+As an example of macro usage, consider a configuration where aliases are looked
+up in a MySQL database. It helps to keep the file less cluttered if long
+strings such as SQL statements are defined separately as macros, for example:
+
+....
+ALIAS_QUERY = select mailbox from user where \
+              login=${quote_mysql:$local_part};
+....
+
+This can then be used in a ^redirect^ router setting like this:
+
+  data = ${lookup mysql{ALIAS_QUERY}}
+
+In earlier versions of Exim macros were sometimes used for domain, host, or
+address lists. In Exim 4 these are handled better by named lists -- see section
+<<SECTnamedlists>>.
+
+Macros in the configuration file can be overridden by the %-D% command line
+option, but Exim gives up its root privilege when %-D% is used, unless called
+by root or the Exim user.
+
+
+
+Conditional skips in the configuration file
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+cindex:[configuration file,conditional skips]
+cindex:[.ifdef]
+You can use the directives `.ifdef`, `.ifndef`, `.elifdef`,
+`.elifndef`, `.else`, and `.endif` to dynamically include or exclude
+portions of the configuration file. The processing happens whenever the file is
+read (that is, when an Exim binary starts to run).
+
+The implementation is very simple. Instances of the first four directives must
+be followed by text that includes the names of one or macros. The condition
+that is tested is whether or not any macro substitution has taken place in the
+line. Thus:
+
+  .ifdef AAA
+  message_size_limit = 50M
+  .else
+  message_size_limit = 100M
+  .endif
+
+sets a message size limit of 50M if the macro `AAA` is defined, and 100M
+otherwise. If there is more than one macro named on the line, the condition
+is true if any of them are defined. That is, it is an ``or'' condition. To
+obtain an ``and'' condition, you need to use nested `.ifdef`##s.
+
+Although you can use a macro expansion to generate one of these directives,
+it is not very useful, because the condition ``there was a macro substitution
+in this line'' will always be true.
+
+Text following `.else` and `.endif` is ignored, and can be used as comment
+to clarify complicated nestings.
+
+
+
+[[SECTcos]]
+Common option syntax
+~~~~~~~~~~~~~~~~~~~~
+cindex:[common option syntax]
+cindex:[syntax of common options]
+cindex:[configuration file,common option syntax]
+For the main set of options, driver options, and 'local_scan()' options,
+each setting is on a line by itself, and starts with a name consisting of
+lower-case letters and underscores. Many options require a data value, and in
+these cases the name must be followed by an equals sign (with optional white
+space) and then the value. For example:
+
+  qualify_domain = mydomain.example.com
+
+Some option settings may contain sensitive data, for example, passwords for
+accessing databases. To stop non-admin users from using the %-bP% command line
+option to read these values, you can precede the option settings with the word
+``hide''. For example:
+
+  hide mysql_servers = localhost/users/admin/secret-password
+
+For non-admin users, such options are displayed like this:
+
+  mysql_servers = <value not displayable>
+
+If ``hide'' is used on a driver option, it hides the value of that option on all
+instances of the same driver.
+
+The following sections describe the syntax used for the different data types
+that are found in option settings.
+
+
+Boolean options
+~~~~~~~~~~~~~~~
+cindex:[format,boolean]
+cindex:[boolean configuration values]
+Options whose type is given as boolean are on/off switches. There are two
+different ways of specifying such options: with and without a data value. If
+the option name is specified on its own without data, the switch is turned on;
+if it is preceded by ``no_'' or ``not_'' the switch is turned off. However,
+boolean options may optionally be followed by an equals sign and one of the
+words ``true'', ``false'', ``yes'', or ``no'', as an alternative syntax. For example,
+the following two settings have exactly the same effect:
+
+  queue_only
+  queue_only = true
+
+The following two lines also have the same (opposite) effect:
+
+  no_queue_only
+  queue_only = false
+
+You can use whichever syntax you prefer.
+
+
+
+
+Integer values
+~~~~~~~~~~~~~~
+cindex:[integer configuration values]
+cindex:[format,integer]
+If an integer data item starts with the characters ``0x'', the remainder of it
+is interpreted as a hexadecimal number. Otherwise, it is treated as octal if it
+starts with the digit 0, and decimal if not. If an integer value is followed by
+the letter K, it is multiplied by 1024; if it is followed by the letter M, it
+is multiplied by 1024x1024.
+
+When the values of integer option settings are output, values which are an
+exact multiple of 1024 or 1024x1024 are
+sometimes, but not always,
+printed using the letters K and M. The printing style is independent of the
+actual input format that was used.
+
+
+Octal integer values
+~~~~~~~~~~~~~~~~~~~~
+cindex:[integer format]
+cindex:[format,octal integer]
+The value of an option specified as an octal integer is always interpreted in
+octal, whether or not it starts with the digit zero. Such options are always
+output in octal.
+
+
+
+Fixed point number values
+~~~~~~~~~~~~~~~~~~~~~~~~~
+cindex:[fixed point configuration values]
+cindex:[format,fixed point]
+A fixed point number consists of a decimal integer, optionally followed by a
+decimal point and up to three further digits.
+
+
+
+[[SECTtimeformat]]
+Time interval values
+~~~~~~~~~~~~~~~~~~~~
+cindex:[time interval,specifying in configuration]
+cindex:[format,time interval]
+A time interval is specified as a sequence of numbers, each followed by one of
+the following letters, with no intervening white space:
+
+[frame="none"]
+`-`-----`--------
+  %s%   seconds
+  %m%   minutes
+  %h%   hours
+  %d%   days
+  %w%   weeks
+-----------------
+
+For example, ``3h50m'' specifies 3 hours and 50 minutes. The values of time
+intervals are output in the same format. Exim does not restrict the values; it
+is perfectly acceptable, for example, to specify ``90m'' instead of ``1h30m''.
+
+
+
+[[SECTstrings]]
+String values
+~~~~~~~~~~~~~
+cindex:[string,format of configuration values]
+cindex:[format,string]
+If a string data item does not start with a double-quote character, it is taken
+as consisting of the remainder of the line plus any continuation lines,
+starting at the first character after any leading white space, with trailing
+white space characters removed, and with no interpretation of the characters in
+the string. Because Exim removes comment lines (those beginning with #) at an
+early stage, they can appear in the middle of a multi-line string. The
+following settings are therefore equivalent:
+
+....
+trusted_users = uucp:mail
+
+trusted_users = uucp:\
+                # This comment line is ignored
+                mail
+....
+
+cindex:[string,quoted]
+cindex:[escape characters in quoted strings]
+If a string does start with a double-quote, it must end with a closing
+double-quote, and any backslash characters other than those used for line
+continuation are interpreted as escape characters, as follows:
+
+[frame="none"]
+`-`----------------------`--------------------------------------------------
+  `\\`                   single backslash
+  `\n`                   newline
+  `\r`                   carriage return
+  `\t`                   tab
+  `\`<'octal digits'>    up to 3 octal digits specify one character
+  `\x`<'hex digits'>     up to 2 hexadecimal digits specify one character
+----------------------------------------------------------------------------
+
+If a backslash is followed by some other character, including a double-quote
+character, that character replaces the pair.
+
+Quoting is necessary only if you want to make use of the backslash escapes to
+insert special characters, or if you need to specify a value with leading or
+trailing spaces. These cases are rare, so quoting is almost never needed in
+current versions of Exim. In versions of Exim before 3.14, quoting was required
+in order to continue lines, so you may come across older configuration files
+and examples that apparently quote unnecessarily.
+
+
+Expanded strings
+~~~~~~~~~~~~~~~~
+cindex:[string expansion, definition of]
+cindex:[expansion,definition of]
+Some strings in the configuration file are subjected to 'string expansion',
+by which means various parts of the string may be changed according to the
+circumstances (see chapter <<CHAPexpand>>). The input syntax for such strings is
+as just described; in particular, the handling of backslashes in quoted strings
+is done as part of the input process, before expansion takes place. However,
+backslash is also an escape character for the expander, so any backslashes that
+are required for that reason must be doubled if they are within a quoted
+configuration string.
+
+
+User and group names
+~~~~~~~~~~~~~~~~~~~~
+cindex:[user name,format of]
+cindex:[format,user name]
+cindex:[group,name format]
+cindex:[format,group name]
+User and group names are specified as strings, using the syntax described
+above, but the strings are interpreted specially. A user or group name must
+either consist entirely of digits, or be a name that can be looked up using the
+'getpwnam()' or 'getgrnam()' function, as appropriate.
+
+
+[[SECTlistconstruct]]
+List construction
+~~~~~~~~~~~~~~~~~
+cindex:[list,syntax of in configuration]
+cindex:[format,list item in configuration]
+cindex:[string list, definition]
+The data for some configuration options is a list of items, with colon as the
+default separator. Many of these options are shown with type ``string list'' in
+the descriptions later in this document. Others are listed as ``domain list'',
+``host list'', ``address list'', or ``local part list''. Syntactically, they are all
+the same; however, those other than ``string list'' are subject to particular
+kinds of interpretation, as described in chapter <<CHAPdomhosaddlists>>.
+
+In all these cases, the entire list is treated as a single string as far as the
+input syntax is concerned. The %trusted_users% setting in section
+<<SECTstrings>> above is an example. If a colon is actually needed in an item in
+a list, it must be entered as two colons. Leading and trailing white space on
+each item in a list is ignored. This makes it possible to include items that
+start with a colon, and in particular, certain forms of IPv6 address. For
+example, the list
+
+  local_interfaces = 127.0.0.1 : ::::1
+
++contains two IP addresses, the IPv4 address 127.0.0.1 and the IPv6 address
+1.
+
+cindex:[list separator, changing]
+cindex:[IPv6,addresses in lists]
+Doubling colons in IPv6 addresses is an unwelcome chore, so a mechanism was
+introduced to allow the separator character to be changed. If a list begins
+with a left angle bracket, followed by any punctuation character, that
+character is used instead of colon as the list separator. For example, the list
+above can be rewritten to use a semicolon separator like this:
+
+  local_interfaces = <; 127.0.0.1 ; ::1
+
+This facility applies to all lists, with the exception of the list in
+%log_file_path%. It is recommended that the use of non-colon separators be
+confined to circumstances where they really are needed.
+
+
+
+[[SECTempitelis]]
+Empty items in lists
+~~~~~~~~~~~~~~~~~~~~
+cindex:[list,empty item in]
+An empty item at the end of a list is always ignored. In other words, trailing
+separator characters are ignored. Thus, the list in
+
+  senders = user@domain :
+
+contains only a single item. If you want to include an empty string as one item
+in a list, it must not be the last item. For example, this list contains three
+items, the second of which is empty:
+
+  senders = user1@domain : : user2@domain
+
+*Note*: there must be whitespace between the two colons, as otherwise they
+are interpreted as representing a single colon data character (and the list
+would then contain just one item). If you want to specify a list that contains
+just one, empty item, you can do it as in this example:
+
+  senders = :
+
+In this case, the first item is empty, and the second is discarded because it
+is at the end of the list.
+
+
+
+
+[[SECTfordricon]]
+Format of driver configurations
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+cindex:[drivers,configuration format]
+There are separate parts in the configuration for defining routers, transports,
+and authenticators. In each part, you are defining a number of driver
+instances, each with its own set of options. Each driver instance is defined by
+a sequence of lines like this:
+
+&&&
+<'instance name'>:
+  <'option'>
+  ...
+  <'option'>
+&&&
+
+In the following example, the instance name is ^localuser^, and it is
+followed by three options settings:
+
+  localuser:
+    driver = accept
+    check_local_user
+    transport = local_delivery
+
+For each driver instance, you specify which Exim code module it uses -- by the
+setting of the %driver% option -- and (optionally) some configuration settings.
+For example, in the case of transports, if you want a transport to deliver with
+SMTP you would use the ^smtp^ driver; if you want to deliver to a local file
+you would use the ^appendfile^ driver. Each of the drivers is described in
+detail in its own separate chapter later in this manual.
+
+You can have several routers, transports, or authenticators that are based on
+the same underlying driver (each must have a different name).
+
+The order in which routers are defined is important, because addresses are
+passed to individual routers one by one, in order. The order in which
+transports are defined does not matter at all. The order in which
+authenticators are defined is used only when Exim, as a client, is searching
+them to find one that matches an authentication mechanism offered by the
+server.
+
+cindex:[generic options]
+cindex:[options, generic -- definition of]
+Within a driver instance definition, there are two kinds of option:
+'generic' and 'private'. The generic options are those that apply to all
+drivers of the same type (that is, all routers, all transports or all
+authenticators).
+The %driver% option is a generic option that must appear in every definition.
+
+cindex:[private options]
+The private options are special for each driver, and none need appear, because
+they all have default values.
+
+The options may appear in any order, except that the %driver% option must
+precede any private options, since these depend on the particular driver. For
+this reason, it is recommended that %driver% always be the first option.
+
+Driver instance names, which are used for reference in log entries and
+elsewhere, can be any sequence of letters, digits, and underscores (starting
+with a letter) and must be unique among drivers of the same type. A router and
+a transport (for example) can each have the same name, but no two router
+instances can have the same name. The name of a driver instance should not be
+confused with the name of the underlying driver module. For example, the
+configuration lines:
+
+  remote_smtp:
+    driver = smtp
+
+create an instance of the ^smtp^ transport driver whose name is
+^remote_smtp^. The same driver code can be used more than once, with
+different instance names and different option settings each time. A second
+instance of the ^smtp^ transport, with different options, might be defined
+thus:
+
+  special_smtp:
+    driver = smtp
+    port = 1234
+    command_timeout = 10s
+
+The names ^remote_smtp^ and ^special_smtp^ would be used to reference
+these transport instances from routers, and these names would appear in log
+lines.
+
+Comment lines may be present in the middle of driver specifications. The full
+list of option settings for any particular driver instance, including all the
+defaulted values, can be extracted by making use of the %-bP% command line
+option.
+
+
+
+
+
+
+////////////////////////////////////////////////////////////////////////////
+////////////////////////////////////////////////////////////////////////////
+
+[[CHAPdefconfil]]
+The default configuration file
+------------------------------
+cindex:[configuration file,default ``walk through'']
+cindex:[default,configuration file ``walk through'']
+The default configuration file supplied with Exim as _src/configure.default_
+is sufficient for a host with simple mail requirements. As an introduction to
+the way Exim is configured, this chapter ``walks through'' the default
+configuration, giving brief explanations of the settings. Detailed descriptions
+of the options are given in subsequent chapters. The default configuration file
+itself contains extensive comments about ways you might want to modify the
+initial settings. However, note that there are many options that are not
+mentioned at all in the default configuration.
+
+
+
+Main configuration settings
+~~~~~~~~~~~~~~~~~~~~~~~~~~~
+The main (global) configuration option settings must always come first in the
+file. The first thing you'll see in the file, after some initial comments, is
+the line
+
+  # primary_hostname =
+
+This is a commented-out setting of the %primary_hostname% option. Exim needs
+to know the official, fully qualified name of your host, and this is where you
+can specify it. However, in most cases you do not need to set this option. When
+it is unset, Exim uses the 'uname()' system function to obtain the host name.
+
+The first three non-comment configuration lines are as follows:
+
+  domainlist local_domains = @
+  domainlist relay_to_domains =
+  hostlist   relay_from_hosts = 127.0.0.1
+
+These are not, in fact, option settings. They are definitions of two named
+domain lists and one named host list. Exim allows you to give names to lists of
+domains, hosts, and email addresses, in order to make it easier to manage the
+configuration file (see section <<SECTnamedlists>>).
+
+The first line defines a domain list called 'local_domains'; this is used
+later in the configuration to identify domains that are to be delivered
+on the local host.
+
+cindex:[@ in a domain list]
+There is just one item in this list, the string ``@''. This is a special form of
+entry which means ``the name of the local host''. Thus, if the local host is
+called 'a.host.example', mail to 'any.user@a.host.example' is expected to
+be delivered locally. Because the local host's name is referenced indirectly,
+the same configuration file can be used on different hosts.
+
+The second line defines a domain list called 'relay_to_domains', but the
+list itself is empty. Later in the configuration we will come to the part that
+controls mail relaying through the local host; it allows relaying to any
+domains in this list. By default, therefore, no relaying on the basis of a mail
+domain is permitted.
+
+The third line defines a host list called 'relay_from_hosts'. This list is
+used later in the configuration to permit relaying from any host or IP address
+that matches the list. The default contains just the IP address of the IPv4
+loopback interface, which means that processes on the local host are able to
+submit mail for relaying by sending it over TCP/IP to that interface. No other
+hosts are permitted to submit messages for relaying.
+
+Just to be sure there's no misunderstanding: at this point in the configuration
+we aren't actually setting up any controls. We are just defining some domains
+and hosts that will be used in the controls that are specified later.
+
+The next configuration line is a genuine option setting:
+
+  acl_smtp_rcpt = acl_check_rcpt
+
+This option specifies an 'Access Control List' (ACL) which is to be used
+during an incoming SMTP session for every recipient of a message (every
+RCPT command). The name of the list is 'acl_check_rcpt', and we will
+come to its definition below, in the ACL section of the configuration. ACLs
+control which recipients are accepted for an incoming message -- if a
+configuration does not provide an ACL to check recipients, no SMTP mail can be
+accepted.
+
+Two commented-out options settings are next:
+
+  # qualify_domain =
+  # qualify_recipient =
+
+The first of these specifies a domain that Exim uses when it constructs a
+complete email address from a local login name. This is often needed when Exim
+receives a message from a local process. If you do not set %qualify_domain%,
+the value of %primary_hostname% is used. If you set both of these options, you
+can have different qualification domains for sender and recipient addresses. If
+you set only the first one, its value is used in both cases.
+
+cindex:[domain literal,recognizing format]
+The following line must be uncommented if you want Exim to recognize
+addresses of the form 'user@[10.11.12.13]' that is, with a ``domain literal''
+(an IP address) instead of a named domain.
+
+  # allow_domain_literals
+
+The RFCs still require this form, but many people think that in the modern
+Internet it makes little sense to permit mail to be sent to specific hosts by
+quoting their IP addresses. This ancient format has been used by people who
+try to abuse hosts by using them for unwanted relaying. However, some
+people believe there are circumstances (for example, messages addressed to
+'postmaster') where domain literals are still useful.
+
+The next configuration line is a kind of trigger guard:
+
+  never_users = root
+
+It specifies that no delivery must ever be run as the root user. The normal
+convention is to set up 'root' as an alias for the system administrator. This
+setting is a guard against slips in the configuration.
+The list of users specified by %never_users% is not, however, the complete
+list; the build-time configuration in _Local/Makefile_ has an option called
+FIXED_NEVER_USERS specifying a list that cannot be overridden. The
+contents of %never_users% are added to this list. By default
+FIXED_NEVER_USERS also specifies root.
+
+When a remote host connects to Exim in order to send mail, the only information
+Exim has about the host's identity is its IP address. The next configuration
+line,
+
+  host_lookup = *
+
+specifies that Exim should do a reverse DNS lookup on all incoming connections,
+in order to get a host name. This improves the quality of the logging
+information, but if you feel it is too expensive, you can remove it entirely,
+or restrict the lookup to hosts on ``nearby'' networks.
+Note that it is not always possible to find a host name from an IP address,
+because not all DNS reverse zones are maintained, and sometimes DNS servers are
+unreachable.
+
+The next two lines are concerned with 'ident' callbacks, as defined by RFC
+1413 (hence their names):
+
+  rfc1413_hosts = *
+  rfc1413_query_timeout = 30s
+
+These settings cause Exim to make ident callbacks for all incoming SMTP calls.
+You can limit the hosts to which these calls are made, or change the timeout
+that is used. If you set the timeout to zero, all ident calls are disabled.
+Although they are cheap and can provide useful information for tracing problem
+messages, some hosts and firewalls have problems with ident calls. This can
+result in a timeout instead of an immediate refused connection, leading to
+delays on starting up an incoming SMTP session.
+
+When Exim receives messages over SMTP connections, it expects all addresses to
+be fully qualified with a domain, as required by the SMTP definition. However,
+if you are running a server to which simple clients submit messages, you may
+find that they send unqualified addresses. The two commented-out options:
+
+  # sender_unqualified_hosts =
+  # recipient_unqualified_hosts =
+
+show how you can specify hosts that are permitted to send unqualified sender
+and recipient addresses, respectively.
+
+The %percent_hack_domains% option is also commented out:
+
+  # percent_hack_domains =
+
+It provides a list of domains for which the ``percent hack'' is to operate. This
+is an almost obsolete form of explicit email routing. If you do not know
+anything about it, you can safely ignore this topic.
+
+The last two settings in the main part of the default configuration are
+concerned with messages that have been ``frozen'' on Exim's queue. When a message
+is frozen, Exim no longer continues to try to deliver it. Freezing occurs when
+a bounce message encounters a permanent failure because the sender address of
+the original message that caused the bounce is invalid, so the bounce cannot be
+delivered. This is probably the most common case, but there are also other
+conditions that cause freezing, and frozen messages are not always bounce
+messages.
+
+  ignore_bounce_errors_after = 2d
+  timeout_frozen_after = 7d
+
+The first of these options specifies that failing bounce messages are to be
+discarded after 2 days on the queue. The second specifies that any frozen
+message (whether a bounce message or not) is to be timed out (and discarded)
+after a week. In this configuration, the first setting ensures that no failing
+bounce message ever lasts a week.
+
+
+
+ACL configuration
+~~~~~~~~~~~~~~~~~
+cindex:[default,ACLs]
+cindex:[{ACL},default configuration]
+In the default configuration, the ACL section follows the main configuration.
+It starts with the line
+
+  begin acl
+
+and it contains the definition of one ACL called 'acl_check_rcpt' that was
+referenced in the setting of %acl_smtp_rcpt% above.
+
+cindex:[RCPT,ACL for]
+This ACL is used for every RCPT command in an incoming SMTP message. Each
+RCPT command specifies one of the message's recipients. The ACL statements
+are considered in order, until the recipient address is either accepted or
+rejected. The RCPT command is then accepted or rejected, according to the
+result of the ACL processing.
+
+  acl_check_rcpt:
+
+This line, consisting of a name terminated by a colon, marks the start of the
+ACL, and names it.
+
+  accept  hosts = :
+
+This ACL statement accepts the recipient if the sending host matches the list.
+But what does that strange list mean? It doesn't actually contain any host
+names or IP addresses. The presence of the colon puts an empty item in the
+list; Exim matches this only if the incoming message didn't come from a remote
+host. The colon is important. Without it, the list itself is empty, and can
+never match anything.
+
+What this statement is doing is to accept unconditionally all recipients in
+messages that are submitted by SMTP from local processes using the standard
+input and output (that is, not using TCP/IP). A number of MUAs operate in this
+manner.
+
+  deny    domains       = +local_domains
+          local_parts   = ^[.] : ^.*[@%!/|]
+
+  deny    domains       = !+local_domains
+          local_parts   = ^[./|] : ^.*[@%!] : ^.*/\\.\\./
+
+These statements are concerned with local parts that contain any of the
+characters ``@'', ``%'', ``!'', ``/'', ``|'', or dots in unusual places. Although these
+characters are entirely legal in local parts (in the case of ``@'' and leading
+dots, only if correctly quoted), they do not commonly occur in Internet mail
+addresses.
+
+The first three have in the past been associated with explicitly routed
+addresses (percent is still sometimes used -- see the %percent_hack_domains%
+option). Addresses containing these characters are regularly tried by spammers
+in an attempt to bypass relaying restrictions, and also by open relay testing
+programs. Unless you really need them it is safest to reject these characters
+at this early stage. This configuration is heavy-handed in rejecting these
+characters for all messages it accepts from remote hosts. This is a deliberate
+policy of being as safe as possible.
+
+The first rule above is stricter, and is applied to messages that are addressed
+to one of the local domains handled by this host. This is implemented by the
+first condition, which restricts it to domains that are listed in the
+'local_domains' domain list. The ``+'' character is used to indicate a
+reference to a named list. In this configuration, there is just one domain in
+'local_domains', but in general there may be many.
+
+The second condition on the first statement uses two regular expressions to
+block local parts that begin with a dot or contain ``@'', ``%'', ``!'', ``/'', or ``|''.
+If you have local accounts that include these characters, you will have to
+modify this rule.
+
+Empty components (two dots in a row) are not valid in RFC 2822, but Exim
+allows them because they have been encountered in practice. (Consider local
+parts constructed as ``first-initial.second-initial.family-name'' when applied to
+someone like the author of Exim, who has no second initial.) However, a local
+part starting with a dot or containing ``/../'' can cause trouble if it is used
+as part of a file name (for example, for a mailing list). This is also true for
+local parts that contain slashes. A pipe symbol can also be troublesome if the
+local part is incorporated unthinkingly into a shell command line.
+
+The second rule above applies to all other domains, and is less strict. This
+allows your own users to send outgoing messages to sites that use slashes
+and vertical bars in their local parts. It blocks local parts that begin
+with a dot, slash, or vertical bar, but allows these characters within the
+local part. However, the sequence ``/../'' is barred. The use of ``@'', ``%'', and
+``!'' is blocked, as before. The motivation here is to prevent your users (or
+your users' viruses) from mounting certain kinds of attack on remote sites.
+
+  accept  local_parts   = postmaster
+          domains       = +local_domains
+
+This statement, which has two conditions, accepts an incoming address if the
+local part is 'postmaster' and the domain is one of those listed in the
+'local_domains' domain list. The ``+'' character is used to indicate a
+reference to a named list. In this configuration, there is just one domain in
+'local_domains', but in general there may be many.
+
+The presence of this statement means that mail to postmaster is never blocked
+by any of the subsequent tests. This can be helpful while sorting out problems
+in cases where the subsequent tests are incorrectly denying access.
+
+  require verify        = sender
+
+This statement requires the sender address to be verified before any subsequent
+ACL statement can be used. If verification fails, the incoming recipient
+address is refused. Verification consists of trying to route the address, to
+see if a
+bounce
+message could be delivered to it. In the case of remote addresses, basic
+verification checks only the domain, but 'callouts' can be used for more
+verification if required. Section <<SECTaddressverification>> discusses the
+details of address verification.
+
+....
+# deny    message       = rejected because $sender_host_address is \
+#                         in a black list at $dnslist_domain\n\
+#                         $dnslist_text
+#         dnslists      = black.list.example
+#
+# warn    message       = X-Warning: $sender_host_address is \
+#                         in a black list at $dnslist_domain
+#         log_message   = found in $dnslist_domain
+#         dnslists      = black.list.example
+....
+
+These commented-out lines are examples of how you could configure Exim to check
+sending hosts against a DNS black list. The first statement rejects messages
+from blacklisted hosts, whereas the second merely inserts a warning header
+line.
+
+  accept  domains       = +local_domains
+          endpass
+          message       = unknown user
+          verify        = recipient
+
+This statement accepts the incoming recipient address if its domain is one of
+the local domains, but only if the address can be verified. Verification of
+local addresses normally checks both the local part and the domain. The
+%endpass% line needs some explanation: if the condition above %endpass% fails,
+that is, if the address is not in a local domain, control is passed to the next
+ACL statement. However, if the condition below %endpass% fails, that is, if a
+recipient in a local domain cannot be verified, access is denied and the
+recipient is rejected.
+
+cindex:[customizing,ACL failure message]
+The %message% modifier provides a customized error message for the failure.
+
+  accept  domains       = +relay_to_domains
+          endpass
+          message       = unrouteable address
+          verify        = recipient
+
+This statement accepts the incoming recipient address if its domain is one of
+the domains for which this host is a relay, but again, only if the address can
+be verified.
+
+  accept  hosts         = +relay_from_hosts
+
+Control reaches this statement only if the recipient's domain is neither a
+local domain, nor a relay domain. The statement accepts the address if the
+message is coming from one of the hosts that are defined as being allowed to
+relay through this host. Recipient verification is omitted here, because in
+many cases the clients are dumb MUAs that do not cope well with SMTP error
+responses. If you are actually relaying out from MTAs, you should probably add
+recipient verification here.
+
+  accept  authenticated = *
+
+Control reaches here for attempts to relay to arbitrary domains from arbitrary
+hosts. The statement accepts the address only if the client host has
+authenticated itself. The default configuration does not define any
+authenticators, which means that no client can in fact authenticate. You will
+need to add authenticator definitions if you want to make use of this ACL
+statement.
+
+  deny    message       = relay not permitted
+
+The final statement denies access, giving a specific error message. Reaching
+the end of the ACL also causes access to be denied, but with the generic
+message ``administrative prohibition''.
+
+
+
+Router configuration
+~~~~~~~~~~~~~~~~~~~~
+cindex:[default,routers]
+cindex:[routers,default]
+The router configuration comes next in the default configuration, introduced
+by the line
+
+  begin routers
+
+Routers are the modules in Exim that make decisions about where to send
+messages. An address is passed to each router in turn, until it is either
+accepted, or failed. This means that the order in which you define the routers
+matters. Each router is fully described in its own chapter later in this
+manual. Here we give only brief overviews.
+
+  # domain_literal:
+  #   driver = ipliteral
+  #   domains = !+local_domains
+  #   transport = remote_smtp
+
+cindex:[domain literal,default router]
+This router is commented out because the majority of sites do not want to
+support domain literal addresses (those of the form 'user@[10.9.8.7]'). If
+you uncomment this router, you also need to uncomment the setting of
+%allow_domain_literals% in the main part of the configuration.
+
+  dnslookup:
+    driver = dnslookup
+    domains = ! +local_domains
+    transport = remote_smtp
+    ignore_target_hosts = 0.0.0.0 : 127.0.0.0/8
+    no_more
+
+The first uncommented router handles addresses that do not involve any local
+domains. This is specified by the line
+
+  domains = ! +local_domains
+
+The %domains% option lists the domains to which this router applies, but the
+exclamation mark is a negation sign, so the router is used only for domains
+that are not in the domain list called 'local_domains' (which was defined at
+the start of the configuration). The plus sign before 'local_domains'
+indicates that it is referring to a named list. Addresses in other domains are
+passed on to the following routers.
+
+The name of the router driver is ^dnslookup^,
+and is specified by the %driver% option. Do not be confused by the fact that
+the name of this router instance is the same as the name of the driver. The
+instance name is arbitrary, but the name set in the %driver% option must be one
+of the driver modules that is in the Exim binary.
+
+The ^dnslookup^ router routes addresses by looking up their domains in the
+DNS in order to obtain a list of hosts to which the address is routed. If the
+router succeeds, the address is queued for the ^remote_smtp^ transport, as
+specified by the %transport% option. If the router does not find the domain in
+the