diff options
author | Sergey Poznyakoff <gray@gnu.org> | 2015-09-20 14:21:54 +0300 |
---|---|---|
committer | Sergey Poznyakoff <gray@gnu.org> | 2015-09-20 14:21:54 +0300 |
commit | dcbf8f353e76d506ecf7ae6c48081783166a82ab (patch) | |
tree | b4850f711af489b9cd563f837847b84712aca663 /doc | |
parent | ad3cc340266af4e1d768e6d3e59594f78cd6f940 (diff) | |
download | mailutils-dcbf8f353e76d506ecf7ae6c48081783166a82ab.tar.gz mailutils-dcbf8f353e76d506ecf7ae6c48081783166a82ab.tar.bz2 |
Document mailbox types, variable extension, etc.
Diffstat (limited to 'doc')
-rw-r--r-- | doc/texinfo/mailutils.texi | 401 | ||||
-rw-r--r-- | doc/texinfo/programs.texi | 652 |
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 |