summaryrefslogtreecommitdiff
path: root/doc
diff options
context:
space:
mode:
authorSergey Poznyakoff <gray@gnu.org>2015-09-20 14:21:54 +0300
committerSergey Poznyakoff <gray@gnu.org>2015-09-20 14:21:54 +0300
commitdcbf8f353e76d506ecf7ae6c48081783166a82ab (patch)
treeb4850f711af489b9cd563f837847b84712aca663 /doc
parentad3cc340266af4e1d768e6d3e59594f78cd6f940 (diff)
downloadmailutils-dcbf8f353e76d506ecf7ae6c48081783166a82ab.tar.gz
mailutils-dcbf8f353e76d506ecf7ae6c48081783166a82ab.tar.bz2
Document mailbox types, variable extension, etc.
Diffstat (limited to 'doc')
-rw-r--r--doc/texinfo/mailutils.texi401
-rw-r--r--doc/texinfo/programs.texi652
2 files changed, 739 insertions, 314 deletions
diff --git a/doc/texinfo/mailutils.texi b/doc/texinfo/mailutils.texi
index 98e0408f1..51c43bb09 100644
--- a/doc/texinfo/mailutils.texi
+++ b/doc/texinfo/mailutils.texi
@@ -29,19 +29,19 @@
@end direntry
@dircategory Individual utilities
@direntry
-* comsatd: (mailutils)comsatd. Comsat Daemon.
-* frm: (mailutils)frm. List Headers from a Mailbox.
-* guimb: (mailutils)guimb. Mailbox Processing Language.
-* imap4d: (mailutils)imap4d. IMAP4 Daemon.
-* mail: (mailutils)mail. Send and Receive Mail.
-* maidag: (mailutils)maidag. A General-Purpose Mail Delivery Agent.
-* messages: (mailutils)messages. Count Messages in a Mailbox.
-* movemail: (mailutils)movemail. Move Mail between Mailboxes.
-* pop3d: (mailutils)pop3d. POP3 Daemon.
-* readmsg: (mailutils)readmsg. Extract Messages from a Folder.
-* sieve: (mailutils)sieve. Mail Filtering Utility.
-* mimeview: (mailutils)mimeview. View MIME Messages.
-* mu: (mailutils)mu. Mailutils Multi-Purpose Tool
+* comsatd: (mailutils) comsatd. Comsat Daemon.
+* frm: (mailutils) frm. List Headers from a Mailbox.
+* guimb: (mailutils) guimb. Mailbox Processing Language.
+* imap4d: (mailutils) imap4d. IMAP4 Daemon.
+* mail: (mailutils) mail. Send and Receive Mail.
+* maidag: (mailutils) maidag. A General-Purpose Mail Delivery Agent.
+* messages: (mailutils) messages. Count Messages in a Mailbox.
+* movemail: (mailutils) movemail. Move Mail between Mailboxes.
+* pop3d: (mailutils) pop3d. POP3 Daemon.
+* readmsg: (mailutils) readmsg. Extract Messages from a Folder.
+* sieve: (mailutils) sieve. Mail Filtering Utility.
+* mimeview: (mailutils) mimeview. View MIME Messages.
+* mailutils: (mailutils) mailutils. Mailutils Multi-Purpose Tool
@end direntry
@end ifinfo
@@ -87,6 +87,7 @@ This edition of the @cite{GNU Mailutils Manual}, last updated on
@menu
* Introduction:: Preliminary Information.
+* Mailbox:: Mailboxes and URLs.
* Programs:: Mailutils Programs.
* Libraries:: Mailutils Libraries.
* Sieve Language:: The Sieve Language.
@@ -143,7 +144,7 @@ Mailutils Programs
* mh:: The MH Message Handling System.
-* mu:: Mailutils Multi-Purpose Tool.
+* mailutils:: The Mailutils Multi-Purpose Tool.
Command Line
@@ -329,22 +330,24 @@ Major differences between Mailutils MH and other MH implementations
MU
-* mu invocation syntax::
-* mu help::
-* mu info::
-* mu cflags::
-* mu ldflags::
-* mu query::
-* mu 2047::
-* mu filter::
-* mu acl::
-* mu wicket::
-* mu dbm::
-* mu logger::
-* mu pop::
-* mu imap::
-
-mu dbm
+* mailutils invocation syntax::
+* mailutils help::
+* mailutils info::
+* mailutils cflags::
+* mailutils ldflags::
+* mailutils query::
+* mailutils 2047::
+* mailutils filter::
+* mailutils acl::
+* mailutils wicket::
+* mailutils dbm::
+* mailutils logger::
+* mailutils pop::
+* mailutils imap::
+* mailutils send::
+* mailutils smtp::
+
+mailutils dbm
* Create a Database::
* Add Records to a Database::
@@ -530,6 +533,344 @@ if a new format is added at a later date, your program will support
that new format automatically as soon as it is compiled against the
new library.
+@node Mailbox
+@chapter Mailbox
+@cindex mailbox URL
+@cindex URL, mailbox
+
+The principal object Mailutils operates on is @dfn{mailbox} --
+a collection of mail messages. The two main characteristics of a
+mailbox are its type and path. The @dfn{type} defines how the
+messages are stored within a mailbox. The @dfn{path} specifies
+the location of the mailbox. The two characteristics are usually
+combined within a @dfn{Uniform Resource Locator} (@acronym{URL}),
+which uniquely identifies the mailbox. The syntax for @acronym{URL}
+is:
+
+@example
+@var{type}:[//[@var{user}:@var{password}@@]@var{host}[:@var{port}]]@var{path}[?@var{query}][;@var{params}]
+@end example
+
+The square brackets do not appear in a @acronym{URL}, instead they are
+used to denote optional parts.
+
+Not all parts are meaningful for all types. Their usage and purpose
+are described in the sections that follow.
+
+@menu
+* Local Mailboxes:: Mailboxes stored on the local file system.
+* Remote Mailboxes:: Mailboxes stored on remote hosts.
+* SMTP Mailboxes:: Mailboxes that send mail.
+* Program Mailboxes::
+@end menu
+
+@node Local Mailboxes
+@section Local Mailboxes
+@cindex local mailbox
+@cindex mailbox, local
+@cindex URL, local
+
+@dfn{Local mailboxes} store mail in files on the local file system. A
+local mailbox URL is:
+
+@example
+@var{type}://@var{path}[;@var{params}]
+@end example
+
+The @var{path} defines its location in the file system. For example:
+
+@example
+mbox:///var/spool/mail/gray
+@end example
+
+Optional @var{params} is a semicolon-separated list of optional
+arguments that configures indexed directory structure. @xref{local
+URL parameters}, for a detailed description.
+
+The local mailbox types are:
+
+@table @asis
+@anchor{mbox}
+@cindex mbox
+@item mbox
+A traditional UNIX mailbox format. Messages are stored sequentially
+in a single file. Each message begins with a @samp{From} line,
+identifying its sender and date when it was received. A single empty
+line separates two adjacent messages.
+
+This is the default format.
+
+@cindex maildir
+@item maildir
+The @dfn{Maildir} mailbox format. Each message is kept in a separate
+file with a unique name. Each mailbox is therefore a directory. This
+mailbox format eliminates file locking and makes message access much
+faster.
+
+@cindex Bernstein, D. J.
+This format was originally described by D.@: J.@: Bernstein in
+@url{http://cr.yp.to/proto/maildir.html}.
+
+@cindex mh
+@item mh
+MH Message Handling System format. Each message is kept in a separate
+file named after its sequential numeric identifier within the mailbox.
+Deleted messages are not removed, but instead the corresponding file
+is renamed by prepending a comma to its original name. Each mailbox
+is a directory. Mailboxes can be nested.
+
+@cindex RAND Corporation
+This format was originally developed by RAND Corporation. Mailutils
+implementation is compatible both with the original implementation and
+with its descendant @dfn{nmh}.
+
+@cindex file, mailbox type
+@item file
+This type can be used when accessing an existing mailbox of any of the
+formats defined above. The actual mailbox format is determined
+automatically. This type is assumed when a mailbox is referred to by
+its full pathname.
+@end table
+
+@node Remote Mailboxes
+@section Remote Mailboxes
+@cindex remote mailbox
+@cindex mailbox, remote
+@cindex URL, remote
+
+@dfn{Remote mailboxes} are accessed via one of the remote message
+protocols.
+
+The basic remote mailbox types are:
+
+@table @asis
+@cindex pop, mailbox
+@item pop
+Remote mailbox accessed using the @dfn{Post Office Protocol}
+(@acronym{POP3}). Default port number 110.
+
+The URL is:
+
+@example
+pop://[@var{user}[:@var{pass}][;auth=+APOP]@@]@var{host}[:@var{port}][;notls]
+@end example
+
+The @var{host} gives the name or IP address of the host running a POP3
+server. Optional @var{port} can be used to connect to a port other than
+the default 110.
+
+The @var{user} and @var{pass} supply authentication credentials. If any
+of them is missing, Mailtils will first try to obtain it from the ticket
+file. If that fails, the behavior depends on the type of the controlling
+terminal. If the terminal is a tty device (i.e. the program accessing
+the mailbox was started from the command line), it will ask the user
+to supply the missing credentials. Otherwise it will issue an
+appropriate error message and refuse to access the mailbox.
+
+By default, the usual POP3 authentication is used. The @samp{auth=+APOP}
+authentication parameter instructs Mailutils to use APOP authentication
+instead.
+
+If the server offers the STLS capability, Mailutils will attempt to
+establish encrypted TLS connection. The @samp{notls} parameter
+disables this behavior.
+
+@cindex pops, mailbox
+@item pops
+Remote mailbox accessed using the @dfn{Post Office Protocol}
+(@acronym{POP3}). The transmission channel is encrypted using the
+@dfn{transport layer security} (@acronym{TLS}). The default port is 995.
+
+The URL is:
+
+@example
+pops://[@var{user}[:@var{pass}][;auth=+APOP]@@]@var{host}[:@var{port}]
+@end example
+
+The meaning of its components is the same as for @samp{pop} type.
+
+@cindex imap, mailbox
+@item imap
+Remote mailbox accessed via the @dfn{Internet Message Access
+Protocol}. Default port number is 143.
+
+The URL is:
+
+@example
+imap://[@var{user}[:@var{pass}]@var{host}[:@var{port}][;notls]
+@end example
+
+The @var{host} gives the name or IP address of the host running a IMAP4
+server. Optional @var{port} can be used to connect to a port other than
+the default 143.
+
+The @var{user} and @var{pass} supply authentication credentials. If any
+of them is missing, Mailtils will first try to obtain it from the ticket
+file. If that fails, the behavior depends on the type of the controlling
+terminal. If the terminal is a tty device (i.e. the program accessing
+the mailbox was started from the command line), it will ask the user
+to supply the missing credentials. Otherwise it will issue an
+appropriate error message and refuse to access the mailbox.
+
+If the server offers the STARTTLS capability, Mailutils will attempt to
+establish encrypted TLS connection. The @samp{notls} parameter
+disables this behavior.
+
+@cindex imaps, mailbox
+@item imaps
+
+The @samp{imaps} type differs in that its transmission channel is
+encrypted using the @dfn{transport layer security} (@acronym{TLS}).
+The default port is 993.
+
+The URL is:
+
+@example
+imaps://[@var{user}[:@var{pass}]@@]@var{host}[:@var{port}]
+@end example
+
+The meaning of its components is the same as for @samp{imap} type.
+@end table
+
+@node SMTP Mailboxes
+@section SMTP Mailboxes
+@cindex mailbox, SMTP
+@cindex URL, SMTP
+
+SMTP mailboxes types are special remote mailboxes that allow only
+append operation. Appending a message is equivalent to sending it to
+the given recipient or recipients.
+
+@table @asis
+@cindex smtp, mailbox
+@item smtp
+A remote mailbox accessed using the Simple Message Transfer Protocol.
+
+The SMTP URL syntax is:
+
+@example
+smtp://[@var{user}[:@var{pass}][;auth=@var{mech},...]@@]@var{host}[:@var{port}][;@var{params}]
+@end example
+
+The @var{host} gives the name or IP address of the host running SMTP
+server. Optional @var{port} can be used to connect to a port other than
+the default 25.
+
+The @var{user}, @var{pass}, and @samp{auth=} elements supply
+credentials for ESMTP authentication, if the server supports it.
+
+If the ESMTP authentication is used, Mailutils will select the best
+authentication mechanism from the list offered by the server. To force
+it to use a particular authentication mechanism, use the @samp{auth}
+authentication parameter. Its value is a comma-separated list of
+authentication mechanisms, in the order from the most to the least
+preferred one, e.g.:
+
+@example
+smtp://smith:guessme;auth=cram-md5,digest-md5@@localhost
+@end example
+
+Optional @var{params} is a semicolon-separated list of additional
+parameters. Valid parameters are:
+
+@table @asis
+@kwindex domain
+@item domain=@var{string}
+Append @samp{@@@var{string}} to those recipient addresses that lack
+the domain part.
+
+@kwindex from
+@item from=@var{addr}
+Use @var{addr} as sender address.
+
+@kwindex noauth
+@item noauth
+Disable ESMTP authentication.
+
+@kwindex notls
+@item notls
+Disable TLS.
+
+@item recipient-headers[=@var{name}[,@var{name}...]]
+Use the supplied header names to determine recipient addresses.
+When no values are supplied, disables header scanning.
+
+@kwindex strip-domain
+@item strip-domain
+Strip domain part from all recipient addresses.
+
+@kwindex to
+@item to=@var{addr}[,@var{addr}...]
+Deliver messages to the supplied email addresses.
+@end table
+
+@cindex smtps, mailbox
+@item smtps
+A remote mailbox accessed using the Simple Message Transfer Protocol, with
+the transmission channel encrypted using the @dfn{transport layer
+security} (@acronym{TLS}). The default port is 465.
+
+The URL is
+
+@example
+smtps://[@var{user}[:@var{pass}][;auth=@var{mech},...]@@]@var{host}[:@var{port}][;@var{params}]
+@end example
+
+See the @samp{smtp} type for a detailed description of its types.
+The only difference from @samp{smtp} is that the @samp{notls}
+parameter is not used.
+@end table
+
+@node Program Mailboxes
+@section Program Mailboxes
+@cindex mailbox, program
+@cindex program mailbox
+
+Program mailboxes support only append operation. Appending a message
+is performed by invoking the specified program and passing the message
+to its standard input stream.
+
+@cindex URL, sendmail
+@cindex sendmail, URL
+A @samp{sendmail} mailbox is identified by the following URL:
+
+@example
+sendmail[://@var{path}]
+@end example
+
+The messages are sent by invoking @command{sendmail} binary with the
+@option{-oi -t} options. If the message being appended has the
+@samp{From:} header, its value is passed to @command{sendmail} using
+the @option{-f} option.
+
+The default path to the sendmail binary is system-dependent. The
+@var{path} part can be used to specify it explicitly.
+
+@cindex URL, prog
+@cindex prog, URL
+The @samp{prog} mailbox URL is:
+
+@example
+prog://@var{pathname}[?@var{query}]
+@end example
+
+Messages are appended by invoking the program @var{pathname} with the
+arguments supplied by @var{query}. The latter is a list of words
+delimited by @samp{&} characters.
+
+Arguments can contain the following variables (@pxref{Variables}):
+
+@table @asis
+@kwindex sender
+@item sender
+Expands to the sender email address.
+
+@kwindex rcpt
+@item rcpt
+Expands to comma-separated list of email addresses obtained from
+@samp{To:}, @samp{Cc:} and @samp{Bcc:} headers of the message.
+@end table
+
@node Programs
@chapter Mailutils Programs
@cindex Programs
diff --git a/doc/texinfo/programs.texi b/doc/texinfo/programs.texi
index ee90ef0b4..54abfd936 100644
--- a/doc/texinfo/programs.texi
+++ b/doc/texinfo/programs.texi
@@ -42,7 +42,7 @@ syntax.
* mh:: The MH Message Handling System.
-* mu:: Mailutils Multi-Purpose Tool.
+* mailutils:: The Mailutils Multi-Purpose Tool.
@end menu
@node command line
@@ -226,7 +226,7 @@ Do not load site-wide configuration file.
Do not load user configuration file.
@xopindex{set, introduced}
-@item --set=@var{path}
+@item --set=@var{path}=@var{value}
Set configuration variable.
@end table
@@ -247,7 +247,7 @@ for the system configuration directory set when compiling the package.
You can obtain the value of @var{sysconfdir} by running
@example
-$ mailutils-config --info sysconfdir
+$ mailutils info sysconfdir
@end example
@noindent
@@ -281,7 +281,7 @@ command line option was given.
@end enumerate
The order in which configuration files are loaded defines the
-precedence of their settings. Thus, the settings from additional
+precedence of their settings. Thus, settings from additional
configuration file override those set in per-user configuration file.
The latter, in their turn, take precedence over the settings from the
site-wide configuration file.
@@ -345,9 +345,10 @@ and to edit the @file{imap4d.rc} file with your editor of choice.
@xopindex{set, described}
It is also possible to set or override arbitrary configuration
variables in the command line. It can be done via the @option{--set}
-option. Its argument is a @dfn{pathname} of the variable to be set.
-For example, to define the variable @samp{syslog} in section
-@samp{logging} to @samp{no}, do the following:
+option. Its argument is a @dfn{pathname} of the variable to be set,
+followed by an equals sign and value. For example, to define the
+variable @samp{syslog} in section @samp{logging} to @samp{no}, do the
+following:
@example
$ imap4d --set .logging.syslog=no
@@ -357,6 +358,7 @@ Configuration pathnames are discussed in detail in @ref{Paths}.
@menu
* conf-syntax:: Configuration File Syntax
+* Variables:: Variable Expansion
* Include:: Include Statement
* Logging Statement::
* Debug Statement::
@@ -674,6 +676,52 @@ component separator, e.g.:
.program="a.out".bar.baz
@end example
+@node Variables
+@subsection Configuration Variables
+@cindex variable expansion
+@cindex macro variable
+ Certain configuration statements allow for the use of variable
+references in their values. A variable reference has the form
+@samp{$@var{variable}} or @samp{$@{@var{variable}@}}, where
+@var{variable} is the variable name. It is expanded to the actual
+value of @var{variable} when Mailutils consults the configuration
+statement in question.
+
+The two forms are entirely equivalent. The form with curly braces is
+normally used if the variable name is immediately followed by an
+alphanumeric symbol, which will otherwise be considered part of it.
+This form also allows for specifying the action to take if the
+variable is undefined or expands to an empty value.
+
+During variable expansion, the forms below cause Mailutils to test
+for a variable that is unset or null. Omitting the colon results
+in a test only for a variable that is unset.
+
+@table @asis
+@item $@{@var{variable}:-@var{word}@}
+@dfn{Use Default Values}. If @var{variable} is unset or null, the expansion
+of @var{word} is substituted. Otherwise, the value of @var{variable} is
+substituted.
+
+@item $@{@var{variable}:=@var{word}@}
+@dfn{Assign Default Values}. If @var{variable} is unset or null, the
+expansion of @var{word} is assigned to variable. The value of
+@var{variable} is then substituted.
+
+@item $@{@var{variable}:?@var{word}@}
+@dfn{Display Error if Null or Unset}. If @var{variable} is null or unset,
+the expansion of @var{word} (or a message to that effect if @var{word} is
+not present) is output to the current logging channel. Otherwise, the
+value of @var{variable} is substituted.
+
+@item $@{@var{variable}:+@var{word}@}
+@dfn{Use Alternate Value}. If @var{variable} is null or unset, nothing is
+substituted, otherwise the expansion of @var{word} is substituted.
+@end table
+
+The subsections below define variable names that are valid for use in
+each configuration statement.
+
@node Include
@subsection Include Statement
@cindex include statement, configuration file
@@ -710,13 +758,20 @@ file. Thus. @command{imap4d} will read
logging @{
# @r{Send diagnostics to syslog.}
syslog @var{boolean};
+
# @r{Print message severity levels.}
print-severity @var{boolean};
+
# @r{Output only messages with a severity equal to or}
# @r{greater than this one.}
severity @var{string};
+
# @r{Set syslog facility.}
facility @var{name};
+
+ # Log session ID
+ session-id @var{boolean};
+
# @r{Tag syslog messages with this string.}
tag @var{text};
@}
@@ -732,10 +787,10 @@ syslog. Otherwise, it goes to the standard error.
@end deffn
The default syslog facility is determined at compile time, it can be inspected
-using the following command (@pxref{mu info}):
+using the following command (@pxref{mailutils info}):
@example
-$ mu info log_facility
+$ mailutils info log_facility
@end example
@anchor{syslog facility}
@@ -761,6 +816,12 @@ one. Valid arguments are: @samp{debug}, @samp{info}, @samp{notice},
@samp{warning}, @samp{error}, @samp{crit}, @samp{alert}, @samp{emerg},
@end deffn
+@deffn {Configuration} session-id bool
+Print session ID with each diagnostic message. This is useful for
+programs that handle multiple user sessions simultaneously, such as
+@command{pop3d} and @command{imap4d}.
+@end deffn
+
@node Debug Statement
@subsection Debug Statement
@kwindex debug
@@ -769,18 +830,21 @@ one. Valid arguments are: @samp{debug}, @samp{info}, @samp{notice},
debug @{
# @r{Set Mailutils debugging level.}
level @var{spec};
+
# @r{Prefix debug messages with Mailutils source locations.}
line-info @var{bool};
@}
@end example
@subheading Description
+@kwindex level
The @samp{debug} statement controls the amount of additional debugging
information output by Mailutils programs. The @samp{level} statement
enables additional debugging information. Its argument (@var{spec})
is a Mailutils debugging specification as described in
@ref{debugging}.
+@kwindex line-info
The @samp{line-info} statement, when set to @samp{true} causes
debugging messages to be prefixed with locations in Mailutils source
files where they appear. Normally, only Mailutils developers need
@@ -794,10 +858,13 @@ this option.
mailbox @{
# @r{Use specified @var{url} as a mailspool.}
mail-spool @var{url};
+
# @r{Create mailbox @var{url} using @var{pattern}.}
mailbox-pattern @var{pattern};
+
# @r{Default mailbox type.}
mailbox-type @var{type};
+
# @r{Default user mail folder.}
folder @var{dir};
@}
@@ -821,34 +888,18 @@ Historically, @var{path} can contain mailbox type prefix, e.g.:
favor of @code{mailbox-pattern} statement.
@end deffn
-@deffn {Configuration} mailbox-pattern @var{pattern}
-The @code{mailbox-pattern} statement is a modern way of configuring
+@deffn {Configuration} mailbox-pattern @var{url}
+The @code{mailbox-pattern} statement is a preferred way of configuring
mailbox locations. It supersedes @code{mail-spool} statement.
-The @var{pattern} is valid @dfn{mailbox URL}, which
-may contain references to @samp{user} macro-variable
-(@FIXME-pxref{macro-variables}). This macro-variable will be expanded
-to the actual user name. The full syntax for @var{pattern} is:
-
-@example
- [@var{type}://]@var{path}[;@var{args}]
-@end example
-
-@noindent
-where:
-
-@table @var
-@item type
-Specifies the mailbox type. It must be one of mailbox types,
-supported by Mailutils. @FIXME-xref{Mailbox URLs}. By default,
-@samp{local} is assumed. @FIXME{Verify this}.
-
-@item path
-The path pattern.
+The @var{url} is valid mailbox URL (@pxref{Mailbox}), which
+may contain references to the @samp{user} variable
+(@pxref{Variables}). This variable will be expanded to the actual
+user name.
-@item args
-A semicolon-separated list of optional arguments, configuring
-indexed directory structure.
+@anchor{local URL parameters}
+Optional URL parameters can be used to configure indexed directory
+structure.
@cindex directory indexing
An @dfn{indexed directory structure} is a special way of storing
@@ -930,8 +981,9 @@ Specifies indexing key. The only meaningful value, as of Mailutils
version @value{VERSION} is @samp{user=$@{user@}}.
@end table
-Let's assume the traditional mail layout, in which user incoming
-mails are stored in UNIX mailbox format in @file{/var/mail} directory.
+Let's assume the traditional mail layout, in which incoming
+mails are stored in a UNIX mailbox named after the recipient user name
+and located in @file{/var/mail} directory.
The @code{mailbox-pattern} for this case is:
@example
@@ -948,12 +1000,11 @@ Now, if the layout is the same, but mailboxes are kept in
@end example
Finally, if the mailboxes are stored in a directly-indexed directory with
-two levels of indexing, than:
+two levels of indexing, the URL is:
@example
mailbox-pattern "maildir:///var/mail;type=index;param=2;user=$@{user@}";
@end example
-@end table
@end deffn
If neither @code{mailbox-pattern} nor @code{mail-spool} are given, the
@@ -978,12 +1029,12 @@ time, using @samp{_PATH_MAILDIR} define from the include file
Specifies type of mailboxes. By default, @samp{mbox} (UNIX mailbox)
is assumed. This can be changed while configuring the package by
setting @code{MU_DEFAULT_SCHEME} configuration variable. The default
-value can be verified by running @command{mailutils-config --info scheme}.
+value can be verified by running @command{mailutils info scheme}.
@end deffn
@deffn {Configuration} folder @var{dir}
@cindex plus expansion
-Sets user mail folder directory. Its value is using when expanding
+Sets user mail folder directory. Its value is used when expanding
@samp{plus-notation}, i.e. such mailbox names as @file{+inbox}. The
@samp{+} sign is replaced by @var{dir}, followed by a directory
separator (@samp{/}).
@@ -1002,12 +1053,16 @@ The default folder name is @samp{Mail/}.
locking @{
# @r{Default locker flags.}
flags @var{arg};
+
# @r{Set timeout for acquiring the lock.}
retry-timeout @var{arg};
+
# @r{Set the maximum number of times to retry acquiring the lock.}
retry-count @var{number};
+
# @r{Expire locks older than this amount of time.}
expire-timeout @var{number};
+
# @r{Use @var{prog} as external locker program.}
external-locker @var{prog};
@}
@@ -1017,8 +1072,9 @@ locking @{
This block statement configures various parameters used when locking
UNIX mailboxes in order to prevent simultaneous writes.
-It is important to note, that locking applies only to maildrops in
-UNIX mailbox format. All other mailbox types do not require locking.
+It is important to note, that locking applies only to traditional
+UNIX mailboxes (@pxref{mbox}). All other
+mailbox types don't require locking.
@deffn {Configuration} flags @var{string}
Set locking flags. Argument is a string consisting of one or more of
@@ -1086,19 +1142,16 @@ The mailer statement contains a single sub-statement:
Set the mailer @acronym{URL}.
@end deffn
-GNU Mailutils supports two types of mailer @acronym{URL}s, described
-in the table below. As usual, square brackets indicate optional parts:
+GNU Mailutils supports three types of mailer @acronym{URL}s, described
+in the table below:
@table @asis
-@item smtp://@var{host}[:@var{port}]
-Use an SMTP server @var{host} to send messages. Optional @var{port}
-specifies port number or symbolic name (as defined in
-@file{/etc/services}). It defaults to 25. The @var{host} can be
-specified as either an IP address in dotted-quad notation or as a
-symbolic host name. In the latter case, DNS system will be used to
-resolve it.
-
-@item sendmail://@var{progname}
+@item smtp://[@var{user}[:@var{pass}][;auth=@var{mech},...]@@]@var{host}[:@var{port}][;@var{params}]
+@itemx smtps://[@var{user}[:@var{pass}][;auth=@var{mech},...]@@]@var{host}[:@var{port}][;@var{params}]
+Send messages using SMTP protocol. @xref{SMTP Mailboxes}, for a
+detailed description of the URL and its parts.
+
+@item sendmail[://@var{progname}]
Use sendmail-compatible program
@var{progname}. @dfn{Sendmail-compatible} means that the program must
support following command line options:
@@ -1114,30 +1167,13 @@ Use @var{addr} as the sender address.
Get recipient addresses from the message.
@end table
-@item sendmail:
-This is a special form of the @samp{sendmail} mailer. It uses the
-@command{sendmail} binary from the @code{_PATH_SENDMAIL} macro in your
-@file{/usr/include/paths.h}. It is the default mailer.
+@xref{Program Mailboxes,,sendmail}, for details.
@item prog://@var{progname}?@var{query}
A @dfn{prog} mailer. This is a generalization of @samp{sendmail}
mailer that allows to use arbitrary external programs as mailers.
-The @var{progname} must be a full pathname of the binary file. When
-sending message, Mailutils will invoke this file with the arguments
-specified by @var{query} and will pipe the message to be sent to its
-standard input.
-
-The @var{query} part is a list of arguments, separated by @samp{&}
-signs. Arguments may contain the following macro-substitutions:
-
-@table @samp
-@item $@{sender@}
-Expands to the sender email address.
-
-@item $@{rcpt@}
-Expands to the recipient email addresses.
-@end table
+It is described in detain in @ref{Program Mailboxes,,prog}.
@end table
@node ACL Statement
@@ -1148,13 +1184,17 @@ Expands to the recipient email addresses.
acl @{
# @r{Allow connections from this IP address.}
allow [from] @var{ip};
+
# @r{Deny connections from this IP address.}
deny [from] @var{ip};
+
# @r{Log connections from this IP address.}
log [from] @var{ip} [@var{string}];
+
/* @r{Execute supplied program if a connection from this
IP address is requested.} */
exec [from] @var{ip} @var{program};
+
/* Use @var{program} to decide whether to allow connection
from @var{ip}. */
ifexec [from] @var{ip} @var{program};
@@ -1175,10 +1215,10 @@ know}, then the next control is tried. It is unclear whether to allow
access if the last control in list returned @samp{Don't know}. GNU
Mailutils @value{VERSION} issues a warning message and allows access.
This default may change in future versions. Users are advised to
-write their ACLs so that the last control returns a definitive answer
+write their ACLs so that the last control returns a definite answer
(either @code{True} or @code{False}).
-In the discussion below, wherever @var{ip} appears as an argument, it
+In the discussion below, wherever @var{cidr} appears as an argument, it
can be replaced by any of:
@itemize @bullet
@@ -1205,6 +1245,34 @@ Deny connections from IP addresses matching this @var{cidr} block.
When a connection from the @var{cidr} block is requested, execute
the program @var{program}. If its exit code is @samp{0}, then allow
connection. Otherwise, deny it.
+
+The @var{program} argument undergoes variable expansion and word
+splitting. The following variables are defined:
+
+@table @code
+@item aclno
+Ordinal number of the control in the ACL. Numbers begin from
+@samp{1}.
+
+@item family
+Connection family. Mailutils version @value{VERSION} supports the following
+families: @samp{AF_INET}, @samp{AF_INET6} and @samp{AF_UNIX}.
+
+@item address
+Remote IP address (for @samp{AF_INET} and @samp{AF_INET6}) or socket name (for
+@samp{AF_UNIX}). Notice that most Unixes return empty string instead
+of the @samp{AF_UNIX} socket name, so do not rely on it.
+
+@item port
+Remote port number (for @samp{AF_INET} and @samp{AF_INET6}).
+@end table
+@end deffn
+
+@deffn {Configuration} exec [from] @var{cidr} @var{program}
+If a connection from the @var{cidr} block is requested, execute the given
+@var{program}. Do not wait for it to terminate, and ignore its exit
+code. The @var{program} is subject for variable expansion as in
+@samp{ifexec}.
@end deffn
The following two controls are provided for logging purposes and as a
@@ -1229,27 +1297,8 @@ For connections over UNIX sockets. The socket name, if available, may
be printed before the closing curly brace.
@end table
-If the @var{string} is specified, it undergoes macro expansion and the
-result of it is used as the log entry. The following macro variables
-are expanded:
-
-@table @code
-@item aclno
-Ordinal number of the control in the ACL. Numbers begin from
-@samp{0}.
-
-@item family
-Connection family. Mailutils version @value{VERSION} supports two
-families: @samp{AF_INET} and @samp{AF_UNIX}.
-
-@item address
-Remote IP address (for @samp{AF_INET}) or socket name (for
-@samp{AF_UNIX}). Notice that most Unixes return empty string instead
-of the @samp{AF_UNIX} socket name, so do not rely on it.
-
-@item port
-Remote port number (for @samp{AF_INET}).
-@end table
+If @var{string} is supplied, it undergoes variable expansions as
+described for the @samp{ifexec}.
For example, the following ACL makes a Mailutils server log every
incoming connection:
@@ -1274,23 +1323,21 @@ its exit code.
@node Tcp-wrappers Statement
@subsection Tcp-wrappers Statement
-@UNREVISED
@kwindex tcp-wrappers
@subheading Syntax
@example
tcp-wrappers @{
# @r{Enable TCP wrapper access control.}
enable @var{bool};
+
# @r{Set daemon name for TCP wrapper lookups.}
daemon @var{name};
+
# @r{Use @var{file} for positive client address access control.}
allow-table @var{file};
+
# @r{Use file for negative client address access control.}
deny-table @var{file};
- # @r{Log allowed accesses at this syslog priority.}
- allow-syslog-priority @var{prio};
- # @r{Log denied accesses at this syslog priority.}
- deny-syslog-priority @var{prio};
@}
@end example
@@ -1336,32 +1383,23 @@ Use @var{file} as negative table. By default, @file{/etc/hosts.deny}
is used.
@end deffn
-@deffn {Configuration} allow-syslog-priority @var{prio};
-Log allowed accesses using syslog priority @var{prio}.
-@end deffn
-
-@deffn {Configuration} deny-syslog-priority @var{prio};
-Log denied accesses using syslog priority @var{prio}.
-@end deffn
-
@node Server Settings
@subsection Server Settings
-@UNREVISED
@cindex server settings, configuration
@cindex configuring servers
GNU Mailutils offers several server applications: @command{pop3d},
@command{imap4d}, @command{comsatd}, to name a few. Being quite
different in their purpose, they are very similar in some aspects of
their architecture. First of all, they all support two operating
-mode: a @dfn{daemon} mode, where a program disconnects from the controlling
-terminal and works in background, and an @dfn{inetd} mode, where it
+modes: @dfn{daemon}, where a program disconnects from the controlling
+terminal and works in background, and @dfn{inetd}, where it
remains in foreground and communicates with the remote party via
standard input and output streams. Secondly, when operating as
daemons, they listen to a preconfigured set of IP addresses and
ports, reacting to requests that arrive.
To configure these aspects of functionality, GNU Mailutils provides
-@dfn{Server Configuration Settings}, which we will describe in this
+@dfn{Server Configuration Settings}, which is describes in this
subsection.
@menu
@@ -1371,20 +1409,24 @@ subsection.
@node General Server Configuration
@subsubsection General Server Configuration
-@UNREVISED
@cindex server configuration, general
@* Syntax:
@example
# @r{Set daemon mode.}
mode @samp{inetd|daemon};
+
# @r{Run in foreground.}
foreground @var{bool};
+
# @r{Maximum number of children processes to run simultaneously.}
max-children @var{number};
+
# @r{Store PID of the master process in @var{file}.}
pidfile @var{file};
+
# @r{Default port number.}
port @var{portspec};
+
# @r{Set idle timeout.}
timeout @var{time};
@end example
@@ -1414,7 +1456,7 @@ Operate as a subprocess of UNIX internet super-server program,
@command{inetd}. @xref{Internet super-server,,,inetd(8), inetd(8) man
page}, for a detailed description of the operation of @command{inetd}
and its configuration. In this case it is @command{inetd} that
-controls all major connectivity aspects, the Mailutils server itself
+controls all major connectivity aspects. The Mailutils server program
communicates with it via standard input and output streams.
For historical reasons, this mode is t