GNU Mailutils 1 Introduction 2 Mailbox 3 Mailutils Programs 4 Mailutils Libraries 5 Sieve Language 6 Reporting Bugs 7 Getting News About GNU Mailutils 8 Acknowledgement Appendix A References Appendix B Date Input Formats Appendix C Date/time Format String Appendix D Configuring Help Summary Appendix E GNU Free Documentation License Function Index Variable Index Keyword Index Program Index Concept Index GNU Mailutils 1 Introduction 1.1 What this Book Contains 1.2 A bit of History, and why use this package? 2 Mailbox 2.1 Local Mailboxes 2.2 Remote Mailboxes 2.3 SMTP Mailboxes 2.4 Program Mailboxes 3 Mailutils Programs 3.1 Command Line 3.1.1 Basic Notions About Command Line Options 3.1.2 Options That are Common for All Utilities. 3.2 Mailutils Configuration File 3.2.1 Configuration File Syntax 3.2.1.1 Comments 3.2.1.2 Statements 3.2.1.3 Statement Path 3.2.2 Configuration Variables 3.2.3 The 'include' Statement 3.2.4 The 'program' statement 3.2.5 The 'logging' Statement 3.2.6 The 'debug' Statement 3.2.7 The 'mailbox' Statement 3.2.8 The 'mime' Statement 3.2.9 The 'locking' Statement 3.2.10 The 'mailer' Statement 3.2.11 The 'acl' Statement 3.2.12 The 'tcp-wrappers' Statement 3.2.13 Server Settings 3.2.13.1 General Server Configuration 3.2.13.2 The 'server' Statement 3.2.14 The 'auth' Statement 3.2.15 PAM Statement 3.2.16 The 'virtdomain' Statement 3.2.17 The 'radius' Statement 3.2.18 The 'sql' Statement 3.2.19 The 'ldap' Statement 3.2.20 The 'tls' Statement 3.2.21 The 'tls-file-checks' Statement 3.2.22 The 'gsasl' Statement 3.3 Debugging 3.3.1 Level Syntax 3.3.2 BNF 3.3.3 Debugging Categories 3.4 'frm' and 'from' -- List Headers from a Mailbox 3.5 'mail' -- Send and Receive Mail 3.5.1 Invoking 'mail' 3.5.2 Reading Mail 3.5.2.1 Syntax of mail internal commands 3.5.2.2 Quitting the Program 3.5.2.3 Obtaining Online Help 3.5.2.4 Moving Within a Mailbox 3.5.2.5 Changing Mailbox/Directory 3.5.2.6 Controlling Header Display 3.5.2.7 Displaying Information 3.5.2.8 Displaying Messages 3.5.2.9 Marking Messages 3.5.2.10 Disposing of Messages 3.5.2.11 Saving Messages 3.5.2.12 Editing Messages 3.5.2.13 Aliasing 3.5.2.14 Replying 3.5.2.15 Controlling Sender Fields 3.5.2.16 Incorporating New Mail 3.5.2.17 Shell Escapes 3.5.3 Saving and Recording 3.5.4 Composing Mail 3.5.4.1 Quitting Compose Mode 3.5.4.2 Getting Help on Compose Escapes: ~? 3.5.4.3 Editing the Message: ~e and ~v 3.5.4.4 Modifying the Headers: ~h, ~t, ~c, ~b, ~s 3.5.4.5 Enclosing Another Message: ~m and ~M 3.5.4.6 Adding a File to the Message: ~r and ~d 3.5.4.7 Attaching a File to the Message 3.5.4.8 Printing And Saving the Message 3.5.4.9 Signing the Message: ~a and ~A 3.5.4.10 Printing Another Message: ~f and ~F 3.5.4.11 Inserting Value of a Mail Variable: ~i 3.5.4.12 Executing Other Mail Commands: ~: and ~- 3.5.4.13 Executing Shell Commands: ~! and ~| 3.5.5 Composing Multipart Messages 3.5.6 Scripting 3.5.7 How to Alter the Behavior of 'mail' 3.5.8 Personal and System-wide Configuration Files 3.6 'messages' -- Count the Number of Messages in a Mailbox 3.7 'movemail' -- Moves Mail from the User Maildrop to the Local File 3.7.1 Movemail Configuration 3.7.2 Setting Destination Mailbox Ownership 3.7.3 Movemail Usage Summary 3.8 'readmsg' -- Extract Messages from a Folder 3.8.1 Invocation of 'readmsg'. 3.8.2 Configuration of 'readmsg'. 3.9 'decodemail' - Decode multipart messages 3.9.1 Invocation of 'decodemail'. 3.9.2 Configuration of 'decodemail'. 3.9.3 Purpose and caveats of 'decodemail'. 3.10 'sieve' 3.10.1 A Sieve Interpreter 3.10.1.1 Invoking 'sieve' 3.10.1.2 Sieve Configuration 3.10.1.3 Logging and debugging 3.10.1.4 Extending 'sieve' 3.11 'guimb' -- A Mailbox Scanning and Processing Language 3.12 mda 3.12.1 Using 'mda' with Sendmail. 3.12.2 Using 'mda' with Exim. 3.12.3 Using 'mda' with MeTA1. 3.12.4 Mailbox Quotas 3.12.4.1 Keeping Quotas in DBM File 3.12.4.2 Keeping Quotas in SQL Database 3.12.5 Scripting in 'mda' 3.12.5.1 Sieve MDA Filters 3.12.5.2 Scheme MDA Filters 3.12.5.3 Python MDA Filters 3.12.6 Forwarding 3.12.7 MDA Configuration File Summary 3.12.8 Mailing list implementation 3.13 lmtpd 3.13.1 Using 'lmtpd' with MeTA1. 3.14 putmail 3.14.1 putmail options 3.14.2 putmail configuration 3.15 mimeview 3.15.1 Mimeview Invocation 3.15.2 Mimeview Config 3.16 POP3 Daemon 3.16.1 Login delay 3.16.2 Auto-expire 3.16.3 Bulletins 3.16.4 Pop3d Configuration 3.16.5 Command line options 3.17 IMAP4 Daemon 3.17.1 Namespace 3.17.2 Configuration of 'imap4d'. 3.17.3 Starting 'imap4d' 3.18 Comsat Daemon 3.18.1 Starting 'comsatd' 3.18.2 Configuring 'comsatd' 3.18.2.1 General Settings 3.18.2.2 Security Settings 3.18.3 A per-user Configuration File 3.19 MH -- The MH Message Handling System 3.19.1 Major differences between Mailutils MH and other MH implementations 3.19.1.1 New and Differing MH Format Specifications 3.19.1.2 New MH Profile Variables 3.19.1.3 Differences in MH Program Behavior 3.20 mailutils 3.20.1 Invocation Syntax 3.20.2 mailutils help 3.20.3 mailutils info 3.20.4 mailutils cflags 3.20.5 mailutils ldflags 3.20.6 mailutils stat 3.20.7 mailutils query 3.20.8 mailutils 2047 3.20.9 mailutils filter 3.20.10 mailutils acl 3.20.11 mailutils wicket 3.20.12 mailutils dbm 3.20.12.1 Create a Database 3.20.12.2 Add Records to a Database 3.20.12.3 Delete Records 3.20.12.4 List the Database 3.20.12.5 Dump the Database 3.20.12.6 Dump Formats 3.20.12.7 Dbm Exit Codes 3.20.13 mailutils logger 3.20.14 mailutils pop 3.20.15 mailutils imap 3.20.16 mailutils send 3.20.17 mailutils smtp 3.20.18 mailutils maildir_fixup 3.21 dotlock 4 Mailutils Libraries 5 Sieve Language 5.1 Lexical Structure 5.2 Syntax 5.2.1 Commands 5.2.2 Actions Described 5.2.3 Control Flow 5.2.4 Tests and Conditions 5.3 Preprocessor 5.3.1 Sieve #include directive 5.3.2 Sieve #searchpath directive 5.4 Require Statement 5.5 Comparators 5.6 Tests 5.6.1 Built-in Tests 5.6.2 External Tests 5.7 Actions 5.7.1 Built-in Actions 5.7.2 External Actions 5.8 Extensions 5.8.1 The encoded-character extension 5.8.2 The relational extension 5.8.3 The variables extension 5.8.4 environment 5.8.5 The numaddr extension 5.8.6 The editheader extension 5.8.7 The list extension 5.8.8 The moderator extension 5.8.9 The pipe extension 5.8.10 The spamd extension 5.8.11 The timestamp extension 5.8.12 The vacation extension 5.9 GNU Extensions 6 Reporting Bugs 7 Getting News About GNU Mailutils 8 Acknowledgement Appendix A References Appendix B Date Input Formats B.1 General date syntax B.2 Calendar date items B.3 Time of day items B.4 Time zone items B.5 Day of week items B.6 Relative items in date strings B.7 Pure numbers in date strings B.8 Seconds since the Epoch B.9 Specifying time zone rules B.10 Authors of 'get_date' Appendix C Date/time Format String Appendix D Configuring Help Summary Appendix E GNU Free Documentation License E.1 ADDENDUM: How to use this License for your documents Function Index Variable Index Keyword Index Program Index Concept Index GNU Mailutils ************* This edition of the 'GNU Mailutils Manual', last updated on 2 January 2022, documents GNU Mailutils Version 3.14. 1 Introduction ************** GNU Mailutils is a set of libraries and utilities for handling electronic mail. It addresses a wide audience and can be of interest to application developers, casual users and system administrators alike. It provides programmers with a consistent API allowing them to handle a variety of different mailbox formats transparently and without having to delve into complexities of their internal structure. While doing so, it also provides interfaces that simplify common programming tasks, such as handling lists, parsing configuration files, etc. The philosophy of Mailutils is to have a single and consistent programming interface for various objects designed to handle the same task. It tries to use their similarities to create an interface that hides their differences and complexities. This covers a wide variety of programming tasks: apart from mailbox handling, Mailutils also contains a unified iterface for work with various DBM databases and much more. The utilities built upon these libraries share that same distinctive feature: no matter what is the internal structure of an object, it is always handled the same way as other objects that do the same task. Again, the most common example of this approach are, of course, mailboxes. Whatever Mailutils program you use, you can be sure it is able to handle various mailbox formats. You even don't have to inform it about what type a mailbox is: it will do its best to discover it automatically. This approach sometimes covers entities which are seldom regarded as compatible. For example, using Mailutils it is possible to treat an SMTP connection as a mailbox opened only for appending new messages. This in turn, provides a way for extending the functionality of some utilities. As an example, using this concept of mailboxes, the usual mail delivery agent becomes able to do things usually reserved for mail transport agents only! At the core of Mailutils is 'libmailutils', a library which provides an API for accessing a generalized mailbox. A set of complementary libraries provide methods for handling particular mailbox implementations: UNIX mailbox, Maildir, MH, POP3, IMAP4, even SMTP. Mailutils offers functions for almost any mail-related task, such as parsing of messages, email addresses and URLs, handling MIME messages, listing mail folders, mailcap facilities, extensible Sieve filtering, access control lists. It supports various modern data security and authentication techniques: TLS encryption, SASL and GSSAPI, to name a few. Mailutils is able to work with a wide variety of authorization databases, ranging from traditional system password database up to RADIUS, SQL and LDAP. The utilities provided by Mailutils include 'imap4d' and 'pop3d' mail servers, mail reporting utility 'comsatd', general-purpose mail delivery agent 'maidag', mail filtering program 'sieve', an implementation of MH message handling system and much more. All utilities share the same subset of command line options and use a unified configuration mechanism, which allows to easily configure the package as a whole. This software is part of the GNU Project and is copyrighted by the Free Software Foundation. All libraries are distributed under the terms of the Lesser GNU Public License. The documentation is licensed under the GNU FDL, and everything else is licensed under the GNU GPL. 1.1 What this Book Contains =========================== This book addresses a wide audience of both system administrators and users that aim to use Mailutils programs, and programmers who wish to use Mailutils libraries in their programs. Given this audience, the book is divided in three major parts. The first part provides a detailed description of each Mailutils utility, and advices on how to use them in various situations. This part is intended for users and system administrators who are using Mailutils programs. If you are not interested in programming using Mailutils, this is the only part you need to read. Subsequent parts address programmers. The second part is a tutorial which provides an introduction to programming techniques for writing mail applications using GNU Mailutils. Finally, the third part contains a complete Mailutils library reference. This version of the book is not finished. The places that may contain inaccurate information carry prominent notices stating so. For updated versions of the documentation, visit . All material that ends up in this document is first published in the Mailutils Wiki, available at . Be sure to visit it for latest updates. If you have any questions that are not answered there, feel free to ask them at the mailing list . 1.2 A bit of History, and why use this package? =============================================== ================================================================== *Editor's note:* The information in this node may be obsolete or otherwise inaccurate. This message will disappear, once this node revised. ================================================================== This package started off to try and handle large mailbox files more gracefully then available at that time POP3 servers did. While it handles this task, it also allows you to support a variety of different mailbox formats without any real effort on your part. Also, 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. 2 Mailbox ********* The principal object Mailutils operates on is "mailbox" - a collection of mail messages. The two main characteristics of a mailbox are its type and path. The "type" defines how the messages are stored within a mailbox. The "path" specifies the location of the mailbox. The two characteristics are usually combined within a "Uniform Resource Locator" (URL), which uniquely identifies the mailbox. The syntax for URL is: TYPE:[//[USER:PASSWORD@]HOST[:PORT]]PATH[?QUERY][;PARAMS] The square brackets do not appear in a 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. 2.1 Local Mailboxes =================== "Local mailboxes" store mail in files on the local file system. A local mailbox URL is: TYPE://PATH[;PARAMS] The PATH defines its location in the file system. For example: mbox:///var/spool/mail/gray Optional PARAMS is a semicolon-separated list of optional arguments that configures indexed directory structure. *Note local URL parameters::, for a detailed description. The local mailbox types are: mbox A traditional UNIX mailbox format. Messages are stored sequentially in a single file. Each message begins with a 'From' line, identifying its sender and date when it was received. A single empty line separates two adjacent messages. This is the default format. maildir The "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. This format was originally described by D. J. Bernstein in . 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. This format was originally developed by RAND Corporation. Mailutils implementation is compatible both with the original implementation and with its descendant "nmh". 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. 2.2 Remote Mailboxes ==================== "Remote mailboxes" are accessed via one of the remote message protocols. The basic remote mailbox types are: pop Remote mailbox accessed using the "Post Office Protocol" (POP3). Default port number 110. The URL is: pop://[USER[:PASS][;auth=+APOP]@]HOST[:PORT][;notls] The HOST gives the name or IP address of the host running a POP3 server. Optional PORT can be used to connect to a port other than the default 110. The USER and 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 '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 'notls' parameter disables this behavior. pops Remote mailbox accessed using the "Post Office Protocol" (POP3). The transmission channel is encrypted using the "transport layer security" (TLS). The default port is 995. The URL is: pops://[USER[:PASS][;auth=+APOP]@]HOST[:PORT] The meaning of its components is the same as for 'pop' type. imap Remote mailbox accessed via the "Internet Message Access Protocol". Default port number is 143. The URL is: imap://[USER[:PASS]@]HOST[:PORT][;notls] The HOST gives the name or IP address of the host running a IMAP4 server. Optional PORT can be used to connect to a port other than the default 143. The USER and 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 'notls' parameter disables this behavior. imaps The 'imaps' type differs in that its transmission channel is encrypted using the "transport layer security" (TLS). The default port is 993. The URL is: imaps://[USER[:PASS]@]HOST[:PORT] The meaning of its components is the same as for 'imap' type. 2.3 SMTP Mailboxes ================== 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. smtp A remote mailbox accessed using the Simple Message Transfer Protocol. The SMTP URL syntax is: smtp://[USER[:PASS][;auth=MECH,...]@]HOST[:PORT][;PARAMS] The HOST gives the name or IP address of the host running SMTP server. Optional PORT can be used to connect to a port other than the default 25. The USER, PASS, and '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 '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.: smtp://smith:guessme;auth=cram-md5,digest-md5@localhost Optional PARAMS is a semicolon-separated list of additional parameters. Valid parameters are: domain=STRING Append '@STRING' to those recipient addresses that lack the domain part. from=ADDR Use ADDR as sender address. noauth Disable ESMTP authentication. notls Disable TLS. recipient-headers[=NAME[,NAME...]] Use the supplied header names to determine recipient addresses. When no values are supplied, disables header scanning. strip-domain Strip domain part from all recipient addresses. to=ADDR[,ADDR...] Deliver messages to the supplied email addresses. smtps A remote mailbox accessed using the Simple Message Transfer Protocol, with the transmission channel encrypted using the "transport layer security" (TLS). The default port is 465. The URL is smtps://[USER[:PASS][;auth=MECH,...]@]HOST[:PORT][;PARAMS] See the 'smtp' type for a detailed description of its types. The only difference from 'smtp' is that the 'notls' parameter is not used. 2.4 Program Mailboxes ===================== 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. A 'sendmail' mailbox is identified by the following URL: sendmail[://PATH] The messages are sent by invoking 'sendmail' binary with the '-oi -t' options. If the message being appended has the 'From:' header, its value is passed to 'sendmail' using the '-f' option. The default path to the sendmail binary is system-dependent. The PATH part can be used to specify it explicitly. The 'prog' mailbox URL is: prog://PATHNAME[?QUERY] Messages are appended by invoking the program PATHNAME with the arguments supplied by QUERY. The latter is a list of words delimited by '&' characters. Arguments can contain the following variables (*note Variables::): sender Expands to the sender email address. rcpt Expands to comma-separated list of email addresses obtained from 'To:', 'Cc:' and 'Bcc:' headers of the message. 3 Mailutils Programs ******************** GNU Mailutils provides a broad set of utilities for handling electronic mail. These utilities address the needs of both system administrators and users. All utilities are built around a single core subsystem and share many common aspects. All of them are able to work with almost any existing mailbox formats. They use a common configuration file syntax, and their configuration files are located in a single subdirectory. In this chapter we will discuss each utility, and give some advices on how to use them in various real life situations. First of all we will describe command line and configuration file syntax. 3.1 Command Line ================ 3.1.1 Basic Notions About Command Line Options ---------------------------------------------- Many command line options have two forms, called short and long forms. Both forms are absolutely identical in function; they are interchangeable. The "short" form is a traditional form for UNIX utilities. In this form, the option consists of a single dash, followed by a single letter, e.g. '-c'. Short options which require arguments take their arguments immediately following the option letter, optionally separated by white space. For example, you might write '-f name', or '-fname'. Here, '-f' is the option, and 'name' is its argument. Short options which allow optional arguments take their arguments immediately following the option letter, _without any intervening white space characters_. This is important, so that the command line parser might discern that the text following option is its argument, not the next command line parameter. For example, if option '-d' took an optional argument, then '-dname' would mean the option with its argument ('name' in this case), and '-d name' would mean the '-d' option without any argument, followed by command line argument 'name'. Short options' letters may be clumped together, but you are not required to do this. When short options are clumped as a set, use one (single) dash for them all, e.g. '-cvl' is equivalent to '-c -v -l'. However, only options that do not take arguments may be clustered this way. If an option takes an argument, it can only be the last option in such a cluster, otherwise it would be impossible to specify the argument for it. Anyway, it is much more readable to specify such options separated. The "long" option names are probably easier to memorize than their short counterparts. They consist of two dashes, followed by a multi-letter option name, which is usually selected to be a mnemonics for the operation it requests. For example, '--verbose' is a long option that increases the verbosity of a utility. In addition, long option names can abbreviated, provided that such an abbreviation is unique among the options understood by a given utility. For example, if a utility takes options '--foreground' and '--forward', then the shortest possible abbreviations for these options are '--fore' and '--forw', correspondingly. If you try to use '--for', the utility will abort and inform you that the abbreviation you use is ambiguous, so it is not clear which of the options you intended to use. Long options which require arguments take those arguments following the option name. There are two ways of specifying a mandatory argument. It can be separated from the option name either by an equal sign, or by any amount of white space characters. For example, if the '--file' option requires an argument, and you wish to supply 'name' as its argument, then you can do so using any of the following notations: '--file=name' or '--file name'. In contrast, optional arguments must always be introduced using an equal sign. 3.1.2 Options That are Common for All Utilities. ------------------------------------------------ All GNU Mailutils programs understand a common subset of options. '--help' '-?' Display a short summary of the command line options understood by this utilities, along with a terse description of each. The output of this option consists of three major parts. First, a usage synopsis is displayed. For example: Usage: sieve [OPTION...] SCRIPT GNU sieve -- a mail filtering tool The first line tells that the 'sieve' utility takes any number of options (brackets indicate optional part) and a single mandatory argument ('SCRIPT'). The second lines summarizes the purpose of the utility. Following this header is an option summary. It consists of two columns: -c, --compile-only Compile script and exit -d, --debug[=FLAGS] Debug flags -e, --email=ADDRESS Override user email address The leftmost column contains a comma-separated list of option names. Short options are listed first. The options are ordered alphabetically. Arguments, if any, are specified after the last option name in the list, so that, e.g. the option '-e' in the example above requires an argument: '-e ADDRESS'. Optional arguments are enclosed in square brackets, as in '--debug' option in the example above. The rightmost column contains a short description of the option purpose. The last part of '--help' output contains some additional notices and lists the email address for reporting bugs. '--usage' Display a short summary of options. In the contrast to the '--help' option, only option names and arguments are printed, without any textual description. For example: Usage: sieve [-cv?V] [--compile-only] [--debug[=FLAGS]] [--email=ADDRESS] SCRIPT The exact formatting of the output produced by these two options is configurable. *Note Usage Vars::, for a detailed descriptions of it. '--version' '-V' Print program version and exit. '--show-config-options' Show configuration options used when compiling the package. You can use this option to verify if support for a particular mailbox format or other functionality is compiled in the binary. The output of this option is intended to be both machine-readable and understandable by humans. The following command line options affect parsing of configuration files. Here we provide a short summary, the next section will describe them in detail. '--config-file=FILE' Load this configuration file, instead of the default. '--config-help' Show configuration file summary. '--config-lint' Check configuration file syntax and exit '--config-verbose' Verbosely log parsing of the configuration files. '--no-site-config' Do not load site-wide configuration file. '--no-user-config' Do not load user configuration file. '--no-config' Don't load site-wide and user configuration files. '--set=PATH=VALUE' Set configuration variable. *Note the --set option::. 3.2 Mailutils Configuration File ================================ Configuration files are the principal means of configuring any GNU Mailutils component. When started, each utility tries to load its configuration from the following locations, in that order: 1. Main site-wide configuration file. It is named 'SYSCONFDIR/mailutils.conf', where SYSCONFDIR stands for the system configuration directory set when compiling the package. You can obtain the value of SYSCONFDIR by running $ mailutils info sysconfdir or $ PROG --show-config-options | grep SYSCONFDIR where PROG stands for any GNU Mailutils utility. The site-wide configuration file is not read if any of '--no-site-config' or '--no-config' command line options was given. Older versions of GNU Mailutils read configuration from file 'mailutils.rc'. To facilitate transition, mailutils will look for that file as well. If both the default site-wide configuration file and legacy configuration file are present you will get the following warning: legacy configuration file /etc/mailutils.rc ignored Otherwise, if 'mailutils.conf' does not exist and 'mailutils.rc' is present, it will be used instead and the following warning will be issued: using legacy configuration file /etc/mailutils.rc: please rename it to /etc/mailutils.conf 2. Per-user configuration file. Client utilities, such as 'frm' or 'sieve', look in the user home directory for a file named '.PROG', where PROG is the name of the utility. If present, this file will be loaded after loading the site-wide configuration file. For example, the per-user configuration file for 'sieve' utility is named '.sieve'. Loading of per-user configuration file is disabled by '--no-user-config' and '--no-config' options. Server programs, such as 'imap4d' don't use per-user configuration files. The '--no-config' option provides a shortcut for disabling loading of the default configuration files. For servers, its effect is the same as of '--no-site-config'. For client utilities, it is equivalent to '--no-site-config --no-user-config' used together. The '--config-file' command line option instructs the program to read configuration from the file supplied as its argument. In that case, default configuration files are not used at all. Neither site-wide nor user configuration files are required to exist. If any or both of them are absent, GNU Mailutils won't complain - the utility will silently fall back to its default settings. To make configuration processing more verbose, use the '--config-verbose' command line option. Here is an example of what you might get using this option: imap4d: parsing file `/etc/mailutils.conf' imap4d: finished parsing file `/etc/mailutils.conf' Specifying this option more than once adds more verbosity to this output. If this option is given two times, GNU Mailutils will print each configuration file statement it parsed, along with the exact location where it occurred (the exact meaning of each statement will be described later in this chapter): imap4d: parsing file `/etc/mailutils.conf' # 1 "/etc/mailutils.conf" mailbox { # 2 "/etc/mailutils.conf" mailbox-pattern maildir:/var/spool/mail;type=index;param=2;user=${user}; # 3 "/etc/mailutils.conf" mailbox-type maildir; }; # 6 "/etc/mailutils.conf" include /etc/mailutils.d; imap4d: parsing file `/etc/mailutils.d/imap4d' ... To test configuration file without actually running the utility, use the '--config-lint' command line option. With this option, any Mailutils utility exits after finishing parsing of the configuration files. Any errors occurred during parsing are displayed on the standard error output. This option can be combined with '--config-verbose' to obtain more detailed output. The '--config-help' command line option produces on the standard output the summary of all configuration statements understood by the utility, with detailed comments and in the form suitable for configuration file. For example, the simplest way to write a configuration file for, say, 'imap4d' is to run $ imap4d --config-help > imap4d.conf and to edit the 'imap4d.conf' file with your editor of choice. The order in which configuration files are loaded defines the precedence of their settings. Thus, for client utilities, settings from the per-user configuration file override those from the site-wide configuration. It is also possible to set or override arbitrary configuration variables in the command line. It can be done via the '--set' option. Its argument is a "pathname" of the variable to be set, followed by an equals sign and a value. For example, to define the variable 'syslog' in section 'logging' to 'no', do the following: $ imap4d --set .logging.syslog=no Configuration pathnames are discussed in detail in *note Paths::. For a detailed description of this option, *note the --set option::. The '--set' options are processed after loading all configuration files. 3.2.1 Configuration File Syntax ------------------------------- The configuration file consists of statements and comments. There are three classes of lexical tokens: keywords, values, and separators. Blanks, tabs, newlines and comments, collectively called "white space" are ignored except as they serve to separate tokens. Some white space is required to separate otherwise adjacent keywords and values. 3.2.1.1 Comments ................ "Comments" may appear anywhere where white space may appear in the configuration file. There are two kinds of comments: single-line and multi-line comments. "Single-line" comments start with '#' or '//' and continue to the end of the line: # This is a comment // This too is a comment "Multi-line" or "C-style" comments start with the two characters '/*' (slash, star) and continue until the first occurrence of '*/' (star, slash). Multi-line comments cannot be nested. However, single-line comments may well appear within multi-line ones. 3.2.1.2 Statements .................. A "simple statement" consists of a keyword and value separated by any amount of whitespace. Simple statement is terminated with a semicolon (';'). The following is a simple statement: standalone yes; pidfile /var/run/pop3d.pid; A "keyword" begins with a letter and may contain letters, decimal digits, underscores ('_') and dashes ('-'). Examples of keywords are: 'expression', 'output-file'. A "value" can be one of the following: number A number is a sequence of decimal digits. boolean A boolean value is one of the following: 'yes', 'true', 't' or '1', meaning "true", and 'no', 'false', 'nil', '0' meaning "false". unquoted string An unquoted string may contain letters, digits, and any of the following characters: '_', '-', '.', '/', '@', '*', ':'. quoted string A quoted string is any sequence of characters enclosed in double-quotes ('"'). A backslash appearing within a quoted string introduces an "escape sequence", which is replaced with a single character according to the following rules: Sequence Replaced with \a Audible bell character (ASCII 7) \b Backspace character (ASCII 8) \f Form-feed character (ASCII 12) \n Newline character (ASCII 10) \r Carriage return character (ASCII 13) \t Horizontal tabulation character (ASCII 9) \v Vertical tabulation character (ASCII 11) \\ A single backslash ('\') \" A double-quote. Table 3.1: Backslash escapes In addition, the sequence '\NEWLINE' is removed from the string. This allows to split long strings over several physical lines, e.g.: "a long string may be\ split over several lines" If the character following a backslash is not one of those specified above, the backslash is ignored and a warning is issued. Two or more adjacent quoted strings are concatenated, which gives another way to split long strings over several lines to improve readability. The following fragment produces the same result as the example above: "a long string may be" " split over several lines" Here-document A "here-document" is a special construct that allows to introduce strings of text containing embedded newlines. The '<; # Kind of TLS encryption to use for this server. tls-mode 'no'|'ondemand'|'required'|'connection'; tls { # Specify SSL certificate file. ssl-certificate-file STRING; # Specify SSL certificate key file. ssl-key-file FILE; # Specify trusted CAs file. ssl-ca-file FILE; # Set the priorities to use on the ciphers, methods, etc. ssl-priorities STRING; # Set timeout for I/O operations during TLS handshake (seconds). handshake-timeout N; } # Set server specific ACLs. acl { /* *Note ACL Statement::. */ }; } Description: The 'server' block statement configures a single TCP or UDP server. It takes effect only in daemon mode (*note server mode::). The argument to this statement specifies the IP address, and, optionally, the port, to listen on for requests. The IPADDR part is either an IPv4 address in dotted-quad form, or a IPv6 address enclosed in square brackets, or a symbolic host name which can be resolved to such an address. Specifying '0.0.0.0' as the IPADDR means listen on all available network interfaces. The PORT argument is either a port number in decimal, or a symbolic service name, as listed in '/etc/services' (*note (services(5))Internet network services list::). If PORT is omitted, Mailutils uses the port set by 'port' statement (*note port: General Server Configuration.), or, in its absence, the default port number, which depends on a server being used (e.g. 110, for 'pop3d', 143, for 'imap4d', etc.). Any number of 'server' statements may be specified in a single configuration file, allowing to set up the same service on several IP addresses and/or port numbers, and with different configurations. Statements within the 'server' block statement configure this particular server. -- Configuration: single-process BOOL; If set to true, this server will operate in single-process mode. This mode is intended for debugging only, do not use it on production servers. -- Configuration: transcript BOOL; Enable transcript of the client-server interaction. This may generate excessive amounts of logging, which in turn may slow down the operation considerably. Session transcripts are useful in fine-tuning your configurations and in debugging. They should be turned off on most production servers. -- Configuration: timeout TIME; Set idle timeout for this server. This overrides the global timeout settings (*note timeout: General Server Configuration.). -- Configuration: backlog NUMBER; Configures the size of the queue of pending connections -- Configuration: tls-mode MODE; Configure the use of TLS encryption. The MODE argument is one of the following: no TLS is not used. The corresponding command ('STLS', for POP3, 'STARTTLS', for 'IMAP4') won't be available even if the TLS configuration is otherwise complete. ondemand TLS is initiated when the user issues the appropriate command. This is the default when TLS is configured. required Same as above, but the use of TLS is mandatory. The authentication state is entered only after TLS negotiation has succeeded. connection TLS is always forced when the connection is established. For 'pop3d' this means using POP3S protocol (or IMAP4S, for 'imap4d'). -- Configuration: tls { ... } The 'tls' statement configures SSL certificate and key files, as well as other SSL settings for use in this server. It is used when 'tls-mode' is set to any of the following values: 'ondemand', 'required', 'connection'. If 'tls-mode' is set to any of the values above and 'tls' section is absent, settings from the global 'tls' section will be used. In this case, it is an error if the global 'tls' section is not defined. *Note tls statement::, for a discussion of its syntax. -- Configuration: acl This statement defines a per-server Access Control List. Its syntax is as described in *note ACL Statement::. Per-server ACLs complement, but not override, global ACLs, i.e. if both global ACL and per-server ACL are used, the connection is allowed only if both of them allow it, and is denied if any one of them denies it. 3.2.14 The 'auth' Statement --------------------------- Syntax ------ auth { # Set a list of modules for authentication. authentication MODULE-LIST; # Set a list of modules for authorization. authorization MODULE-LIST; } Description ----------- Some mail utilities provide access to their services only after verifying that the user is actually the person he is claiming to be. Such programs are, for example, 'pop3d' and 'imap4d'. The process of the verification is broken down into two stages: "authorization" and "authentication". In "authorization" stage the program retrieves the information about a particular user. In "authentication" stage, this information is compared against the user-supplied credentials. Only if both stages succeed is the user allowed to use the service. A set of "modules" is involved in performing each stage. For example, the authorization stage can retrieve the user description from various sources: system database, SQL database, virtual domain table, etc. Each module is responsible for retrieving the description from a particular source of information. The modules are arranged in a "module list". The modules from the list are invoked in turn, until one of them succeeds or the list is exhausted. In the latter case the authorization fails. Otherwise, the data returned by the succeeded module are used in authentication. Similarly, authentication may be performed in several ways. The authentication modules are also grouped in a list. Each module is tried in turn until either a module succeeds, in which case the authentication succeeds, or the end of the list is reached. For example, the authorization list (system, sql, virtdomains) means that first the system user database ('/etc/password') is searched for a description of a user in question. If the search fails, the SQL database is searched. Finally, if it also fails, the search is performed in the virtual domain database. _Note_, that some authentication and/or authorization modules may be disabled when configuring the package before compilation. The names of the disabled modules are nevertheless available for use in runtime configuration options, but they represent a "fail-only" functionality, e.g. if the package was compiled without SQL support then the module 'sql' in the above example will always fail, thus passing the execution on to the next module. The 'auth' statement configures authentication and authorization. -- Configuration: authorization MODULE-LIST Define a sequence of modules to use for authorization. Modules will be tried in the same order as listed in MODULE-LIST. The modules available for use in authorization list are: system User credentials are retrieved from the system user database ('/etc/password'). sql User credentials are retrieved from a SQL database. A separate configuration statement, 'sql', is used to configure it (*note sql statement::). virtdomain User credentials are retrieved from a "virtual domain" user database. Virtual domains are configured using 'virtdomain' statement (*note virtdomain statement::). radius User credentials are retrieved using RADIUS. *Note radius statement::, for a detailed description on how to configure it. ldap User credentials are retrieved from an LDAP database. *Note ldap statement::, for an information on how to configure it. Unless overridden by 'authorization' statement, the default list of authorization modules is: 1. generic 2. system 3. pam 4. sql 5. virtual 6. radius 7. ldap -- Configuration: authentication MODULE-LIST Define a sequence of modules to use for authentication. Modules will be tried in the same order as listed in MODULE-LIST. The following table lists modules available for use in MODULE-LIST: generic The generic authentication type. User password is hashed and compared against the hash value returned in authorization stage. system The hashed value of the user password is retrieved from '/etc/shadow' file on systems that support it. sql The hashed value of the user password is retrieved from a SQL database using query supplied by 'getpass' statement (*note getpass: sql statement.). pam The user is authenticated via pluggable authentication module (PAM). The PAM service name to be used is configured in 'pam' statement (*note pam statement::). radius The user is authenticated on a remote RADIUS server. *Note radius statement::. ldap The user is authenticated using LDAP. *Note ldap statement::. Unless overridden by 'authentication' statement, the list of authentication modules is the same as for 'authorization', i.e.: 1. generic 2. system 3. pam 4. sql 5. virtual 6. radius 7. ldap 3.2.15 PAM Statement -------------------- Syntax ------ pam { # Set PAM service name. service TEXT; } Description ----------- The 'pam' statement configures PAM authentication. It contains a single sub-statement: -- Configuration: service TEXT Define service name to look for in PAM configuration. By default, the base name of the Mailutils binary is used. This statement takes effect only if 'pam' is listed in 'authentication' statement (*note auth statement::). 3.2.16 The 'virtdomain' Statement --------------------------------- Syntax ------ virtdomain { # Name of the virtdomain password directory. passwd-dir DIR; } Description ----------- "Virtual mail domains" make it possible to handle several mail domains each having a separate set of users, on a single server. The domains are completely independent of each other, i.e. the same user name can be present in several domains and represent different users. When authenticating to a server with virtual domain support enabled, users must supply their user names with domain parts. The server strips off the domain part and uses it as a name of UNIX-format password database file, located in the "domain password directory". The latter is set using 'passwd-dir' statement. -- Configuration: passwd-dir DIR Set virtual domain password directory. For example, when authenticating user 'smith@example.com', the server will use password file named 'DIR/example.com'. This file must be in UNIX passwd format (*note (passwd(5))password file::), with encrypted passwords stored in it (as of GNU Mailutils version 3.14, there is no support for shadow files in virtual password directories, although this is planned for future versions). Here is an example record from this file: smith:Wbld/G2Q2Le2w:1000:1000:Email Account:/var/mail/domain/smith:/dev/null Notice, that it must contain user names without domain parts. The 'pw_dir' field (the 6th field) is used to determine the location of the maildrop for this user. It is defined as 'PW_DIR/INBOX'. In our example, the maildrop for user 'smith' will be located in file '/var/mail/domain/smith'. If user did not supply his domain name, or if no matching record was found in the password file, or if the file matching the domain name does not exist, then GNU Mailutils falls back to alternative method. First, it tries to determine the IP address of the remote party. Then the domain name corresponding to that address is looked up in the DNS system. Finally, this domain name is used as a name of the password file. 3.2.17 The 'radius' Statement ----------------------------- Syntax ------ radius { # Set radius configuration directory. directory DIR; # Radius request for authorization. auth REQUEST; # Radius request for getpwnam. getpwnam REQUEST; # Radius request for getpwuid. getpwuid REQUEST; } Description ----------- The 'radius' block statement configures RADIUS authentication and authorization. Mailutils uses GNU Radius library, which is configured via 'raddb/client.conf' file (*note Client Configuration: (radius)client.). Its exact location depends on configuration settings that were used while compiling GNU Radius. Usually it is '/usr/local/etc', or '/etc'. This default can also be changed at run time using 'directory' statement: -- Configuration: directory DIR Set full path name to the GNU Radius configuration directory. It authorization is used, the Radius dictionary file must declare the the following attributes: Attribute Type Description --------------------------------------------------------------------------- GNU-MU-User-Name string User login name GNU-MU-UID integer UID GNU-MU-GID integer GID GNU-MU-GECOS string GECOS GNU-MU-Dir string Home directory GNU-MU-Shell string User shell GNU-MU-Mailbox string User mailbox GNU-MU-Quota integer Mail quota (in bytes) A dictionary file with appropriate definitions is included in the Mailutils distribution: 'examples/config/mailutils.dict'. This file is not installed by default, you will have to manually copy it to the GNU Radius 'raddb/dict' directory and include it in the main dictionary file 'raddb/dictionary' by adding the following statement: $INCLUDE dict/mailutils.dict Requests to use for authentication and authorization are configured using three statements: 'auth', 'getpwnam' and 'getpwuid'. Each statement takes a single argument: a string, containing a comma-separated list of assignments. An assignment specifies a particular "attribute-value pair" (*note RADIUS Attributes: (radius)Overview.) to send to the server. The left-hand side of the assignment is a symbolic attribute name, as defined in one of Radius dictionaries (*note Dictionary of Attributes: (radius)dictionary file.). The value is specified by the right-hand side of assignment. For example: "Service-Type = Authenticate-Only, NAS-Identifier = \"mail\"" The assignment may contain references to the following variables (*note Variables::): user The actual user name (for 'auth' and 'getpwnam'), or user ID (for 'getpwuid'). For example: User-Name = ${user} passwd User password. For examples: User-Password = ${passwd} -- Configuration: auth PAIRLIST Specifies the request to be sent to authenticate the user. For example: auth "User-Name = ${user}, User-Password = ${passwd}"; The user is authenticated only if this request returns 'Access-Accept' (*note Access-Accept: (radius)Authentication Requests.). Any returned attribute-value pairs are ignored. -- Configuration: getpwnam PAIRLIST Specifies the request that returns user information for the given user name. For example: getpwnam "User-Name = ${user}, State = getpwnam, " "Service-Type = Authenticate-Only"; If the requested user account exists, the Radius server must return 'Access-Accept' packet with the following attributes: 'GNU-MU-User-Name', 'GNU-MU-UID', 'GNU-MU-GID', 'GNU-MU-GECOS', 'GNU-MU-Dir', 'GNU-MU-Shell'. The attributes 'GNU-MU-Mailbox' and 'GNU-MU-Quota' are optional. If 'GNU-MU-Mailbox' is present, it must contain a valid mailbox URL (*note URL: Mailbox.). If 'GNU-MU-Mailbox' is not present, Mailutils constructs the mailbox name using the settings from the 'mailbox' configuration statement (*note Mailbox Statement::), or built-in defaults, if it is not present. If 'GNU-MU-Quota' is present, it specifies the maximum mailbox size for this user, in bytes. In the absence of this attribute, mailbox size is unlimited. -- Configuration: getpwuid PAIRLIST Specifies the request that returns user information for the given user ID. In PAIRLIST, the 'user' macro-variable is expanded to the numeric value of ID. For example: getpwuid "User-Name = ${user}, State = getpwuid, " "Service-Type = Authenticate-Only"; The reply to 'getpwuid' request is the same as to 'getpwnam' request (see above). 3.2.18 The 'sql' Statement -------------------------- Syntax ------ sql { # Set SQL interface to use. interface 'mysql|odbc|postgres'; # SQL server host name. host ARG; # SQL user name. user ARG; # Password for the SQL user. passwd ARG; # SQL server port. port ARG; # Database name. db ARG; # Type of password returned by getpass query. password-type 'plain | hash | scrambled'; # Set a field-map for parsing SQL replies. field-map LIST; # SQL query returning the user's password. getpass QUERY; # SQL query to use for getpwnam requests. getpwnam QUERY; # SQL query to use for getpwuid requests. getpwuid QUERY; } Description ----------- The 'sql' statement configures access credentials to SQL database and the queries for authentication and authorization. GNU Mailutils supports three types of SQL interfaces: MySQL, PostgreSQL and ODBC. The latter is a standard API for using database management systems, which can be used to communicate with a wide variety of DBMS. -- Configuration: interface TYPE Configures type of DBMS interface. Allowed values for TYPE are: mysql Interface with a MySQL server (). odbc Use ODBC interface. See , for a detailed description of ODBC configuration. postgres Interface with a PostgreSQL server (). The database and database access credentials are configured using the following statements: -- Configuration: host ARG The host running the SQL server. The value can be either a host name or an IP address in dotted-quad notation, in which case an INET connection is used, or a full pathname to a file, in which case a connection to UNIX socket is used. -- Configuration: port ARG TCP port the server is listening on (for INET connections). This parameter is optional. Its default value depends on the type of database being used. -- Configuration: db ARG; Name of the database. -- Configuration: user ARG SQL user name. -- Configuration: passwd ARG; Password to access the database. -- Configuration: password-encryption ARG; Defines type of encryption used by the password returned by 'getpass' query (see below). Possible arguments are: plain Password is in plain text. crypt hash Password is encrypted by system 'crypt' function (*note (crypt(3))crypt::). scrambled Password is encrypted by MySQL 'password' function. -- Configuration: getpwnam QUERY Defines SQL query that returns information about the given user. The QUERY is subject to variable expansion (*note Variables::). The only variable defined is '$user', which expands to the user name. The query should return a single row with the following columns: name User name. passwd User password. uid UID of the user. gid GID of the primary group. gecos Textual description of the user. dir User's home directory shell User's shell program. The following columns are optional: mailbox Full pathname of the user's mailbox. If not returned or NULL, the mailbox is determined using the default algorithm (*note Mailbox::). quota Upper limit on the size of the mailbox. The value is either an integer number optionally followed by one of the usual size suffixes: 'K', 'M', 'G', or 'T' (case-insensitive). -- Configuration: getpwuid QUERY Defines SQL query that returns information about the given UID. The QUERY is subject to variable expansion (*note Variables::). The only variable defined is '$user', which expands to the UID. The query should return a single row, as described for 'getpwnam'. -- Configuration: getpass QUERY Defines SQL query that returns the password of the given user. The QUERY is subject to variable expansion (*note Variables::). The only variable defined is '$user', which expands to the user name. The query should return a row with a single column, which gives the password. The password can be encrypted as specified by the 'password-encryption' statement. -- Configuration: field-map LIST Defines a translation map for column names. The LIST is a list of mappings. Each mapping is a string 'NAME=COLUMN', where NAME is one of the names described in *note getpw column names::, and COLUMN is the name of the column in the returned row that should be used instead. The effect of this statement is similar to that of SQL 'AS' keyword. E.g. the statement field-map (uid=user_id); has the same effect as using 'SELECT user_id AS uid' in the SQL statement. 3.2.19 The 'ldap' Statement --------------------------- Syntax ------ ldap { # Enable LDAP lookups. enable BOOL; # Set URL of the LDAP server. url URL; # Base DN for LDAP lookups. base STRING; # DN for accessing LDAP database. binddn STRING; # Password for use with binddn. passwd STRING; # Use TLS encryption. tls BOOL; # Set LDAP debugging level. debug NUMBER; # Set a field-map for parsing LDAP replies. field-map LIST; # LDAP filter to use for getpwnam requests. getpwnam STRING; # LDAP filter to use for getpwuid requests. getpwuid FILTER; } Description ----------- The 'ldap' statement configures the use of LDAP for authentication. -- Configuration: enable BOOL Enables LDAP lookups. If absent, 'enable On' is assumed. -- Configuration: url URL Sets the URL of the LDAP server. -- Configuration: base STRING Defines base DN for LDAP lookups. -- Configuration: binddn STRING Defines the DN for accessing LDAP database. -- Configuration: passwd STRING Password for use when binding to the database. -- Configuration: tls BOOL Enable the use of TLS when connecting to the server. -- Configuration: debug NUMBER Set LDAP debug level. Please refer to the OpenLDAP documentation, for allowed NUMBER values and their meaning. -- Configuration: field-map MAP Defines a map for parsing LDAP replies. The MAP is a list of mappings(1). Each mapping is 'FIELD=ATTR', where ATTR is the name of the LDAP attribute and FIELD is a field name that declares what information that attribute carries. Available values for FIELD are: name User name. passwd User password. uid UID of the user. gid GID of the primary group. gecos Textual description of the user. dir User's home directory shell User's shell program. The default mapping is ("name=uid", "passwd=userPassword", "uid=uidNumber", "gid=gidNumber", "gecos=gecos", "dir=homeDirectory", "shell=loginShell") -- Configuration: getpwnam STRING Defines the LDAP filter to use for 'getpwnam' requests. The default is: (&(objectClass=posixAccount) (uid=$user)) -- Configuration: getpwuid STRING Defines the LDAP filter to use for 'getpwuid' requests. The default filter is: (&(objectClass=posixAccount) (uidNumber=$user)) ---------- Footnotes ---------- (1) For backward compatibility, MAP can be a string containing colon-delimited list of mappings. Such usage is, however, deprecated. 3.2.20 The 'tls' Statement -------------------------- Syntax ------ tls { # Specify SSL certificate file. ssl-certificate-file STRING; # Specify SSL certificate key file. ssl-key-file FILE; # Specify trusted CAs file. ssl-ca-file FILE; # Set the priorities to use on the ciphers, methods, etc. ssl-priorities STRING; # Set timeout for I/O operations during TLS handshake (seconds). handshake-timeout N; } Description ----------- The 'tls' statement configures TLS parameters to be used by servers. It can appear both in the global scope and in server scope. Global tls settings are applied for servers that are declared as supporting TLS encryption, but lack the 'tls' substatement. -- Configuration: ssl-certificate-file STRING Specify SSL certificate file. -- Configuration: ssl-key-file FILE Specify SSL certificate key file. -- Configuration: ssl-ca-file FILE Specify the trusted certificate authorities file. -- Configuration: ssl-priorities STRING Set the priorities to use on the ciphers, key exchange methods, MACs and compression methods. -- Configuration: handshake-timeout N Set the timeout (in seconds) for I/O operations during TLS handshake. Default value is 10 seconds. 3.2.21 The 'tls-file-checks' Statement -------------------------------------- Syntax ------ tls-file-checks { # Configure safety checks for SSL key file. key-file LIST; # Configure safety checks for SSL certificate. cert-file LIST; # Configure safety checks for SSL CA file. ca-file LIST; } Description ----------- This section configures security checks applied to the particular SSL configuration files in order to decide whether it is safe to use them. -- Configuration: key-file LIST Configure safety checks for SSL key file. Elements of the LIST are names of individual checks, optionally prefixed with '+' to enable or '-' to disable the corresponding check. Valid check names are: none Disable all checks. all Enable all checks. gwrfil Forbid group writable files. awrfil Forbid world writable files. grdfil Forbid group readable files. ardfil Forbid world writable files. linkwrdir Forbid symbolic links in group or world writable directories. gwrdir Forbid files in group writable directories. awrdir Forbid files in world writable directories, -- Configuration: cert-file LIST Configure safety checks for SSL certificate. See 'key-file' for a description of LIST. -- Configuration: ca-file LIST Configure safety checks for SSL CA file. See 'key-file' for a description of LIST. 3.2.22 The 'gsasl' Statement ---------------------------- ================================================================== *Editor's note:* This node is to be written. ================================================================== Syntax ------ gsasl { # Name of GSASL password file. cram-passwd FILE; # SASL service name. service STRING; # SASL realm name. realm STRING; # SASL host name. hostname STRING; # Anonymous user name. anonymous-user STRING; } 3.3 Debugging ============= 'Mailutils' debugging output is controlled by a set of levels, each of which can be set independently of others. Each debug level consists of a "category name", which identifies the part of 'Mailutils' for which additional debugging is desired, and a level number, which tells 'Mailutils' how verbose should its output be. Valid debug levels are: error Displays error conditions which are normally not reported, but passed to the caller layers for handling. trace0 through trace9 Ten levels of verbosity, 'trace0' producing less output, 'trace9' producing the maximum amount of output. prot Displays network protocol interaction, where applicable. Implementation and applicability of each level differs between various categories. The full list of categories is available in file 'libmailutils/diag/debcat' in the Mailutils source tree. Most useful categories and levels implemented for them are discussed later in this article. 3.3.1 Level Syntax ------------------ Debug levels can be set either from the command line, by using the '--debug-level' command line option, or from the configuration file, using the '.debug.level' statement. In both cases, the level is specified as a list of individual levels, delimited with semicolons. Each individual level can be specified as: !CATEGORY Disables all levels for the specified CATEGORY. CATEGORY Enables all levels for the specified CATEGORY. CATEGORY.LEVEL For the given CATEGORY, enables all levels from 'error' to LEVEL, inclusive. CATEGORY.=LEVEL Enables only the given LEVEL for this CATEGORY. CATEGORY.!LEVEL Disables all levels from 'error' to LEVEL, inclusive, for this CATEGORY. CATEGORY.!=LEVEL Disables only the given LEVEL in this CATEGORY. CATEGORY.LEVELA-LEVELB Enables all levels in the range from LEVELA to LEVELB, inclusive. CATEGORY.!LEVELA-LEVELB Disables all levels in the range from LEVELA to LEVELB, inclusive. Additionally, a comma-separated list of level specifications is allowed after the dot. For example, the following specification: acl.prot,!=trace9,!trace2 enables in category 'acl' all levels, except 'trace9', 'trace0', 'trace1', and 'trace2'. 3.3.2 BNF --------- The following specification in Backus-Naur form describes formally the Mailutils debug level: ::= | ::= | ";" ::= | "!" | "." ::= | "," ::= | ::= "!" ::= | "=" | "-" ::= "error" | "trace0" | "trace1" | "trace2" | "trace3" | "trace4" | "trace5" | "trace6" | "trace7" | "trace8" | "trace9" | "prot" 3.3.3 Debugging Categories -------------------------- acl This category enables debugging of Access Control Lists. Available levels are: error As usual, displays errors, not directly reported otherwise. trace0 Basic tracing of ACL processing. trace9 Traces the process of matching the ACL conditions. config This category affects configuration parser and/or lexical analyzer. The following levels are supported: trace0 Minimal information about configuration statements. trace2 Trace lexical structure of the configuration files. trace7 Trace execution of the configuration parser. Due to its specific nature, this category cannot be enabled from the configuration file. A special hook is provided to facilitate debugging the configuration parser, namely, a pragmatic comment in form: #debug=DEBUG-LEVEL-LIST causes DEBUG-LEVEL-LIST to be parsed as described above. Thus, to force debugging of the configuration parser, one would add the following line at the very beginning of the configuration file: #debug=config.trace7 mailbox Operations over mailboxes. This module supports the following levels: 'error', 'trace0', 'trace1', and 'prot'. The latter is used by remote mailbox support libraries. auth Enables debugging information about authentication and authorization. This category supports the following levels: 'error', 'trace0', 'trace1', and 'trace2'. In level 'trace0', user data are reported along with the "data source" they were obtained from. The output may look like this: pop3d: source=system, name=gray, passwd=x, uid=120, gid=100, gecos=Sergey Poznyakoff, dir=/home/gray, shell=/bin/bash, mailbox=/var/mail/gray, quota=0, change_uid=1 In the 'trace1' level, additional flow traces are displayed. In the level 'trace2', a detailed flow trace is displayed, which looks like the following: pop3d: Trying generic... pop3d: generic yields 38=Function not implemented pop3d: Trying system... pop3d: system yields 0=Success pop3d: Trying generic... pop3d: generic yields 4135=Authentication failed pop3d: Trying system... pop3d: system yields 0=Success mailer Debugs mailer operations. The following levels are supported: error Displays mild error conditions. trace0 Traces mailer operations in general: displays what part of the message is being sent, etc. trace6 When used together with 'prot', displays security-sensitive information (such as passwords, user keys, etc). in plaintext. By default, such information is replaced with asterisks to reduce the possibility of security compromise. trace7 When used together with 'prot', displays the "payload" information as it is being sent. The "payload" is the actual message contents, i.e. the part of SMTP transaction that goes after the 'DATA' command and which ends with a terminating dot line. Setting this level can generate huge amounts of information. prot For SMTP mailer: outputs transcripts of SMTP sessions. _Note:_ Unless in a very secure environment, it is advised to avoid using level settings such as mailer.prot or mailer (without explicit level part), because the resulting output tends to be extremely copious and reveals sender private and security-sensitive data. If you wish to trace SMTP session flow, use 'mailer.=prot' or at least 'mailer.prot,!trace6'. server This category provides debugging information for Mailutils IP server objects. It supports the 'error' and 'trace0' levels. folder This category controls debugging information shown for operations related to Mailutils folders. remote The remote category is used by 'imap4d' and 'pop3d' servers to request showing additional information in the session transcripts. This category takes effect only when the 'transcript' configuration variable is set. Valid levels are: trace6 Show security-sensitive information (user passwords, etc.) trace7 Show payload information 3.4 'frm' and 'from' -- List Headers from a Mailbox =================================================== ================================================================== *Editor's note:* The information in this node may be obsolete or otherwise inaccurate. This message will disappear, once this node revised. ================================================================== GNU mailutils provides two commands for listing messages in a mailbox. These are 'from' and 'frm'. The behavior of both programs is affected by the following configuration file statements: Statement Reference ------------------------------------------------------------------- debug *Note debug statement::. tls *Note tls statement::. mailbox *Note mailbox statement::. locking *Note locking statement::. 'frm' ----- The 'frm' utility outputs a header information of the selected messages in a mailbox. By default, 'frm' reads user's system mailbox and outputs the contents of 'From' and 'Subject' headers for each message. If a folder is specified in the command line, the program reads that folder rather than the default mailbox. The following command line options alter the behavior of the program: '-d' '--debug' Enable debugging output. '-f STRING' '--field STRING' Display the header named by STRING instead of 'From' 'Subject' pair. '-l' '--to' Include the contents of 'To' header to the output. The output field order is then: 'To' 'From' 'Subject'. '-n' '--number' Prefix each line with corresponding message number. '-Q' '--Quiet' Be very quiet. Nothing is output except error messages. This is useful in shell scripts where only the return status of the program is important. '-q' '--query' Print a message only if there are unread messages in the mailbox. '-S' '--summary' Print a summary line. '-s ATTR' '--status ATTR' Only display headers from messages with the given status. ATTR may be one of the following: 'new', 'read', 'unread'. It is sufficient to specify only first letter of an ATTR. Multiple '-s' options are allowed. '-t' '--align' Tidy mode. In this mode 'frm' tries to preserve the alignment of the output fields. It also enables the use of BIDI algorithm for displaying subject lines that contain text in right-to-left orientation (such as Arabic or Hebrew). 'from' ------ The 'from' utility displays sender and subject of each message in a mailbox. By default, it reads the user's system mailbox. If the program is given a single argument, it is interpreted as a name of the user whose mailbox is to be read. Obviously, permissions are required to access that user's mailbox, so such invocations may be used only by superuser. The option '-f' ('--file') instructs 'from' to read the given mailbox. The full list of options, supported by 'from' follows: '-c' '--count' Prints only a count of messages in the mailbox and exit. '-d' '--debug' Prints additional debugging output. '-s STRING' '--sender=STRING' Prints only mail with 'From:' header containing the supplied string. '-f URL' '--file=URL' Examine mailbox from the given URL. 3.5 'mail' -- Send and Receive Mail =================================== ================================================================== *Editor's note:* The information in this node may be obsolete or otherwise inaccurate. This message will disappear, once this node revised. ================================================================== 'Mail' is an enhanced version of POSIX 'mailx' program. The program operates in two modes: "read" and "send". 'Mail' enters "send" mode when at least one email address was specified in its command line. In this mode the program waits until user finishes composing the message, then attempts to send it to the specified addresses and exits. *Note Composing Mail::, for a detailed description of this behavior. If the command line contained no email addresses, 'mail' switches to reading mode. In this mode it allows the user to read and manipulate the contents of the user system mailbox. Use the '--file' ('-f') option to specify another mailbox name. For more detail, see *note Reading Mail::. In addition to the Mailutils configuration file, 'mail' reads the traditional 'mailrc'-style configuration files. *Note Mail Configuration Files::, for a detailed description of their format. 3.5.1 Invoking 'mail' --------------------- General usage of 'mail' program is: mail [OPTION...] [ADDRESS...] If [ADDRESS...] part is present, 'mail' switches to mail sending mode, otherwise it operates in mail reading mode. 'Mail' understands the following command line options: '-A FILE' '--attach=FILE' Attach FILE to the composed message. The encoding, content type, and content description are controlled by the '--encoding', '--content-type', and '--content-name' options, correspondingly. The option '--attach=-' instructs 'mail' to read the file to be attached from the standard input. Interactive shell is disabled in this case. '--attach-fd=FD' Read attachment body from the file descriptor FD. The descriptor must be open for reading. This option is useful when calling 'mail' from another program. See the options '--encoding', '--content-type', '--content-name', and '--content-filename'. '-a HEADER:VALUE' '--append=HEADER:VALUE' Append the given header to the composed message. '--content-type=TYPE' This options sets the content type to be used by all subsequent '--attach' options. '--content-filename=NAME' Set the 'filename' parameter in the 'Content-Disposition' header for the next '--attach-fd' option. '--content-name=TEXT' Set the 'name' parameter (description) in the 'Content-Type' header for the next '--attach' or '--attach-fd' option. '-E COMMAND' '--exec=COMMAND' Execute COMMAND before opening the mailbox. Any number of '--exec' options can be given. The commands will be executed after sourcing configuration files (*note Mail Configuration Files::), but before opening the mailbox. '-e' '--exist' Return true if the mailbox contains some messages. Return false otherwise. This is useful for writing shell scripts. '--encoding=ENC' Sets content transfer encoding for use by the subsequent '--attach' options. '-F' '--byname' Record outgoing messages in a file named after the first recipient. The name is the login-name portion of the address found first on the 'To:' line in the mail header. '-f' '--file' Operate on the mailbox given by the first non-optional command line argument. If there is no such argument, read messages from the user's 'mbox' file. *Note Reading Mail::, for more details about using this option. '-H' '--headers' Print header summary to stdout and exit. '-i' '--ignore' Ignore interrupts when composing the message. '-M' '--mime' '--no-mime' The '--mime' option instructs 'mail' to compose MIME messages. It is equivalent for '-E 'set mime'', except that it is processed after all other options. The '--no-mime' disables the MIME compose mode, and is a shortcut for '-E 'set nomime'', '-N' '--nosum' Do not display initial header summary. '-n' '--norc' Do not read the system-wide mailrc file. *Note Mail Configuration Files::. '-p' '--print' '--read' Print all mail to standard output. It is equivalent to issuing following commands after starting 'mail -N': print * quit except that 'mail --print' does not change status of the messages. '-q' '--quit' Cause interrupts to terminate program. '-r ADDRESS' '--return-address=ADDRESS' Sets the return email address for outgoing mail. *Note return-address::. '--skip-empty-attachments' '--no-skip-empty-attachments' Don't create attachments that would have zero-size body. This option affects all attachments created by '--attach' and '--attach-fd' options appearing after it in the command line, as well as the body of the original message. To cancel its effect, use the '--no-skip-empty-attachments' option. '-s SUBJ' '--subject=SUBJ' Send a message with a Subject of SUBJ. Valid only in sending mode. '-t' '--to' Read recipients from the message header. Ignore addresses listed in the command line. '-u USER' '--user=USER' Operate on USER's mailbox. This is equivalent to: mail -f/SPOOL_PATH/USER with SPOOL_PATH being the full path to your mailspool directory ('/var/spool/mail' or '/var/mail' on most systems). The program also understands the common mailutils options (*note Common Options::. 3.5.2 Reading Mail ------------------ The 'mail' utility operates on three kinds of mailboxes. The "user system mailbox" is the mailbox where the incoming mail for the user is stored. Its location is system-dependent and is determined using the common mailutils rules (*note mailbox statement::). The "personal mailbox" (or "mbox", for short) is the default location for saving messages that have been read. By default it is '$HOME/mbox' or whatever file specified by the 'MBOX' environment variable. Any other mailboxes are called "secondary mailboxes". When called without arguments, 'mail' opens the system mailbox for the invoking user. The '--file' ('-f') used without arguments instructs 'mail' to operate on the personal mailbox instead. When this option and a single command line argument are used together, 'mail' treats the argument as the pathname of the secondary mailbox to operate upon. Notice that this argument is not an argument to the '--file' ('-f') option itself, but rather the first non-optional argument on the command line. This means that any number of additional options are allowed between the '--file' option and the mailbox file name. For example, the following three invocations are equivalent: $ mail -fin mymbox $ mail -f mymbox -in $ mail --file -in mymbox $ mail --file -i mymbox -n Additionally, for conformance to the GNU standards, the following form is also accepted: $ mail --file=mymbox -i -n The '--user' ('-u') option allows the system administrator to assume another user identity for operating on this user's mailboxes. Obviously, it is available only to system administrators. For example: mail --user=tom reads mail from the system mailbox of the user 'tom', and mail --user=tom --file reads mail from the personal mailbox of this user. Unless you have started mail with '--norc' command line option, it will read the contents of the system-wide configuration file. Then it will read the contents of user configuration file, if it exists. For detailed description of these files, see *note Mail Configuration Files::. After this initial setup, 'mail' displays the first page of header lines (unless the '-N' option has been given), followed by a prompt, indicating that it is waiting for regular commands. Upon receiving a command, 'mail' parses and executes it, displays the result on the screen, prints the prompt and waits for the next command. This process is continued until 'mail' receives any of the commands 'quit', 'exit' or the end-of-file character (ASCII 4, or 'C-D'). Each message in the mailbox has a state that affects how it is retained or deleted upon closing the mailbox when terminating the program (*note the quit command::) or when switching to another mailbox (*note the file command::). The state is reflected in the header listing and can be changed during the session. The states are: "new" The message is present in the system mailbox and has not been read by the user or moved to any other state. When 'mail' terminates, messages in this state are retained in the system mailbox. If the mailbox is closed, such messages are moved to the 'unread' state. "unread" The message has been present in the system mailbox for more than one invocation of 'mail' and has not been read by the user or moved to any other state. When 'mail' terminates, messages in this state are retained in the system mailbox. "read" The message has been read by the user, i.e. processed by one of the following commands: 'copy', 'mbox', 'next', 'pipe', 'prev', 'print', 'Print', 'struct', 'top', 'type', 'Type', 'undelete', or any of the following escapes (in message compose mode): '~f', '~m', '~F', '~M'. When 'mail' terminates, messages in this state are handled depending on the mailbox they are in. If 'mail' was operating on the user system mailbox, all messages in state 'read' are preserved. The location where they are preserved is determined by the 'hold' variable (*note Mail Variables::). If it is not set (the default), the messages are moved to the user's 'mbox'. If 'hold' is set, the messages are held in the system mailbox instead. The 'read' messages in any other mailbox will be retained in their current location. "deleted" The message has been processed by one of the following commands: 'delete', 'dp', 'dt'. Messages in this state are ignored by any command, excepting 'undelete', which changes their state back to 'read'. When closing the mailbox, deleted messages are permanently removed from the mailbox. "preserved" The message has been processed by the 'preserve' ('hold') command. When closing the mailbox, such messages are retained in the mailbox. "saved" The message has been processed by one of the following commands: 'save', 'write'. When 'mail' terminates, messages in this state are handled depending on the mailbox they are in. If 'mail' was operating on the user system mailbox, the default behavior for 'saved' messages is to remove them from the system mailbox. If, however, the 'keepsave' variable is set, they are preserved using the same rules as for 'read' messages (see above). Saved messages in non-system mailboxes are retained in their current location. Unless the mailbox is empty, exactly one of its messages will be marked as "current message". Upon startup, current message is set to the first new message, if there is any, or the first unread message if there is any, or to the first message in the mailbox. In the header listing, current message is marked with the '>' sign at the beginning of the line. Current message is changed by any of the following commands: 'dp', 'prev', 'next'. 3.5.2.1 Syntax of mail internal commands ........................................ Commands have the following syntax: COMMAND [MSGLIST] [ARGUMENT ...] A command is terminated by a newline character. Empty command (i.e. a newline character alone) is equivalent to 'next' (*note next: Moving Within a Mailbox.). In the syntax above, COMMAND is the command verb. Each command has long and short (abbreviated) form. Each of them can be used to invoke the command. Many mail commands take a list of messages (MSGLIST) to operate upon, which defaults to current message. The list of messages in its simplest form is one of: . Selects current message. It is equivalent to empty message list. * Selects all messages in the mailbox. ^ Selects first non-deleted message. $ Selects last non-deleted message. In its complex form, the "message list" is a comma or whitespace-separated list of "message specifiers". A "message specifier" is one of N (integer number) This specifier addresses the message with the given ordinal number in the mailbox. N-M All messages with ordinal numbers between N and M, inclusive. :T All messages of type T, where T can be any of: 'd' Deleted messages. 'n' New messages. 'o' Old messages (any message not in state 'read' or 'new'). 'r' Messages in state 'read'. 'u' Messages in state 'unread'. 't' Selects all tagged messages. 'T' Selects all untagged messages. 's' Selects all messages in state 'saved'. [HEADER:]/STRING[/] Header match. Selects all messages that contain header field HEADER matching given STRING. If the variable 'regex' is set, the STRING is assumed to be a POSIX regexp. (All comparison is case-insensitive in either case). If HEADER: part is omitted, it is assumed to be 'Subject:'. :/STRING[/] Message body match. Selects all messages with body matching the STRING. The matching rules are the same as described above. A "message specifier" can be followed by "message part specifier", enclosed in a pair of brackets. A "message part specifier" controls which part of a message should be operated upon. It is meaningful only for multipart messages. A "message part specifier" is a comma or whitespace-separated list of part numbers or ranges. Each part number can in turn be "message part specifier", thus allowing for operating upon multiply-encoded messages. The following are the examples of valid message lists: 3 Third message. 1-4 10 Messages from 1 through 4 and message 10. 4-* All messages starting from message 4. /watch All messages with the word 'watch' in the subject. /watch :/watch All messages with the word 'watch' in the subject or body. /watch :/watch $ Same as above plus the last message in the mailbox. 10[2] Part 2 of the multipart message 10. 3.5.2.2 Quitting the Program ............................ Following commands quit the program: -- Mail command: quit Terminates the session. The messages, marked with 'delete' are removed. The messages in state 'read' and 'saved' are processed depending on the mailbox they are in. If 'mail' was operating on the user system mailbox, all messages in state 'read' are preserved. The location where they are preserved is determined by the 'hold' variable. If it is not set (the default), the messages are moved to the user's 'mbox'. If 'hold' is set, the messages are held in the system mailbox instead. The default behavior for 'saved' messages is to remove them from the system mailbox. If, however, the 'keepsave' variable is set, they are preserved using the same rules as for 'read' messages. For non-system mailboxes, both 'read' and 'saved' messages are retained in their current location. The same rules are followed when the mailbox is switched using the 'file' command. The program exits to the shell, unless saving the mailbox fails, in which case user can escape with the exit command. -- Mail command: exit -- Mail command: ex -- Mail command: xit Program exits to the shell without modifying the mailbox it operates upon. Typing EOF ('C-D') alone is equivalent to 'quit'. 3.5.2.3 Obtaining Online Help ............................. Following commands can be used during the session to request online help: -- Mail command: help [COMMAND] -- Mail command: hel [COMMAND] -- Mail command: ? [COMMAND] Display detailed command synopsis. If no COMMAND is given, help for all available commands is displayed. -- Mail command: list -- Mail command: * Print a list of available commands. -- Mail command: version -- Mail command: ve Display program version. -- Mail command: warranty -- Mail command: wa Display program warranty statement. 3.5.2.4 Moving Within a Mailbox ............................... -- Mail command: ^ Move to the first undeleted message. -- Mail command: $ Move to the last undeleted message. -- Mail command: next -- Mail command: n Move to the next message. -- Mail command: previous -- Mail command: prev Move to the previous message. 3.5.2.5 Changing Mailbox/Directory .................................. -- Mail command: cd [DIR] -- Mail command: chdir [DIR] -- Mail command: ch [DIR] Change to the specified directory. If DIR is omitted, '$HOME' is assumed. -- Mail command: file [MAILBOX] -- Mail command: fi [MAILBOX] -- Mail command: folder [MAILBOX] -- Mail command: fold [MAILBOX] When used without argument, prints the information about the current mailbox: the mailbox file name (or URL), total number of messages and the number of unread messages, e.g.: ? fold "/var/spool/mail/gray": 23 messages 22 unread Otherwise, closes the current mailbox and opens the mailbox named by the MAILBOX argument. When closing the current mailbox, its messages are processed according to their state (*note mail message states::). The MAILBOX argument can be the name of the existing file, a mailbox URL (*note Mailbox::), or any of the following shortcuts: % The system mailbox for the invoking user. %USER The system mailbox for USER. # The previous file. & The user's personal mailbox. @ Secondary mailbox, given using the '-f' command line option. +FILE The named FILE in the folder directory. *Note folder variable::. 3.5.2.6 Controlling Header Display .................................. To control which headers in the message should be displayed, 'mail' keeps two lists: a "retained" header list and an "ignored" header list. If "retained" header list is not empty, only the header fields listed in it are displayed when printing the message. Otherwise, if "ignored" header list is not empty, only the headers _not listed_ in this list are displayed. The uppercase variants of message-displaying commands can be used to print all the headers. The following commands modify and display the contents of both lists. -- Mail command: discard [HEADER-FIELD-LIST] -- Mail command: di [HEADER-FIELD-LIST] -- Mail command: ignore [HEADER-FIELD-LIST] -- Mail command: ig [HEADER-FIELD-LIST] Add HEADER-FIELD-LIST to the ignored list. When used without arguments, this command prints the contents of ignored list. -- Mail command: retain [HEADER-FIELD-LIST] -- Mail command: ret [HEADER-FIELD-LIST] Add HEADER-FIELD-LIST to the retained list. When used without arguments, this command prints the contents of retained list. 3.5.2.7 Displaying Information .............................. -- Mail command: = Displays the current message number. -- Mail command: headers [MSGLIST] -- Mail command: h [MSGLIST] Lists the current pageful of headers. -- Mail command: from [MSGLIST] -- Mail command: f [MSGLIST] Lists the contents of 'From' headers for a given set of messages. -- Mail command: z [ARG] Presents message headers in pagefuls as described for 'headers' command. When ARG is '.', it is generally equivalent to 'headers'. When ARG is omitted or is '+', the next pageful of headers is displayed. If ARG is '-', the previous pageful of headers is displayed. The latter two forms of 'z' command may also take a numerical argument meaning the number of pages to skip before displaying the headers. For example: ? z +2 will skip two pages of messages before displaying the header summary. -- Mail command: size [MSGLIST] -- Mail command: si [MSGLIST] Lists the message number and message size in bytes for each message in MSGLIST. -- Mail command: folders Displays the value of 'folder' variable. -- Mail command: summary -- Mail command: su Displays current mailbox summary. E.g.: ? summary "/var/spool/mail/gray": 23 messages 22 unread 3.5.2.8 Displaying Messages ........................... -- Mail command: print [MSGLIST] -- Mail command: p [MSGLIST] -- Mail command: type [MSGLIST] -- Mail command: t [MSGLIST] Prints out the messages from MSGLIST. The variable 'crt' determines the minimum number of lines the body of the message must contain in order to be piped through pager command specified by environment variable 'PAGER'. If 'crt' is set to a numeric value, this value is taken as the minimum number of lines. Otherwise, if 'crt' is set without a value then the height of the terminal screen is used to compute the threshold. The number of lines on screen is controlled by 'screen' variable. -- Mail command: Print [MSGLIST] -- Mail command: P [MSGLIST] -- Mail command: Type [MSGLIST] -- Mail command: T [MSGLIST] Like print but also prints out ignored header fields. -- Mail command: decode [MSGLIST] -- Mail command: dec [MSGLIST] Print a multipart message. The 'decode' command decodes and prints out specified message parts. E.g. ? decode 15[2] +--------------------------------------- | Message=15[2] | Type=message/delivery-status | encoding=7bit +--------------------------------------- Content-Type: message/delivery-status ... -- Mail command: top [MSGLIST] -- Mail command: to [MSGLIST] Prints the top few lines of each message in MSGLIST. The number of lines printed is controlled by the variable 'toplines' and defaults to five. -- Mail command: pipe [[MSGLIST] SHELL-COMMAND] -- Mail command: | [[MSGLIST] SHELL-COMMAND] Pipe the contents of specified messages through SHELL-COMMAND. Without arguments, pipe the current message through the command given by the 'cmd' variable (which must be set). -- Mail command: struct [MSGLIST] Prints the MIME structure of each message from MSGLIST. Empty MSGLIST means current message. Example: ? struct 2 2 multipart/mixed 14k 2[1] text/plain 296 2[2] application/octet-stream 5k 2[3] text/x-diff 31k 3.5.2.9 Marking Messages ........................ -- Mail command: tag [MSGLIST] -- Mail command: ta [MSGLIST] Tag messages. The tagged messages can be referred to in message list using ':t' notation. -- Mail command: untag [MSGLIST] -- Mail command: unt [MSGLIST] Clear tags from specified messages. To untag all messages tagged so far type ? untag :t -- Mail command: hold [MSGLIST] -- Mail command: ho [MSGLIST] -- Mail command: preserve [MSGLIST] -- Mail command: pre [MSGLIST] Marks each message to be held in user's system mailbox. This command does not override the effect of 'delete' command. -- Mail command: unread [MSGLIST] Marks each message from the MSGLIST as not having been read. 3.5.2.10 Disposing of Messages .............................. -- Mail command: delete [MSGLIST] -- Mail command: d [MSGLIST] Mark messages as deleted. Upon exiting with 'quit' command these messages will be deleted from the mailbox. Until the end of current session the deleted messages can be referred to in message lists using :d notation. -- Mail command: undelete [MSGLIST] -- Mail command: u [MSGLIST] Clear delete mark from the specified messages. -- Mail command: dp [MSGLIST] -- Mail command: dt [MSGLIST] Deletes the current message and prints the next message. If MSGLIST is specified, deletes all messages from the list and prints the message immediately following last deleted one. 3.5.2.11 Saving Messages ........................ -- Mail command: save [[MSGLIST] MAILBOX] -- Mail command: s [[MSGLIST] MAILBOX] Takes a message list and a file or mailbox name and appends each message in turn to that file or mailbox. The syntax for MAILBOX is the same as for the 'file' command (*note Mailbox shortcuts::). The name of the mailbox and number of lines and characters appended to it is echoed on the terminal. When writing to file, the numbers represent exact number of lines and characters appended to the file. When FILE specifies a mailbox, these numbers may differ by the amount of lines/characters needed to represent message envelope for that specific mailbox type. Each saved message is marked for deletion as if with 'delete' command, unless the variable 'keepsave' is set. -- Mail command: Save [MSGLIST] -- Mail command: S [MSGLIST] Like 'save', but the file to append messages to is named after the sender of the first message in MSGLIST. The file name is selected as described in *note saving mail by name::. For example: ? from 14 15 U 14 smith@noldor.org Fri Jun 30 18:11 14/358 The Save c U 15 gray@noldor.org Fri Jun 30 18:30 8/245 Re: The Sa ? Save 14 15 "smith" 22/603 i.e., 22 lines (603 characters) have been appended to the file "smith". If the file does not exist, it is created. -- Mail command: write [[MSGLIST] FILE] -- Mail command: w [[MSGLIST] FILE] Similar to 'save', except that only message body (without the header) is saved. -- Mail command: Write [MSGLIST] -- Mail command: W [MSGLIST] Similar to 'Save', except that only message body (without the header) is saved. -- Mail command: mbox [MSGLIST] -- Mail command: mb [MSGLIST] Mark list of messages to be saved in the user's personal mailbox (*note personal mailbox: Reading Mail.) upon exiting via 'quit' command. This is the default action for all read messages, unless you have variable 'hold' set. -- Mail command: touch [MSGLIST] -- Mail command: tou [MSGLIST] Touch the specified messages. If any message in MSGLIST is not specifically deleted nor saved in a file, upon normal termination it will be acted upon as if it had been read (*note mail message states::). -- Mail command: copy [[MSGLIST] FILE] -- Mail command: c [[MSGLIST] FILE] Similar to 'save', except that saved messages are not marked as saved. -- Mail command: Copy [MSGLIST] -- Mail command: C [MSGLIST] Similar to 'Save', except that saved messages are not marked as saved. 3.5.2.12 Editing Messages ......................... These command allow to edit messages in a mailbox. _Please note_, that modified messages currently do not replace original ones. i.e. you have to save them explicitly using your editor's 'save' command if you do not want the effects of your editing to be lost. -- Mail command: edit [MSGLIST] -- Mail command: e [MSGLIST] Edits each message in MSGLIST with the editor, specified in 'EDITOR' environment variable. -- Mail command: visual [MSGLIST] -- Mail command: v [MSGLIST] Edits each message in MSGLIST with the editor, specified in 'VISUAL' environment variable. 3.5.2.13 Aliasing ................. -- Mail command: alias [alias [ADDRESS...]] -- Mail command: a [alias [ADDRESS...]] -- Mail command: group [alias [ADDRESS...]] -- Mail command: g [alias [ADDRESS...]] With no arguments, prints out all currently-defined aliases. With one argument, prints out that alias. With more than one argument, creates a new alias or changes an old one. -- Mail command: unalias [ALIAS...] -- Mail command: una [ALIAS...] Takes a list of names defined by alias commands and discards the remembered groups of users. The alias names no longer have any significance. -- Mail command: alternates NAME... -- Mail command: alt NAME... The alternates command is useful if you have accounts on several machines. It can be used to inform mail that the listed addresses are really you. When you reply to messages, mail will not send a copy of the message to any of the addresses listed on the alternates list. If the alternates command is given with no argument, the current set of alternate names is displayed. 3.5.2.14 Replying ................. -- Mail command: mail [ADDRESS...] -- Mail command: m [ADDRESS...] Switches to compose mode. After composing the message, sends it to the specified addresses. If the 'record' variable is set, the composed message will be saved in the folder named by it. -- Mail command: Mail [ADDRESS...] -- Mail command: M [ADDRESS...] Same as 'mail', but the name of the file to save the composed message is derived from its first recipient as outlined below. If the 'outfolder' variable is set, and has a string value S, the filename is 'S/RECIPIENT'. If it is a boolean, then the 'folder' variable is consulted. If it is set, then the filename is 'FOLDER/RECIPIENT'. Otherwise, the message will not be saved. The value RECIPIENT is derived from the email of the first recipient of the message. By default it is a local part of that email. If the 'outfilename' variable has the value 'domain', the domain part of the email is used. If this variable is set to 'email', then entire email address is used. *Note saving mail by name::, for a detailed discussion. -- Mail command: reply [MESSAGE] -- Mail command: respond [MESSAGE] -- Mail command: r [MESSAGE] Mail a reply message to all recipients included in the header of the MESSAGE. The subject header is formed by concatenating the value of the 'replyprefix' variable and the subject from the message. If 'record' is set to a filename, the response is saved at the end of that file. -- Mail command: Reply [MSGLIST] -- Mail command: Respond [MSGLIST] -- Mail command: R [MSGLIST] Mail a reply message to the sender of each message in the MSGLIST. The subject header is formed by concatenating the value of the 'replyprefix' variable and the subject header of from the first message in MSGLIST. If 'record' is set to a filename, the response is saved at the end of that file. Notice, that setting mail variable 'flipr' (*note Mail Variables::) swaps the meanings of the two above commands -- Mail command: followup [MESSAGE] -- Mail command: fo [MESSAGE] Respond to MESSAGE, recording the response in a file whose name is derived from the author of the message. *Note saving mail by name::, for a discussion of how the file name is selected. -- Mail command: Followup [MSGLIST] -- Mail command: F [MSGLIST] Same as 'Reply', but the response is saved in a file whose name is derived from the author of the first message. *Note saving mail by name::, for a detailed discussion of how the file name is selected. By default, 'mail' will preserve personal email parts when forming lists of recipient addresses. If this is not desired, unset the 'fullnames' variable (*note fullnames::). To determine the sender of the message 'mail' uses the list of sender fields (*note Controlling Sender Fields::). The first field from this list is looked up in message headers. If it is found and contains a valid email address, this address is used as the sender address. If not, the second field is searched and so on. This process continues until a field is found in the headers, or the sender field list is exhausted, whichever happens first. If the previous step did not determine the sender address, the address from SMTP envelope is used. Let's illustrate this. Suppose your mailbox contains the following: U 1 block@helsingor.org Fri Jun 30 18:30 8/245 Re: The Sa ? Print 1 From: Antonius Block To: Smeden Plog Date: Tue, 27 Apr 2004 13:23:41 +0300 Reply-To: Subject: News Hi Now, you issue the following commands: ? sender mail-followup-to reply-to from ? reply To: Subject: Re: News As you see, the value of 'Reply-To' field was taken as the sender address. Now, let's try the following command sequence: # Clear the sender list ? nosender # Set new sender list ? sender From Now, the 'From' address will be taken: ? reply To: Antonius Block Subject: Re: News 3.5.2.15 Controlling Sender Fields .................................. When 'mail' needs to know the sender of a message, it looks it up in one or more headers of that message. Such headers constitute a "sender list". The first header from the list that is present in the message and has a non-empty value is used. If none is found or if the sender list is empty, the value of the message envelope is used. The commands 'sender' and 'nosender' manipulate the sender list. If the command 'sender' is used without arguments, it displays the contents of the sender field list. If arguments are given, each argument is appended to the sender field list. For example: ? sender Sender address is obtained from the envelope ? sender mail-followup-to reply-to ? sender mail-followup-to reply-to ? sender from ? sender mail-followup-to reply-to from Command 'nosender' is used to remove items from the sender field list: ? sender mail-followup-to reply-to from ? nosender reply-to ? sender mail-followup-to from When used without arguments, this command clears the list: ? nosender Sender address is obtained from the envelope 3.5.2.16 Incorporating New Mail ............................... The 'incorporate' ('inc') command incorporates newly arrived messages to the displayed list of messages. This is done automatically before returning to 'mail' command prompt if the variable 'autoinc' is set. 3.5.2.17 Shell Escapes ...................... To run arbitrary shell command from 'mail' command prompt, use 'shell' ('sh') command. If no arguments are specified, the command starts the user login shell. Otherwise, it uses its first argument as a file name to execute and all subsequent arguments are passed as positional parameters to this command. The 'shell' command can also be spelled as '!'. 3.5.3 Saving and Recording -------------------------- Several commands discussed in the previous section save messages in a disk file. The name of that file is either obtained from the 'record' variable ("recording mail") or is derived from the first recipient of the message ("saving by name"). The following commands record mails: * 'mail' * 'reply' * 'Reply' The following commands save mail by name: * 'Copy' * 'Save' * 'Mail' * 'followup' * 'Followup' Saving mail by name is controlled by three mail variables: 'outfolder', 'folder', and 'outfilename'. The first, 'outfolder', is a boolean variable which, when set, enables saving mail by name. The 'folder' variable defines a directory where mail files are stored. Name of file in that directory where the message will be saved is derived from the message recipient(1). This process is controlled by the 'outfilename' variable: if its value is 'local', the file is named by the local part of the email (this is the default). If it is 'domain', the domain part is used instead. Finally, if it's value is 'email', the entire email is used. As a GNU extension, 'outfolder' can be a string variable. In that case its value names the directory to use instead of 'folder'. The 'mailx' variable, if set, disables GNU extensions. In this case, 'outfolder' is used as a boolean value, and file names are derived from the local part of the email, ignoring the 'outfilename' value. ---------- Footnotes ---------- (1) In case of 'Copy' and 'Save', message sender is used instead 3.5.4 Composing Mail -------------------- You can compose the message by simply typing the contents of it, line by line. But usually this is not enough, you would need to edit your text, to quote some messages, etc. 'Mail' provides these capabilities through "compose escapes". The "compose escapes" are single-character commands, preceded by special "escape character", which defaults to '~'. The combination 'escape character + command' is recognized as a compose escape only if it occurs at the beginning of a line and the standard input is connected to a terminal. If the escape character must appear at the beginning of a line, enter it twice. The actual escape character may be changed by setting the value of 'escape' mail variable (*note Mail Variables::). 3.5.4.1 Quitting Compose Mode ............................. There are several commands allowing you to quit the compose mode. Typing the end-of-file character ('C-D') on a line alone finishes compose mode and sends the message to its destination. The 'C-D' character looses its special meaning if 'ignoreeof' mail variable is set. If mail variable 'dot' is set, typing dot ('.') on a line alone achieves the same effect as 'C-D' above. Finally, using '~.' escape always quits compose mode and sends out the composed message. To abort composing of a message without sending it, type interrupt character (by default, 'C-C') twice. This behavior is disabled when mail variable 'ignore' is set. In this case, you can use '~x' escape to achieve the same effect. 3.5.4.2 Getting Help on Compose Escapes: ~? ........................................... The '~?' escape prints on screen a brief summary of the available compose escapes. _Please note_, that '~h' escape prompts for changing the header values, and does _not_ give help. 3.5.4.3 Editing the Message: ~e and ~v ...................................... If you are not satisfied with the message as it is, you can edit it using a text editor specified either by 'EDITOR' or by 'VISUAL' environment variables. The '~e' uses the former, and '~v' uses the latter. By default both escapes allow you to edit only the body of the message. However, if the 'editheaders' variable is set, 'mail' will load into the editor the complete text of the message with headers included, thus allowing you to change the headers as well. 3.5.4.4 Modifying the Headers: ~h, ~t, ~c, ~b, ~s ................................................. To add new addresses to the list of message recipients, use '~t' command, e.g.: ~t name1@domain.net name2 To add addresses to 'Cc' or 'Bcc', use '~c' or '~b' escapes respectively. To change the 'Subject' header, use '~s' escape, e.g.: ~s "Re: your message" Finally, to edit all headers, type '~h' escape. This will present you with the values of 'To', 'Cc', 'Bcc', and 'Subject' headers allowing to edit them with normal text editing commands. 3.5.4.5 Enclosing Another Message: ~m and ~M ............................................ If you are sending mail from within mail command mode, you can enclose the contents of any message sent to you by using '~m' or '~M' commands. Typing '~m' alone will enclose the contents of the current message, typing '~m 12' will enclose the contents of message #12 and so on. The '~m' uses retained and ignored lists when enclosing headers, the '~M' encloses all header fields. In both cases, the contents of 'indentprefix' mail variable is prepended to each line enclosed. 3.5.4.6 Adding a File to the Message: ~r and ~d ............................................... To append the contents of file FILENAME to the message, type ~r FILENAME or ~< FILENAME The '~d' escape is a shorthand for ~r dead.letter 3.5.4.7 Attaching a File to the Message ....................................... The '~+' escape attaches a file to the message. It takes one to three arguments. The first argument supplies the name of the file to attach: ~+ myfile.txt The file will be attached with default content-type 'application/octet-stream', and encoding 'base64' (these can be altered by the '--content-type' and '--encoding' command line options, correspondingly). Optional second argument defines the content type to be used instead of the default one. Optional third argument defines the encoding, e.g.: ~+ myfile.html text/html base64 To list the files attached so far, use the '~l' escape: ~l multipart/mixed 1 myfile.html text/html base64 The first line of the output shows the content type of the message. Each subsequent line contains the ordinal number of the attachment, the name of the file, content-type and transfer encoding used. The '~/' escape toggles the content type bewteen 'multipart/mixed', and 'multipart/alternative'. The new value of the content type is displayed on the screen. The '~^' escape removes attachments. Its argument is the number of the attachment to remove, e.g.: ~^ 1 3.5.4.8 Printing And Saving the Message ....................................... The '~p' escape types the contents of the message entered so far, including headers, on your terminal. You can save the message to an arbitrary file using '~w' escape. It takes the filename as its argument. 3.5.4.9 Signing the Message: ~a and ~A ...................................... To save you the effort of typing your signature at the end of each message, you can use '~a' or '~A' escapes. If your signature occupies one line only, save it to the variable 'sign' and use '~a' escape to insert it. Otherwise, if it is longer than one line, save it to a file, store the name of this file in the variable 'Sign', and use '~A' escape to insert it into the message. 3.5.4.10 Printing Another Message: ~f and ~F ............................................ Sometimes it is necessary to view the contents of another message, while composing. These two escapes allow it. Both take the message list as their argument. If they are used without argument, the contents of the current message is printed. The difference between '~f' and '~F' is that the former uses ignored and retained lists to select headers to be displayed, whereas the latter prints all headers. 3.5.4.11 Inserting Value of a Mail Variable: ~i ............................................... The '~i' escape enters the value of the named mail variable into the body of the message being composed. 3.5.4.12 Executing Other Mail Commands: ~: and ~- ................................................. You can execute a mail command from within compose mode using '~:' or '~-' escapes. For example, typing ~: from :t will display the from lines of all tagged messages. Note, that executing mail-sending commands from within the compose mode is not allowed. An attempt to execute such a command will result in diagnostic message "Command not allowed in an escape sequence" being displayed. Also, when starting compose mode immediately from the shell (e.g. running 'mail address@domain'), most mail commands are meaningless, since there is no mailbox to operate upon. In this case, the only commands that can reasonably be used are: 'alias', 'unalias', 'alternate', 'set', and 'unset'. 3.5.4.13 Executing Shell Commands: ~! and ~| ............................................ The '~!' escape executes specified command and returns you to 'mail' compose mode without altering your message. When used without arguments, it starts your login shell. The '~|' escape pipes the message composed so far through the given shell command and replaces the message with the output the command produced. If the command produced no output, 'mail' assumes that something went wrong and retains the old contents of your message. 3.5.5 Composing Multipart Messages ---------------------------------- Multipart messages (or MIME, for short) can be used to send text in character sets other than ASCII, attach non-text files, send multiple parts in alternative formats, etc. Technically speaking, the boolean variable 'mime' controls this feature. If it is set (*note Setting and Unsetting the Variables::), 'MIME' will create MIME messages by default. The variable can be set in the global or user configuration file (*note Mail Configuration Files::), using the following command: set mime It can also be set from the command line, using the '--mime' option. GNU 'mail' automatically turns on the MIME mode, when it is requested to send a non-plaintext message, or a message in character set other than ASCII, when the encoding is specified, or when attachments are given. To send a message in another character set, specify it with the '--content-type' option: mail --content-type 'text/plain; charset=utf-8' The '--encoding' specifies the encoding to use: mail --content-type 'text/plain; charset=utf-8' --encoding=base64 Its argument is any encoding supported by GNU mailutils. The two most often used encodings are 'base64' and 'quoted-printable'. To specify the charset from 'mail' interactive section, enable the "edit headers" mode ('set editheaders') and add the needed 'Content-Type' header manually. GNU 'mail' also gives you a possibility to attach files to the message being sent. The simplest way to attach a file from command line is by using the '--attach' ('-A') option. Its argument specifies the file to attach. For example, the following will attach the content of the file 'archive.tar': $ mail --attach=archive.tar By default, the content type will be set to 'application/octet-stream', and the attachment will be encoded using the 'base64' encoding. To change the content type, use the '--content-type' option. For example, to send an HTML attachment: $ mail --content-type=text/html --attach=in.html The '--content-type' option affects all '--attach' options that follow it, and the message body (if any). To change the content type, simply add another '--content-type' option. For example, to send both the HTML file and the archive: $ mail --content-type=text/html --attach=in.html \ --content-type=application/x-tar --attach=archive.tar To change the content type of the message body when sending a message with attachments, use the trailing '--content-type' option, i.e. the option not followed by another '--attach' option: $ mail --content-type=text/html --attach=in.html \ --content-type=application/x-tar --attach=archive.tar \ --content-type=text/plain This example adds two attachments with different content types and switched back to the 'text/plain' content type for the message body. The encoding to use is set up by the '--encoding' option. As well as '--content-type', this option affects all attachments supplied after it in the command line as well as the message body read from the standard input, until changed by the eventual next instance of the same option. Extending the above example: $ mail --content-type=text/html --encoding=quoted-printable \ --attach=in.html \ --content-type=application/x-tar --encoding=base64 \ --attach=archive.tar A trailing '--encoding' option sets the encoding of the message body. Each attachment can also be assigned a "description" and a "file name". Normally, these are the same as the file name supplied with the '--attach' option. However, you can change either or both of them using the '--content-name' and '--content-filename', correspondingly. Both of these options affect only the next '--attach' (or '--attach-fd', see below) option. By default, the message will be assigned the content type 'multipart/mixed'. To change it to 'multipart/alternative', use the '--alternative' command line option. Using this option also sets the 'Content-Disposition' header of each attached message to 'inline'. All the examples above will enter the usual interactive shell, allowing you to compose the body of the message. If that's not needed, the non-interactive use can be forced by redirecting '/dev/null' to the standard input, e.g.: $ mail --attach=archive.tar < /dev/null This will normally produce a message saying: mail: Null message body; hope that's ok To suppress this message, unset the 'nullbodymsg' variable, as shown in the example below: $ mail -E 'set nonullbodymsg' --attach=archive.tar < /dev/null The option '--attach=-' forces 'mail' to read the file to be attached from the standard input stream. This option disables the interactive mode and sets 'nonullbodymsg' implicitly, so that the above example can be rewritten as: $ mail --attach=- < archive.tar Special option is provided to facilitate the use of 'mail' in scripts. The '--attach-fd=N' instructs the program to read the data to be attached from the file descriptor N. The above example is equivalent to: $ mail --attach-fd=0 < archive.tar Attachments created with this option have neither filename nor description set, so normally the use of '--content-name' and/or '--content-filename' is advised. The option '--skip-empty-attachments' instructs 'mail' to skip creating attachments that would have zero-size body. This option affects all attachments created by '--attach' and '--attach-fd' options appearing after it in the command line. It also affects the handling of the original message body. To cancel its effect, use the '--no-skip-empty-attachments' option. Here are some examples illustrating how it works. First, consider the following command line $ mail --attach=archive.tar ) { chomp; if (/^\S+ on (?.+) type (?.+) /) { For each mountpoint, the 'find' command line is constructed and launched. The file descriptor is pushed to the '@fds' array to prevent it from being collected by the garbage collector: open(my $fd, '-|', "find $+{mpoint} -xdev -type f" . " \\( -perm -u+x -o -perm -g+x -o -perm -o+x \\)" . " \\( -perm -u+s -o -perm -g+s \\) -print"); push @fds, $fd; Now, the 'mail' command is instructed to create next attachment from that file descriptor: my $mpname = $+{mpoint}; $mpname =~ tr{/}{%}; push @cmd, "--content-name=Set[ug]id files on $+{mpoint} (type $+{fstype})", "--content-filename=$mpname.list", '--attach-fd=' . fileno($fd); } } close $in; Finally, the emails of the recipients are added to the command line, the standard input is closed to make sure 'mail' won't enter the interactive mode and the constructed command is executed: push @cmd, @rcpt; close STDIN; system(@cmd); 3.5.6 Scripting --------------- Comments ........ The '#' character introduces an end-of-line comment. All characters until and including the end of line are ignored. Displaying Arbitrary Text ......................... The 'echo' ('ec') command prints its arguments to stdout. Sourcing External Command Files ............................... The command 'source FILENAME' reads commands from the named file. Its minimal abbreviation is 'so'. Setting and Unsetting the Variables ................................... The mail variables are set using 'set' ('se') command. The command takes a list of assignments. The syntax of an assignment is 'NAME=STRING' Assign a string value to the variable. If STRING contains whitespace characters it must be enclosed in a pair of double-quote characters ('"') 'NAME=NUMBER' Assign a numeric value to the variable. 'NAME' Assign boolean 'True' value. 'noNAME' Assign boolean 'False' value. Example: ? set askcc nocrt indentprefix="> " This statement sets 'askcc' to 'True', 'crt' to 'False', and 'indentprefix' to "> ". To unset mail variables use 'unset'('uns') command. The command takes a list of variable names to unset. To undo the effect of the previous example, do: ? unset askcc crt indentprefix When used without arguments, both 'set' or 'unset' list all currently defined variables. The form of this listing is controlled by 'variable-pretty-print' ('varpp') variable. If it is set, a description precedes each variable, e.g.: # prompt user for subject before composing the message ask # prompt user for cc before composing the message askcc # output character set for decoded header fields charset="auto" # number of columns on terminal screen columns=80 If 'variable-pretty-print' is not set, only the settings are shown, e.g.: ask askcc charset="auto" columns=80 A special command is provided to list all internal 'mail' variables: variable [NAMES...] If used without arguments, it prints all known internal variables. If arguments are given, it displays only those internal variables that are listed in command line. For each variable, this command prints its name, data type, current value and a short description. For example: ? variable ask datefield ask, asksub Type: boolean Current value: yes prompt user for subject before composing the message datefield Type: boolean Current value: [not set] get date from the `Date:' header, instead of the envelope Setting and Unsetting Shell Environment Variables ................................................. Shell environment may be modified using 'setenv' ('sete') command. The command takes a list of assignments. The syntax of an assignment is: 'NAME=VALUE' If variable NAME does not already exist in the environment, then it is added to the environment with the value VALUE. If NAME does exist, then its value in the environment is changed to VALUE. 'NAME' Delete the variable NAME from the environment ("unset" it). Conditional Statements ...................... The conditional statement allows to execute a set of mail commands depending on the mode the 'mail' program is in. The conditional statement is: if COND ... else ... endif where '...' represents the set of commands to be executed in each branch of the statement. COND can be one of the following: 's' True if 'mail' is operating in mail sending mode. 'r' True if 'mail' is operating in mail reading mode. 't' True if stdout is a terminal device (as opposed to a regular file). The conditional statements can be nested to arbitrary depth. The minimal abbreviations for 'if', 'else' and 'endif' commands are 'i', 'el' and 'en'. Example: if t set crt prompt="& " else unset prompt endif if s alt gray@example.com gray@example.org set 3.5.7 How to Alter the Behavior of 'mail' ----------------------------------------- Following variables control the behavior of GNU 'mail': -- mail: boolean append Default: True Comment: Read-Only Messages saved in 'mbox' are appended to the end, rather than prepended. This is the default and cannot be changed. This variable exists only for compatibility with other 'mailx' implementations. -- mail: boolean appenddeadletter Default: False If this variable is set, the contents of canceled letter is appended to the user's 'dead.letter' file. Otherwise it overwrites its contents. -- mail: boolean askbcc Default: False When set to 'True' the user will be prompted to enter 'Bcc' field before composing the message. -- mail: boolean askcc Default: True When set to 'True' the user will be prompted to enter 'Cc' field before composing the message. -- mail: boolean asksub Default: True in interactive mode, False otherwise. When set to 'True' the user will be prompted to enter 'Subject' field before composing the message. -- mail: boolean autoinc Default: True Automatically incorporate newly arrived messages. -- mail: boolean autoprint Default: False Causes the delete command to behave like 'dp': after deleting a message, the next one will be typed automatically. -- mail: boolean bang Default: False When set, every occurrence of '!' in arguments to '!' escape is replaced with the last executed command. *Note Executing Shell Commands::, for details on the '!' escape. -- mail: boolean datefield Default: False By default the date in a header summary is taken from the SMTP envelope of the message. Setting this variable tells 'mail' to use the date from 'Date:' header field, converted to local time. Notice, that for messages lacking this field 'mail' will fall back to using SMTP envelope. *Note fromfield::. -- mail: string charset Default: 'auto' The value of this variable is the character set used for input and output operations. If the value is 'auto', 'mail' will try to deduce the name of the character set from the value of 'LC_ALL' environment variable. If the variable contains the character set part (e.g. 'nb_NO.utf-8'), it will be used. Otherwise, 'mail' will look up in its built-in database the value of the character for this language/territory combination. If 'LC_ALL' is not set, the 'LANG' environment variable is inspected. The value of 'charset' controls both input and output operations. On input, it is used to set the value of the 'charset' parameter in the 'Content-Type' MIME header, if its value begins with 'text/' and the 'charset' parameter is not present. On output, it is used to display values of the header fields encodied using RFC 2047. If the variable is unset, no decoding is performed and the fields are printed as they are. Otherwise, they are recoded to that character set. -- mail: string cmd Default: Unset Contains default shell command for 'pipe'. -- mail: numeric columns Default: Detected at startup by querying the terminal device. If this fails, the value of environment variable 'COLUMNS' is used. This variable contains the number of columns on terminal screen. -- mail: numeric crt -- mail: boolean crt Default: True in interactive mode, False otherwise. The variable 'crt' determines the minimum number of lines the body of the message must contain in order to be piped through pager command specified by environment variable 'PAGER'. If 'crt' is set to a numeric value, this value is taken as the threshold. Otherwise, if 'crt' is set without a value, then the height of the terminal screen is used to compute the threshold. The number of lines on screen is controlled by 'screen' variable. -- mail: boolean debug -- mail: string debug Default: Unset Sets mailutils debug level. If set to string, the value must be a valid Mailutils debugging specification. *Note Debug Statement::, for a description. If unset (i.e. 'set nodebug'), clears and disables all debugging information. If set to 'true' (i.e. 'set debug'), sets maximum debugging ('%a%4m %18f %16d %3l/%-5o %s' Format string to use for the header summary. The '%' character introduces a "format specifier". The format specifier consists of optional alignment specifier ('+' or '-' sign), optional output width and the specifier letter. Format specifiers are replaced on output with the corresponding piece of information from the message being described. The '-' character immediately following '%' indicates that this field should be left aligned. The '+' character indicates right alignment. Default alignment depends on the type of the specifier: the specifiers that produce numeric values ('%l', '%m', and '%o') are aligned to the right, whereas the ones producing string or date/time values are aligned to the left. A number following '%' or the alignment flag, indicates the field width. Consider the '%m' specifier as an example: %m Print current message number. Take as much screen columns as necessary for output. %4m %+4m Print current message number. Use exactly 4 screen columns, truncating the output if it does not fit that width. Align the output to the right. %-4m Same as above, but align to the left. Valid format specifiers are: %a Message attribute. One of the following letters, or a single horizontal space, if none of them applies: 'M' the message was copied to the mailbox ('mbox' command) 'P' the message was preserved ('hold' command) '*' the message was saved ('save' or 'Save') 'T' the message was tagged ('tag') 'R' the message was read 'N' the message is new (was not seen) 'U' the message was seen, but wasn't read %d The date when the message was received. It is determined from the message header defined by the 'datefield' variable (*note datefield::). If that variable is not set, or the requested header is not present in the message, the date from the envelope is used. The output is formatted according to the following format specification (*note Date/time Format String::): %a %b %e %H:%M I.e.: abbreviated weekday name, abbreviated month name, day of the month as a decimal number, followed by hour and minutes. All names are displayed according to the current locale. %D{FMT} Same as '%d', but the date is formatted according to the date/time format FMT. It is essentially a C 'strftime' format string, described in detail in *note Date/time Format String::. For example: set headline="%4m %20D{%Y-%m-%dT%H:%M:%S}" Note, that the opening '{' must follow the format letter without any intervening whitespace. If FMT contains '{', '}', or '\', these characters must be escaped with backslash (e.g. '\{'). %DF A simplified form of the '%D' specifier. It is equivalent to %D{%F} where F is a single 'strftime' specifier letter. It can be preceded by 'E' or 'O', if the Single UNIX Specification allows such usage (*note conversion specs::), e.g. '%DOU'. Notice, that '%D' not followed by a valid time format in either of the above forms is treated as unknown specifier. %f The email address of the message sender. %l The number of lines of the message. %m Message number. %o The number of octets (bytes) in the message. %s Message subject (if any). %S Message subject (if any) in double quotes. %> A '>' for the current message, otherwise a space. %< A '<' for the current message, otherwise a space. %% A '%' character. -- mail: boolean hold Default: False Determines the location where to store the messages in state 'read' and (if the 'keepsave' is also set) 'saved'. When set, these messages will be retained in the system mailbox. When not set (the default), such messages will be stored in the user's personal mailbox. *Note read messages::, and *Note saved messages::, for a detailed information on how such messages are processed when the mailbox is being closed. *Note keepsave::, for the discussion of the 'keepsave' variable. -- mail: boolean ignore Default: False When set to 'True', 'mail' will ignore keyboard interrupts when composing messages. Otherwise an interrupt will be taken as a signal to abort composing. -- mail: boolean ignoreeof Default: False Controls whether typing EOF character terminates the letter being composed. -- mail: string indentprefix Default: "\t" (a tab character). String used by the '~m' tilde escape for indenting quoted messages. -- mail: boolean inplacealiases Default: False If set, 'mail' will expand aliases in the address header field before entering send mode (*note Composing Mail::). By default, the address header fields are left intact while composing, the alias expansion takes place immediately before sending message. -- mail: boolean keep Comment: Read-Only Default: True Truncate the user's system mailbox when it is empty, instead of removing it. This is the default and cannot be changed. This variable exists only for compatibility with other 'mailx' implementations. -- mail: boolean keepsave Default: False Controls whether saved messages should be retained. The location where they will be retained is controlled by the 'hold' variable (*note the hold variable::). This variable is in effect only when operating upon the user's system mailbox. *Note saved messages::, for a detailed information on how the saved messages are processed when the mailbox is being closed. -- mail: boolean mailx Default: False When set, enables "mailx compatibility mode". This mode has the following effects: * When composing a message 'mail' will ask for 'Cc' and 'Bcc' addresses after composing the body. The default behavior is to ask for these values before composing the body. * In send mode, if the composition was interrupted, 'mail' will exit with zero status. By default it exits with zero status only if the message was sent successfully. * The 'outfolder' variable is treated as boolean. *note outfolder::. * The value of 'outfilename' is ignored (assumed to be 'local'). *note outfilename::. * The values of 'folder' and 'record' variables are assumed relative to the home directory, unless they begin with '/', '~', or '+'. * If the value of the 'sendmail' variable does not begin with a scheme specification, 'sendmail:/' is assumed. *Note sendmail mail variable::. -- mail: boolean metamail -- mail: string metamail Default: True This variable controls operation of 'decode' command. If it is unset, 'decode' will not attempt any interpretation of the content of message parts. Otherwise, if 'metamail' is set to 'true', 'decode' will use internal metamail support to interpret message parts. Finally, if 'metamail' is assigned a string, this string is treated as command line of the external 'metamail' command which will be used to display parts of a multipart message. For example: # Disable MIME interpretation: set nometamail # Enable built-in MIME support: set metamail # Use external program to display MIME parts: set metamail="metamail -m mail -p" -- mail: string mime Default: False If set, this variable instructs 'mail' to compose MIME messages. It can be set from the command line using '--mime' option. -- mail: string mimenoask Default: Unset By default 'mail' asks for confirmation before running interpreter to view a part of the multi-part message. If this variable is set, its value is treated as a comma-separated list of MIME types for which no confirmation is needed. Elements of this list may include shell-style globbing patterns, e.g. setting set mimenoask=text/*,image/jpeg will disable prompting before displaying any textual files, no matter what their subtype is, and before displaying files with type 'image/jpeg'. -- mail: boolean metoo Default: False Usually, when an alias is expanded that contains the sender, the sender is removed from the expansion. Setting this option causes the sender to be included in the group. -- mail: string mode Comment: Read-Only Default: The name of current operation mode. This variable keeps the name of the current operation mode. Its possible values are: headers The program is started with the '--headers' ('-H') command line option (*note Invoking Mail::). exist The program is started with the '--exist' ('-e') command line option (*note Invoking Mail::). print The program is started with the '--print' ('-p') command line option (*note Invoking Mail::). read The program operates in read mode. This is the default. send The program operates in send mode. This means it was given one or more recipient addresses in the command line. -- mail: boolean nullbody Default: True Controls whether 'mail' accepts messages with an empty body. The default value, 'true', means such messages are sent, and a warning (traditionally saying 'Null message body; hope that's ok') is displayed. The text of the warning can be set using 'nullbodymsg' variable (see below). If 'nullbody' is unset, 'mail' will silently ignore such messages. This can be useful in 'crontab' files, to avoid sending mails when nothing important happens. For example, the 'crontab' entry below will send mail only if the utility 'some-prog' outputs something on its standard output or error: */5 * * * * some-prog 2>&1 | \ /bin/mail -E'set nonullbody' -s 'Periodic synchronization' -- mail: string nullbodymsg Default: 'Null message body; hope that's ok' Text of the warning displayed by 'mail' before sending an empty message. When available, the translation of this text, in accordance with the current locale, is displayed. Unsetting this variable disables the warning. -- mail: boolean onehop Default: Unset This variable is not used. It exists for compatibility with other 'mailx' implementations and for future use. -- mail: string outfilename Comment: Three-state: 'local', 'email', 'domain'. Default: 'local' Defines the algorithm to convert the recipient email to the name of the file used to record outgoing messages to that recipient. This affects the following commands: 'Copy', 'Save', 'Mail', 'followup', and 'Followup'. The following values are allowed: 'local' Local part of the email address is taken as the file name. This is the default. 'email' Entire email is takes as the file name. 'domain' Domain part of the email is used as the file name. -- mail: boolean outfolder -- mail: string outfolder Default: Unset When set as boolean, causes the files used to record outgoing messages to be located in the directory specified by the 'folder' variable (unless the pathname is absolute). If set to a string value, names the directory where to store these files. This variable affects the following commands: 'Copy', 'Save', 'Mail', 'followup', and 'Followup'. In mailx compatibility mode, only boolean value is allowed. *note mailx mail variable::. -- mail: boolean page Default: Unset If set, the 'pipe' command will emit a linefeed character after printing each message. -- mail: string PID Comment: Read-Only Default: PID of the process. PID of the current 'mail' process. -- mail: string prompt Default: "? " Contains the command prompt sequence. -- mail: boolean quiet Default: Unset This variable is not used. It exists for compatibility with other 'mailx' implementations and for future use. -- mail: boolean quit Default: False, unless started with '--quit' ('-q') option. When set, causes keyboard interrupts to terminate the program. -- mail: boolean rc Default: True, unless started with '--norc' ('-N') option. When this variable is set, 'mail' will read the system-wide configuration file upon startup. *Note Mail Configuration Files::. -- mail: boolean readonly Default: False When set, mailboxes are opened in readonly mode. In this mode, any 'mail' commands that alter the contents of the mailbox are disabled. These commands include, but are not limited to: 'delete', 'save' and 'mbox'. -- mail: string record Default: Unset When set, outgoing messages produced by the following commmands will be saved to the named file: 'mail', 'reply', 'Reply'. See also *note outfolder:: and *note outfilename::. -- mail: boolean recursivealiases Default: True When set, 'mail' will expand aliases recursively. -- mail: boolean regex Default: True. If set, enables the use of regular expressions in '/.../' message specifications. -- mail: string replyprefix Default: 'Re: ' Sets the prefix that will be used when constructing the subject line of a reply message. -- mail: string replyregex Default: '^re: *' Sets the regular expression used to recognize subjects of reply messages. If the 'Subject' header of the message matches this expression, the value of 'replyprefix' will not be prepended to it before replying. The value should be a POSIX extended regular expression. The comparison is case-insensitive. For example, to recognize usual English, Polish, Norwegian and German reply subject styles, use: set replyregex="^(re|odp|aw|ang)(\\[[0-9]+\\])?:[[:blank:]]" (Notice the quoting of backslash characters). -- mail: string return-address Default: unset Sets the return email address to use when sending messages. If unset, return address is composed from the current user name and the host name. -- mail: boolean save Default: True. When set, the aborted messages will be stored in the user's 'dead.file'. See also 'appenddeadletter'. -- mail: numeric screen Default: Detected at startup by querying the terminal device. If this fails, the value of environment variable 'LINES' is used. This variable contains the number of lines on terminal screen. See also *note crt::. -- mail: string sendmail Default: 'sendmail:/usr/lib/sendmail' Contains URL of the mail transport agent. If the value begins with a scheme specifier, it must be one of the mailer URL schemes supported by mailutils (*note mailer URL::). Otherwise, if not in mailx compatibility mode, the value starting with directory separator ('/') is treated as the external command that will be started as is and the composed message will be piped to its standard input. In mailx compatibility mode (*note mailx mail variable::), the 'sendmail:' prefix is assumed. -- mail: boolean sendwait Default: Unset This variable is not used. It exists for compatibility with other 'mailx' implementations and for future use. -- mail: string Sign Default: Unset Contains the filename holding users signature. The contents of this file is appended to the end of a message being composed by '~A' escape. -- mail: string sign Default: Unset Contains the user's signature. The contents of this variable is appended to the end of a message being composed by '~a' escape. Use 'Sign' variable, if your signature occupies more than one line. -- mail: boolean showenvelope Default: Unset If this variable is set, the 'print' command will include the SMTP envelope in its output. -- mail: boolean showto Default: Unset If this variable is set, 'mail' will show 'To:' addresses instead of 'From:' for all messages that come from the user that invoked the program. -- mail: string subject Default: Unset Contains default subject line. This will be used when 'asksub' is off. -- mail: numeric toplines Default: 5 Number of lines to be displayed by 'top' and 'Top' commands. -- mail: boolean variable-pretty-print -- mail: boolean varpp Default: False If this variable is set, the listing output by 'set' contains short descriptions before each variable. *Note Setting and Unsetting the Variables::. -- mail: boolean variable-strict -- mail: boolean varstrict Default: False Setting this variable enables strict control over variable settings. In this mode, 'mail' refuses to set read-only variables. Also, if the user is trying to set an unknown variable, 'mail' prints a warning. *Note Setting and Unsetting the Variables::. -- mail: boolean verbose Default: False When set, the actual delivery of messages is displayed on the user's terminal. -- mail: boolean useragent Default: True Controls whether the 'User-Agent' header should be added to outgoing messages. The default value of this header is User-Agent: mail (GNU Mailutils 3.14) -- mail: boolean xmailer This header is retained for compatibility with previous releases of GNU Mailutils. Since version 3.13 it is an alias for 'useragent'. 3.5.8 Personal and System-wide Configuration Files -------------------------------------------------- After processing the usual Mailutils configuration files (*note configuration::), 'mail' reads the contents of the two command files: the system-wide command file, and the user's command file. Each line read from these files is processed like a usual 'mail' command. When run with '--norc' ('-N') option, 'mail' does not read the contents of system-wide configuration file. The user's file, if it exists, is always processed. The user's configuration file is located in the user's home directory and is named '.mailrc'. The location and name of the system-wide configuration file is determined when configuring the package via '--with-mail-rc' option. It defaults to 'SYSCONFDIR/mail.rc'. 3.6 'messages' -- Count the Number of Messages in a Mailbox =========================================================== 'Messages' prints on standard output the number of messages contained in each folder specified in command line. If no folders are specified, it operates upon user's system mailbox. For each folder, the following output line is produced: Number of messages in FOLDER: NUMBER where FOLDER represents the folder name, NUMBER represents the number of messages. The following configuration file statements affect the behaviour of 'messages': Statement Reference ------------------------------------------------------------------- debug *Note debug statement::. tls *Note tls statement::. mailbox *Note mailbox statement::. locking *Note locking statement::. In addition to the common mailutils options (*note Common Options::), the program accepts the following command line options: '-q' '--quiet' '-s' '--silent' Be quiet. Display only number of messages per mailbox, without leading text. 3.7 'movemail' -- Moves Mail from the User Maildrop to the Local File ===================================================================== The purpose of 'movemail', as its name implies, is to move mail from one location to another. For example, the following invocation: movemail /var/mail/smith INBOX moves messages from file '/var/mail/smith' to file 'INBOX'. The program was initially intended as a replacement for 'movemail' from GNU Emacs. The 'movemail' program is run by Emacs 'Rmail' module. *Note (emacs)Rmail::, for detailed description of 'Rmail' interface. Mailutils version of 'movemail' is fully backward-compatible with its Emacs predecessor, so it should run flawlessly with older versions of Emacs. Emacs versions starting from 22.1 contain improved 'Rmail' interface and are able to take advantage of all new features mailutils 'movemail' provides. Apart from that use, 'movemail' proved to be a useful tool for incorporating mail from remote mailboxes into the local one. See Fetching Mail with Movemail (http://mailutils.org/wiki/Fetching_Mail_with_Movemail), for a detailed discussion with usage recipes. 3.7.1 Movemail Configuration ---------------------------- The following configuration file statements affect the behavior of 'movemail': -- Movemail Config: preserve BOOL If BOOL is 'true', do not remove messages from the source mailbox. -- Movemail Config: reverse BOOL If BOOL is 'true', reverse message sorting order. -- Movemail Config: emacs BOOL If BOOL is 'true', output information used by Emacs rmail interface. -- Movemail Config: ignore-errors BOOL Continue moving messages after errors. By default, 'mailfromd' exits immediately if it cannot copy a message. -- Movemail Config: program-id FMT Set program identifier, i.e. a string which will prefix all diagnostic messages issued by the program. By default, program name is used. The FMT is a format string that may contain references to the following variables (*note Variables::): 'progname' The program name. 'source' URL of the source mailbox. 'source_user' User part of the source mailbox URL. 'source_host' Host part of the source mailbox URL. 'source_path' Path part of the source mailbox URL. 'dest' URL of the destination mailbox 'dest_user' User part of the destination mailbox URL. 'dest_host' Host part of the destination mailbox URL. 'dest_path' Path part of the destination mailbox URL. Setting 'program-id' may be necessary if several 'movemail' instances are run simultaneously (e.g. invoked from a script) to discern between the instances. For example: program-id "${progname}: ${source} => ${dest}" -- Movemail Config: uidl BOOL Avoid copying the message if a message with the same UIDL already exists in the destination mailbox. -- Movemail Config: verbose LEVEL Set verbosity level. -- Movemail Config: mailbox-ownership METHOD-LIST Define list of methods for setting ownership of the destination mailbox. The METHOD-LIST argument can contain the following elements: copy-id Copy owner UID and GID from the source mailbox. This method works only with local mailboxes, i.e.: 'mbox' (UNIX mailbox), 'maildir' and 'mh'. copy-name Get owner name from the source mailbox URL and obtain UID and GID for this user using mailutils authorization methods. set-id=UID[:GID] Set supplied UID and GID. If GID is not supplied, it is read from the '/etc/passwd' record for this UID. set-name=USER Make destination mailbox owned by USER. -- Movemail Config: max-messages COUNT Defines upper limit on the number of moved messages. Movemail will stop after transferring COUNT messages. By default, the number of messages is not limited. -- Movemail Config: onerror ACTIONS Defines what to do if an error occurs when transferring a message. ACTIONS is a list of one or more of the following keywords: abort Abort the transfer and terminate the program. This is the default action. skip Skip to the next message. delete Delete the affected message. count Count this message as processed. Each keyword can be prefixed with 'no' to reverse its meaning. The following standard Mailutils statements are supported: Statement Reference ------------------------------------------------------------------- debug *Note debug statement::. tls *Note tls statement::. mailbox *Note mailbox statement::. locking *Note locking statement::. pam *Note pam statement::. sql *Note sql statement::. virtdomain *Note virtdomain statement::. radius *Note radius statement::. ldap *Note ldap statement::. auth *Note auth statement::. 3.7.2 Setting Destination Mailbox Ownership ------------------------------------------- ================================================================== *Editor's note:* The information in this node may be obsolete or otherwise inaccurate. This message will disappear, once this node revised. ================================================================== 3.7.3 Movemail Usage Summary ---------------------------- movemail [OPTION...] INBOX DESTFILE [PASSWORD] The first argument, INBOX, is the url (*note Mailbox::) of the source mailbox. The second argument, DESTFILE, traditionally means destination file, i.e. the UNIX mailbox to copy messages to. However, mailutils 'movemail' extends the meaning of this parameter. You may actually specify any valid url as DESTFILE parameter.(1). For compatibility with older implementations of 'movemail', the SOURCE argument can also have the form: po:USERNAME[:POP-SERVER] where POP-SERVER is the IP address or hostname of a POP3 server to connect to and USERNAME is the name of the user on that server. The password is then supplied by the third argument. It is equivalent to the following URL: pop://USERNAME[:PASSWORD]@POP-SERVER In fact, whenever SOURCE refers to a remote mailbox, the PASSWORD argument can be used to pass the password. However, the safer "ticket" method is of course preferred. Options are one or more of the following: '--emacs' Output information used by Emacs 'rmail' interface. '--ignore-errors' Try to continue after errors. '--max-messages=COUNT' Process at most COUNT messages. '--notify' Enable biff notification. '--onerror=KW[,KW...]' What to do on errors. *Note onerror statement: movemail-onerror, for a description of KW. '-P MODELIST' '--owner=MODELIST' Control mailbox ownership. MODELIST is a comma-separated list of one or more ownership change methods. *Note mailbox-ownership-methods::, for a description of available methods. This option is useful only when running 'movemail' as root. '-p' '--preserve' '--keep-messages' Don't remove transferred messages from the source mailbox. '--program-id=FMT' Set program identifier for diagnostics (default: the program name). *Note movemail-program-id::, for a description of its argument. '-r' '--reverse' Reverse the order of retrieved messages. '-u' '--uidl' Use UIDLs to avoid downloading the same message twice. '-v' '--verbose' Increase verbosity level. The common options are also understood (*note Common Options::). ---------- Footnotes ---------- (1) Rmail does not use this feature 3.8 'readmsg' -- Extract Messages from a Folder =============================================== The 'readmsg' utility extracts messages from a mailbox according to the criteria specified in the command line. These criteria are: 1. A lone '*' means "select all messages in the mailbox". 2. A list of message numbers may be specified. Values of '0' and '$' in the list both mean the last message in the mailbox. For example: readmsg 1 3 0 extracts three messages from the folder: the first, the third, and the last. 3. Finally, the selection may be some text to match. This will select a mail message which exactly matches the specified text. For example, readmsg staff meeting extracts the message which contains the words 'staff meeting'. Note that it will not match a message containing 'Staff Meeting' - the matching is case sensitive by default. This can changed using the '-i' ('--ignorecase') option. Two more options are provided to control the matching algorithm: the '-g' ('--glob') option instructs 'readmsg' to treat arguments as shell globbing patterns and the '-r' ('--regex') option instructs it to treat them as POSIX extended regular expressions. Needless to say, when using any of the two latter options, you should pay attention to escape the matching pattern to prevent it from being interpreted by the shell. E.g.: readmsg --regex 'staff.*meeting' Unless requested otherwise, only the first message that matches the pattern is printed. At least one command line argument or one informational option must be present in 'readmsg' invocation. Informational options are: '--help' ('-?'), '--usage', and '--version' ('-V'). 3.8.1 Invocation of 'readmsg'. ------------------------------ '-a' '--show-all' If a pattern is used for selection, show all messages that match pattern by default only the first one is presented. '-d' '--debug' Display mailbox debugging information. '-e' '--exact' Look for messages containing exactly the words given as arguments. This is the default. Other options changing this behavior are: '--glob', '--regex', and '--ignorecase'. '-f MAILBOX' '--folder=MAILBOX' Specified the default mailbox. '-g' '--glob' Treat non-option arguments as shell globbing patterns. For example, to select the first message with words 'morning' and 'coffee' with anything bewteen them: readmsg --glob 'morning*coffee' (notice quoting, which prevents the shell from interpreting the '*' prematurely). '-h' '--header' Show the entire header and ignore the weedlist. '-i' '--ignorecase' Ignore the case of letters when looking for matching messages. E.g.: readmsg --glob --ignorecase 'morning*coffee' '-n' '--no-header' Do not print the message header. '-p' '--form-feed' Put form-feed (Control-L) between messages instead of newline. '-r' '--regex' Treat non-option arguments as POSIX extended regular expressions. '-w WEEDLIST' '--weedlist=WEEDLIST' A whitespace or coma separated list of header names to show per message. Default is '--weedlist="From Subject Date To CC Apparently-"'. See also *note Common Options::. 3.8.2 Configuration of 'readmsg'. --------------------------------- Following configuration statements affect the behavior of 'readmsg': -- Readmsg Conf: header BOOL If BOOL is 'true', display entire headers. -- Readmsg Conf: weedlist STR Set the weedlist. The STR argument is a string, containing a list of header names, separated by whitespace, commands or colons. This corresponds to the '--weedlist' command line option (*note -weedlist: Opt-readmsg.). -- Readmsg Conf: no-header BOOL If BOOL is 'true', exclude all headers. -- Readmsg Conf: form-feeds BOOL If BOOL is 'true', output formfeed character between messages. -- Readmsg Conf: folder URL Set the URL of the mailbox folder to read. -- Readmsg Conf: show-all-match BOOL If BOOL is 'true', print all messages matching pattern, not only the first. Statement Reference ------------------------------------------------------------------- debug *Note Debug Statement::. tls *Note TLS Statement::. mailbox *Note Mailbox Statement::. locking *Note Locking Statement::. 3.9 'decodemail' - Decode multipart messages ============================================ The 'decodemail' utility is a filter program that reads messages from the input mailbox, decodes "textual" parts of each multipart message from a base64- or quoted-printable encoding to an 8-bit or 7-bit transfer encoding, and stores the processed messages in the output mailbox. All messages from the input mailbox are stored in the output, regardless of whether a change was made. The message parts deemed to be textual are those whose 'Content-Type' header matches a predefined, or user-defined, mime type pattern. In addition, encoded pieces of the 'From:', 'To:', 'Subject:', etc., headers are decoded. For example, 'decodemail' makes this transformation: Subject: =?utf-8?Q?The=20Baroque=20Enquirer=20|=20July=202020?= => Subject: The Baroque Enquirer | July 2020 The built-in list of textual content type patterns is: text/* application/*shell application/shellscript */x-csrc */x-csource */x-diff */x-patch */x-perl */x-php */x-python */x-sh These strings are matched as shell globbing patterns (*note (glob(7))glob::). More patterns can be added to this list using the 'mime.text-type' configuration statement. *Note mime statement::, for a detailed discussion, and the configuration section below for a simple example. When processing old mesages you may encounter 'Content-Type' headers whose value contains only type, but no subtype. To match such headers, use the pattern without '/whatever' part. E.g. 'text/*' matches 'text/plain' and 'text/html', but does not match 'text'. On the other hand, 't*xt' does not match 'text/plain', but does match 'text'. Optionally, the decoded parts can be converted to another character set. By default, the character set is not changed. 3.9.1 Invocation of 'decodemail'. --------------------------------- Usually, the utility is invoked as: decodemail INBOX OUTBOX where INBOX and OUTBOX are file names or URLs of the input and output mailboxes, correspondingly. The input mailbox is opened read-only and will not be modified in any way. In particular, the status of the processed messages will not change. If the output mailbox does not exist, it will be created. If it exists, the messages will be appended to it, preserving any original messages that are already in it. This behavior can be changed using the '-t' ('--truncate') option, described below. The two mailboxes can be of different types. For example you can read input from an imap server and store it in local 'maildir' box using the following command: decodemail imap://user@example.com maildir:///var/mail/user Both arguments can be omitted. If OUTBOX is not supplied, the resulting mailbox will be printed on the standard output in Unix 'mbox' format. If INBOX is not supplied, the utility will open the system inbox for the current user and use it for input. A consequence of these rules is that there is no simple way to read the input mailbox from standard input (the input must be seekable). If you need to do this, the normal procedure would be to save what would be standard input in a temporary file and then give that file as 'decodemail''s input. The following command line options modify the 'decodemail' behavior: '-c, --charset=CHARSET' Convert all textual parts from their original character set to the specified CHARSET. '-R, --recode' Convert all textual parts from their original character set to the current character set, as specified by the 'LC_ALL' or 'LANG' environment variable. '--no-recode' Do not convert character sets. This is the default. '-t, --truncate' If the output mailbox exists, truncate it before appending new messages. '--no-truncate' Keep the existing messages in the output mailbox intact. This is the default. Additionally, the *note Common Options:: are also understood. 3.9.2 Configuration of 'decodemail'. ------------------------------------ The following common configuration statements affect the behavior of 'decodemail': Statement Reference ------------------------------------------------------------------- mime *Note mime statement::. debug *Note Debug Statement::. mailbox *Note Mailbox Statement::. locking *Note Locking Statement::. Notably, the 'mime' statement can be used to extend the list of types which are decoded. For example, in the file '~/.decodemail' (other locations are possible, *note configuration::), you could have: # base64/qp decode these mime types also: mime { text-type "application/x-bibtex"; text-type "application/x-tex"; } Since the list of textual mime types is open-ended, with new types being used at any time, we do not attempt to make the built-in list comprehensive. 3.9.3 Purpose and caveats of 'decodemail'. ------------------------------------------ The principal use envisioned for this program is to decode messages in batch, after they are received. Unfortunately, some mailers prefer to encode messages in their entirety in base64 (or quoted-printable), even when the content is entirely human-readable text. This makes straightforward use of 'grep' or other standard commands impossible. The idea is for 'decodemail' to rectify that, by making the message text readable again. Besides personal mail, mailing list archives are another place where such decoding can be useful, as they are often searched with standard tools. It is generally not recommended to run 'decodemail' within a mail reader (which should be able to do the decoding itself), or directly in a terminal (since quite possibly there will be 8-bit output not in the current character set). Although the output message from 'decodemail' should be entirely equivalent to the input message, apart from the decoding, it is generally not identical. Because 'decodemail' parses the input message and reconstructs it for output, there are usually small differences: * In the envelope 'From ' line, multiple spaces are collapsed to one. * A 'Content-Transfer-Encoding:' header may be added where not previously present, or its value changed from '8bit' to '7bit', or vice versa. This may happen both for the message as a whole, and for a given mime part. 'decodemail' looks at the actual content of the text and outputs 'Content-Transfer-Encoding:' accordingly. * A trailing space is inserted when a long header line is broken to occupy several lines ("header wrapping"). SomeHeader: someextremelylongvaluethatcannotbebroken * The non-tracing headers may be reordered, notably those that are mime-related. * Any material before the first mime part of a mime multipart message is lost. By the standards, nothing should appear there. Typically if it does appear, it is a string such as 'This is a multi-part message in MIME format.'. * In mime parts, the charset specifications may no longer be quoted (if quoting is not necessary). For example, 'charset="utf-8"' becomes 'charset=utf-8'. * The mime boundary strings will be changed. If a discrepancy is created which actually affects message parsing or reading, that's most likely a bug, and please report it. Naturally, please send an exact input message to reproduce the problem. 3.10 'sieve' ============ ================================================================== *Editor's note:* The information in this node may be obsolete or otherwise inaccurate. This message will disappear, once this node revised. ================================================================== Sieve is a language for filtering e-mail messages at time of final delivery, described in RFC 3028. GNU Mailutils contains stand-alone "sieve interpreter", which is described in detail below. 3.10.1 A Sieve Interpreter -------------------------- The sieve interpreter 'sieve' allows you to apply Sieve scripts to arbitrary number of mailboxes. GNU 'sieve' implements a superset of the Sieve language as described in RFC 3028. *Note Sieve Language::, for a description of the Sieve language. *Note GNU Extensions::, for a discussion of differences between the GNU implementation of Sieve and its standard. 3.10.1.1 Invoking 'sieve' ......................... The 'sieve' invocation syntax is: sieve [OPTIONS] SCRIPT Normally, SCRIPT is the name of the disk file with the Sieve script. If SCRIPT is a single dash, the script is read from the standard input. If the '-E' ('--expression') option is given, SCRIPT is taken to be the sieve script text. where SCRIPT denotes the filename of the sieve program to parse, and OPTIONS is one or more of the following: '-c' '--compile-only' Compile script and exit. '--clear-library-path' '--clearpath' Clear Sieve library path. See also *note clear-library-path: Sieve Configuration. '--clear-include-path' Clear Sieve include path. See also *note clear-include-path: Sieve Configuration. '-d[FLAGS]' '--debug[=FLAGS]' Specify debug flags. The FLAGS argument is a sequence of one or more of the following letters: 'g' Enable main parser traces 'T' Enable mailutils traces 'P' Trace network protocols 't' Enable sieve trace 'i' Trace the program instructions '-D' '--dump' Compile the script, dump disassembled code on standard output and exit. '--environment=NAME=VALUE' Set sieve environment variable NAME to the VALUE. '-e ADDRESS' '--email ADDRESS' Override the user email address. This is useful for 'reject' and 'redirect' actions. By default, the user email address is deduced from the user name and the full name of the machine where 'sieve' is executed. See also *note email: Sieve Configuration. '-E,' '--expression' Treat the SCRIPT argument as Sieve program text. '-I DIR' '--includedir=DIR' Append directory DIR to the list of directories searched for include files. See also *note include-path: Sieve Configuration. '-f' '--mbox-url=MBOX' Mailbox to sieve (defaults to user's system mailbox). See also *note mbox-url: Sieve Configuration. '-k' '--keep-going' Keep on going if execution fails on a message. See also *note keep-going: Sieve Configuration. '-L DIR' '--libdir=DIR' Append directory DIR to the list of directories searched for library files. See also *note library-path: Sieve Configuration. '--libdir-prefix=DIR' Add DIR to the beginning of the list of directories searched for library files. '--line-info=BOOL' Print source location along with action logs (default). '-M URL' '--mailer=URL' Define the URL of the default mailer. '-n' '--no-actions' '--dry-run' Dry run: do not execute any actions, just print what would be done. '--no-program-name' Do not prefix diagnostic messages with the program name. '-t TICKET' '--ticket=TICKET' Ticket file for mailbox authentication. See also *note ticket: Sieve Configuration. '--variable=NAME=VALUE' Set Sieve variable NAME. This option automatically inserts 'require "variables"' at the top of the script. '-v' '--verbose' Log all actions executed. See also *note verbose: Sieve Configuration. See also *note Common Options::. 3.10.1.2 Sieve Configuration ............................ The behavior of 'sieve' is affected by the following configuration statements: Statement Reference ------------------------------------------------------------------- debug *Note debug statement::. tls *Note tls statement::. mailbox *Note mailbox statement::. locking *Note locking statement::. logging *Note logging statement::. mailer *Note mailer statement::. The following statements configure sieve-specific features: -- Sieve Conf: sieve { ... } This block statement configures search paths 'sieve' uses to locate its loadable modules. *Note Require Statement::, for a detailed information about loadable modules. This statement may contain the following sub-statements: -- Sieve Conf: clear-library-path BOOL If BOOL is 'true', clear library search path. -- Sieve Conf: clear-include-path BOOL If BOOL is 'true', clear include search path. -- Sieve Conf: library-path PATH Add directories to 'sieve' library search path. Argument is a string containing a colon-separated list of directories. -- Sieve Conf: library-path-prefix PATH Add directories to the beginning if the library search path. Argument is a string containing a colon-separated list of directories. -- Sieve Conf: include-path PATH Add directories to the include search path. Argument is a string containing a colon-separated list of directories. -- Sieve Conf: keep-going BOOL If BOOL is 'true', do not abort if execution of a Sieve script fails on a particular message. -- Sieve Conf: mbox-url URL Sets URL of the mailbox to be processed. -- Sieve Conf: ticket FILE Sets the name of the ticket file for user authentication. -- Sieve Conf: debug FLAGS Sets Sieve debug flags. *Note Logging and Debugging::, for a detailed description. -- Sieve Conf: verbose BOOL If BOOL is 'true', log all executed actions. -- Sieve Conf: line-info BOOL If BOOL is 'true', print source locations along with action logs. This statement takes effect only if 'verbose true' is also set. -- Sieve Conf: email ADDR Set user e-mail address. This is useful for 'reject' and 'redirect' actions. By default, the user email address is deduced from the user name and the full name of the machine where 'sieve' is executed. 3.10.1.3 Logging and debugging .............................. The default behavior of 'sieve' is to remain silent about anything except errors. However, it is sometimes necessary to see which actions are executed and on which messages. This is particularly useful when debugging the sieve scripts. The '--verbose' ('-v') option outputs log of every action executed. Option '--debug' allows to produce even more detailed debugging information. This option takes an argument specifying the debugging level to be enabled. The argument can consist of the following letters: 't' This flag enables sieve tracing. It means that every test will be logged when executed. 'T' This flag enables debugging of underlying 'mailutils' library. 'P' Trace network protocols: produces log of network transactions executed while running the script. 'g' Enable main parser traces. This is useful for debugging the sieve grammar. 'i' Trace the program instructions. It is the most extensive debugging level. It produces the full execution log of a sieve program, showing each instruction and states of the sieve machine. It is only useful for debugging the code generator. _Note_, that there should be no whitespace between the short variant of the option ('-d'), and its argument. Similarly, when using long option ('--debug'), its argument must be preceded by equal sign. If the argument to '--debug' is omitted, it defaults to 'TPt'. Option '--dump' produces the disassembled dump of the compiled sieve program. By default 'sieve' outputs all diagnostics on standard error and verbose logs on standard output. This behaviour is changed when '--log-facility' is given in the command line (see logging). This option causes 'sieve' to output its diagnostics to the given syslog facility. 3.10.1.4 Extending 'sieve' .......................... The basic set of sieve actions, tests and comparators may be extended using loadable extensions. The usual 'require' mechanism is used for that. When processing arguments for 'require' statement, 'sieve' uses the following algorithm: 1. Look up the name in a symbol table. If the name begins with 'comparator-' it is looked up in the comparator table. If it begins with 'test-', the test table is searched instead. Otherwise the name is looked up in the action table. 2. If the name is found, the search is terminated. 3. Otherwise, transform the name. First, any 'comparator-' or 'test-' prefix is stripped. Then, any character other than alphanumeric characters, '.' and ',' is replaced with dash ('-'). The name thus obtained is used as a file name of an external loadable module. 4. Try to load the module. The module is searched in the following search paths (in the order given): 1. Mailutils module directory. By default it is '$prefix/lib/mailutils'. 2. The value of the environment variable 'LTDL_LIBRARY_PATH'. 3. Additional search directories specified with the. '--libdir-prefix' command line option (*note libdir-prefix: Invoking Sieve.), or the 'library-path-prefix' configuration statement (*note library-path-prefix: Sieve Configuration.). 4. Additional search directories specified with the 'library-path' statement (*note library-path: Sieve Configuration.) in Sieve configuration file. 5. Additional search directories specified with the. '--libdir' command line option (*note libdir: Invoking Sieve.). 6. Additional search directories specified with the '#searchpath' Sieve directive (*note #searchpath::). 7. System library search path: The system dependent library search path (e.g. on Linux it is set by the contents of the file '/etc/ld.so.conf' and the value of the environment variable 'LD_LIBRARY_PATH'). The value of 'LTDL_LIBRARY_PATH' and 'LD_LIBRARY_PATH' must be a colon-separated list of absolute directories, for example, '"/usr/lib/mypkg:/lib/foo"'. In any of these directories, 'sieve' first attempts to find and load the given filename. If this fails, it tries to append the following suffixes to the file name: 1. the libtool archive extension '.la' 2. the extension used for native dynamic libraries on the host platform, e.g., '.so', '.sl', etc. 5. If the module is found, 'sieve' executes its initialization function (see below) and again looks up the name in the symbol table. If found, search terminates successfully. 6. If either the module is not found, or the symbol wasn't found after execution of the module initialization function, search is terminated with an error status. 'sieve' then displays the following diagnostic message: source for the required action NAME is not available 3.11 'guimb' -- A Mailbox Scanning and Processing Language ========================================================== 'Guimb' is an experimental tool that iterates over messages in a mailbox (or several mailboxes), applying a Scheme function to each of them. A user-defined "scheme module" that supplies the function to apply is specified using the '--source' or '--file' option. The module must define at least the following function: -- User function: guimb-message MSG Processes message MSG. This function can alter the message using Guile primitives supplied by mailutils. The following function definitions are optional: -- User function: guimb-getopt ARGS If defined, this function is called after 'guimb' has finished processing the command line. ARGS is a list of unconsumed command line arguments. The function is intended to provide a way of configuring the module from the command line. -- User function: guimb-end If defined, this function is called after all mailboxes have been processed. In the following example we define a module that prints information about each message is the input mailbox, in a way similar to 'frm' utility: (define-module (frm) :export (guimb-message)) (use-modules (mailutils mailutils)) (define (guimb-message msg) (display (mu-message-get-sender msg)) (display " ") (display (mu-message-get-header msg "subject")) (newline)) The modules are looked up in directories listed in the global variable '%load-path'. New directories can be added to that variable on the fly using the '-L' ('--load-path') option. For example, if the sample module above was saved in a file 'frm.scm' somewhere in the load path, it can be applied to the current user inbox by running the following command: guimb --file frm Specifying Scheme Program to Execute ------------------------------------ The Scheme module that defines message processing functions is given via the following options: '-s MODULE' '--source MODULE' Load Scheme code from MODULE. This option stops further argument processing, and passes all remaining arguments as the value of ARGS argument to the 'guimb-getopt' function, if it is defined. '-f MODULE' '--file MODULE' Load Scheme source code from MODULE. The remaining arguments are processed in the usual way. When using this option, you can pass additional options and or arguments to the module by enclosing them in '-{' and '-}' options (*note Passing Options to Scheme::). An experimental option is provided, that evaluates a supplied Scheme expression right after loading the module: '-e EXPR' '--expression EXPR' Evaluate scheme expression. Specifying Mailboxes to Operate Upon ------------------------------------ There are four basic ways of passing mailboxes to 'guimb'. 'guimb [OPTIONS] [MAILBOX...]' The resulting mailbox is not saved, unless the user-supplied scheme program saves it. 'guimb [OPTIONS] --mailbox DEFMBOX' The contents of DEFMBOX is processed and is replaced with the resulting mailbox contents. Useful for applying filters to user's mailbox. 'guimb [OPTIONS] --mailbox DEFMBOX MAILBOX [MAILBOX...]' The contents of specified mailboxes is processed, and the resulting mailbox contents is appended to DEFMBOX. 'guimb [OPTIONS] --user USERNAME [MAILBOX...]' The contents of specified mailboxes is processed, and the resulting mailbox contents is appended to the user's system mailbox. This makes it possible to use 'guimb' as a mail delivery agent. If no mailboxes are specified in the command line, 'guimb' reads and processes the system mailbox of the current user. Passing Options to Scheme ------------------------- Sometimes it is necessary to pass some command line options to the scheme procedure. There are three ways of doing so. When using '--source' ('-s') option, the rest of the command line following the option's argument is passed as the ARGS argument to the 'guimb-getopt' function, if such function is defined. This allows for making guimb scripts executable by the shell. If your system supports '#!' magic at the start of scripts, add the following two lines to the beginning of your script to allow for its immediate execution: #! /usr/local/bin/guimb -s !# (replace '/usr/local/bin/' with the actual path to the 'guimb'). Otherwise, if you use the '--file' option, the additional arguments can be passed to the Scheme program '-g' ('--guile-arg') command line option. For example: guimb --guile-arg -opt --guile-arg 24 --file PROGFILE In this example, the 'guimb-getopt' function will get the following argument ( '-opt' 24 ) Finally, if there are many arguments to be passed to Scheme, it is more convenient to enclose them in '-{' and '-}' escapes: guimb -{ -opt 24 -} --file PROGFILE Command Line Option Summary --------------------------- This is a short summary of the command line options available to 'guimb'. '-d' '--debug' Start with debugging evaluator and backtraces. '-e EXPR' '--expression EXPR' Execute given Scheme expression. '-L DIR' '--load-path DIR' Insert DIR at the beginning of the '%load-path' list. The argument is either a single directory name, or a list of such names, delimited by ':' characters. '-m PATH' '--mail-spool=PATH' Set path to the mailspool directory '-f PROGFILE' '--file PROGFILE' Read Scheme program from PROGFILE. '-g ARG' '--guile-command ARG' Append ARG to the command line passed to Scheme program. '-{ ... -}' Pass all command line options enclosed between '-{' and '-}' to Scheme program. '-m' '--mailbox MBOX' Set default mailbox name. '-u' '--user NAME' Act as local MDA for user NAME. '-h' '--help' Display help message. '-v' '--version' Display program version. 3.12 mda ======== GNU local mail delivery agent reads a message from its standard input and delivers it to one or more local recipients listed in the command line. When we speak about local recipients, we mean that these are system users that are known to the system that runs 'mda'. However, the mailboxes of these users can be local as well as remote ones. 'mda' is able to deliver mail to any mailbox format, supported by GNU Mailutils. These formats, among others, include 'smtp://', 'prog://' and 'sendmail://' which are equivalent to forwarding a message over SMTP to a remote node. 'Mda' is also able to process incoming messages using Sieve, Scheme or Python scripts and, based on results of this processing, to take a decision on whether to actually deliver and where to deliver them. Due to its extensive scripting facilities, 'mda' offers much more flexibility than other popular MDAs. 3.12.1 Using 'mda' with Sendmail. --------------------------------- When used with Sendmail, 'mda' must be invoked from the local mailer definition in the 'sendmail.cf' file. The flags 'lswS' must be set for the mailer. These mean: the mailer is local, quote characters should be stripped off the address before invoking the mailer, the user must have a valid account on this machine and the userid should not be reset before calling the mailer. Additionally, the 'fn' flags may be specified to allow 'mda' to generate the usual 'From ' envelope instead of the one supplied by 'sendmail'. If you wish to use 'mda' with non-local authentication, such as SQL or LDAP, you also need to remove the 'w' flag, since in that case the user is not required to have a valid account on the machine that runs 'sendmail'. Here is an example of mailer definition in 'sendmail.cf' Mlocal, P=/usr/local/sbin/mda, F=lsDFMAw5:/|@qSPfhn9, S=EnvFromL/HdrFromL, R=EnvToL/HdrToL, T=DNS/RFC822/X-Unix, A=mail $u To define local mailer in 'mc' source file, it will suffice to set: define(`LOCAL_MAILER_PATH', `/usr/local/sbin/mda') define(`LOCAL_MAILER_ARGS', `mail $u') 3.12.2 Using 'mda' with Exim. ----------------------------- Using 'mda' with Exim is quite straightforward. The following example illustrates the definition of the appropriate transport and director in 'exim.conf': # transport mda_pipe: driver = pipe command = /usr/local/sbin/mda $local_part return_path_add delivery_date_add envelope_to_add # director mda: driver = localuser transport = mda_pipe 3.12.3 Using 'mda' with MeTA1. ------------------------------ MeTA1 () communicates with the delivery agent using LMTP. Instead of using 'mda' you will have to start the LMTP daemon 'lmtpd' and configure MeTA1 to communicate with it. *Note MeTA1-lmtpd::, for details. 3.12.4 Mailbox Quotas --------------------- "Mailbox quota" is a limit on the size of the mailbox. When a mailbox size reaches this limit, 'mda' stops accepting messages for this recipient and returns an error condition to the sender. The error code is accompanied by the following error message: USER: mailbox quota exceeded for this recipient Furthermore, if accepting the incoming message would make the mailbox size exceed the quota, such a message will be rejected as well. In this case, the error message is: USER: message would exceed maximum mailbox size for this recipient In both cases, the default return code will be 'service unavailable' (corresponding to the SMTP return code '550'), unless the following statement is present in the 'maidag' configuration file: quota { exit-tempfail yes; } in which case a temporary error will be returned. The mailbox quota can be retrieved from the following sources: 1. Authentication method. 2. DBM file. 3. SQL database. 3.12.4.1 Keeping Quotas in DBM File ................................... To use DBM quota database, GNU Mailutils must be compiled with one of the following command line options: '--with-gdbm', '--with-berkeley-db', '--with-ndbm', '--with-tokyocabinet', or '--with-kyotocabinet'. Examine the output of 'mda --show-config-options', if not sure. The quota database should have the following structure: Key Key represents the user name. Special key 'DEFAULT' means default quota value, i.e. the one to be used if the user is not explicitly listed in the database. Value Mailbox quota for this user. If it is a number, it represents the maximum mailbox size in bytes. A number may optionally be followed by 'kb' or 'mb', meaning kilobytes and megabytes, respectively. A special value 'NONE' means no mailbox size limit for this user. Here is an example of a quota database in text form: # Default quota value: DEFAULT 5mb # Following users have unlimited mailbox size root NONE smith NONE # Rest of users plog 26214400 karin 10mB To use the DBM quota database, specify its absolute name using the 'database' configuration statement in the 'quota' section, e.g.: quota { database /etc/mail/quota.db; } 3.12.4.2 Keeping Quotas in SQL Database ....................................... User quotas can be kept in an SQL table as well. Currently (as of mailutils version 3.14) it is assumed that this table can be accessed using the credentials set in 'sql' configuration statement (*note SQL Statement::). For example, suppose you have the following quota table: create table mailbox_quota ( user_name varchar(32) binary not null, quota int, unique (user_name) ); To retrieve user quota the following query can be used: SELECT quota FROM mailbox_quota WHERE user_name='${user}' To define this query use the 'sql-query' statement: quota { sql-query "SELECT quota " "FROM mailbox_quota " "WHERE user_name='${user}'"; } There are no special provisions for specifying group quotas, similar to 'DEFAULT' in DBM databases. This is because group quotas can easily be implemented using SQL language. 'Mda' always uses the first tuple from the set returned by mailbox quota query. So, you can add a special entry to the 'mailbox_quota' table that would keep the group quota. In the discussion below we assume that the 'user_name' column for this entry is lexicographically less than any other user name in the table. Let's suppose the group quota name is '00DEFAULT'. Then the following query: SELECT quota FROM mailbox_quota WHERE user_name IN ('${user}','00DEFAULT') ORDER BY user_name DESC will return two tuples if the user is found in 'mailbox_quota'. Due to 'ORDER' statement, the first tuple will contain quota for the user, which will be used by 'mda'. On the other hand, if the requested user name is not present in the table, the above query will return a single tuple containing the group quota. The following configuration statement instructs 'maidag' to use this query for retrieving the user quota: quota { sql-query "SELECT quota " "FROM mailbox_quota " "WHERE user_name IN ('${user}','00DEFAULT') " "ORDER BY user_name DESC"; } 3.12.5 Scripting in 'mda' ------------------------- 'Mda' can use global or per-user "mail filters" to decide whether to deliver the message, and where to deliver it. As of Mailutils version 3.14, such mail filters may be written in the following languages: * Sieve *Note Sieve Language::. * Scheme * Python Mail filters to use are specified using 'script' configuration statement. The following meta-symbols can be used in its argument: ~ %h Expands to the recipient home directory. %u Expands to the recipient user name. By default, the filename extension decides which scripting language will be used. User can alter the choice using 'language' configuration statement. For example: script { language python; pattern "~/.maidag-py-filter"; } 3.12.5.1 Sieve MDA Filters .......................... The file name of the Sieve filter to use is specified using 'script' configuration statement. For example, the following configuration statement: script { pattern "~/.maidag.sv"; } instructs 'maidag' to use file '.maidag.sv' in the recipient home directory as a Sieve filter. Normal message delivery is attempted if execution of the Sieve code ended with 'keep' action (either implicit or explicit). Other Sieve actions are executed as described in *note Actions::. For example, to deliver message to another mailbox, use the 'fileinto' action. Any modifications to headers or body of the message performed by the Sieve code will be visible in the delivered message. 3.12.5.2 Scheme MDA Filters ........................... The file name of the Scheme mail filter is specified using 'script' configuration statement. For example, the following configuration statement: script { pattern "~/.maidag.scm"; } instructs 'mda' to use file '.maidag.scm' in the recipient home directory as a Scheme filter. 3.12.5.3 Python MDA Filters ........................... The file name of the Python mail filter is specified using 'script' configuration statement. For example, the following configuration statement: script { pattern "~/.maidag.py"; } instructs 'mda' to use the file '.maidag.py' in the recipient home directory as a Python filter. A simple example of a mail filter written in Python: from mailutils import * import maidag import re msg = message.Message (maidag.message) hdr = msg.header try: if 'List-Post' in hdr and 'Received' in hdr \ and hdr['Received'].find ('fencepost.gnu.org') != -1: # check envelope's sender address m = re.search (r'([\w\-]+)-bounces\+([\w]+)=.*', msg.envelope.get_sender ()) if m: lbox = m.group (1) user = m.group (2) # open destination mailbox and append message dst = mailbox.MailboxDefault ('~/Mail/%s' % lbox) dst.open ('ac') dst.append_message (msg) dst.close () # set deleted flag so maidag will not deliver msg elsewhere msg.attribute.set_deleted () except Exception: pass 3.12.6 Forwarding ----------------- A "forward file" is a special file in the user's home directory that contains the email address of the mailbox where the user wants to forward his mail. Normally, forward files are processed by MTA. However, there are some MTA that lack this feature. One of them is MeTA1. 'Mda' provides a forwarding feature that is useful to compensate the lack of it. This feature is controlled by the 'forward' section in the configuration file: forward { # Process forward file. file NAME; # Configure safety checks for the forward file. file-checks (LIST); } The name of the forward file is given by the 'file' statement in the 'forward' section. A common usage is: forward { file .forward; } The forward file is always searched in the recipient home directory. Before actually using the forward file, a number of safety checks are performed on it. If the file fails to pass one of these checks, no forwarding is performed and the message is delivered as usual. These checks are configured using the 'forward.file-checks' statement: forward { file .forward; file-checks (LIST); } Its argument is a list of the following keywords: groupwritablefile file_iwgrp The file must not be group writable. worldwritablefile file_iwoth The file must not be world writable. linkedfileinwritabledir link The file cannot be a symlink in a writable directory. fileingroupwritabledir dir_iwgrp The file cannot reside in a group writable directory. fileinworldwritabledir dir_iwoth The file cannot reside in a world writable directory. all All of the above checks. The default is 'file-checks all'. Each of these keywords may be prefixed by 'no' to disable this particular check. For example: forward { file-checks (nodir_iwoth, nodir_iwgrp); file .forward; } 3.12.7 MDA Configuration File Summary ------------------------------------- The behavior of 'mda' is affected by the following configuration statements: Statement Reference ------------------------------------------------------------------- debug *Note debug statement::. mailbox *Note mailbox statement::. locking *Note locking statement::. pam *Note pam statement::. sql *Note sql statement::. virtdomain *Note virtdomain statement::. radius *Note radius statement::. ldap *Note ldap statement::. auth *Note auth statement::. mailer *Note mailer statement::. -- MDA Config: stderr BOOL If BOOL is true, log to standard error instead of syslog. -- MDA Config: deliver { ... } This section contains general delivery settings: deliver { domain STRING; exit-multiple-delivery-success ARG; }; -- deliver: domain NAME Default email domain. -- deliver: exit-multiple-delivery-success ARG; In case of multiple delivery, exit with code 0 if at least one delivery succeeded. -- MDA Config: forward { ... } Controls the forwarding support: forward { file NAME; file-checks (LIST); } -- forward: file NAME Defines the name of the forward file. E.g.: forward { file .forward; } *Note Forwarding::, for a detailed description. -- forward: file-checks (LIST) Configures safety checks to be performed on the forward file prior to using it. *Note Forwarding::, for a detailed description. -- MDA Config: quota { ... } This section configures mail quota support. *Note Mailbox Quotas::, for a detailed description. quota { database NAME; sql-query QUERY; exit-tempfail BOOL; } -- quota: database NAME Sets the name of the quota database in DBM format. *Note DBM Quotas::. -- quota: sql-query QUERY If the quotas are kept in a SQL table, this statement defines the SQL query to retrieve the quota for a given user name. *Note SQL Quotas::. -- quota: exit-tempfail BOOL By default, if a message cannot be delivered because the user has exceeded its mail quota, or its delivery would cause it to be exceeded, 'MDA' exits with the 'service unavailable' status, which causes MTA to return the 550 code. If 'exit-tempfail' is set to true, it will return a temporary error instead. -- MDA Config: script { ... } Controls scripting. *Note MDA Scripting::. script { language LANG; pattern GLOB; } -- script: language LANG Defines the language that is used for scripting. Allowed values for LANG are: 'sieve', 'scheme', or 'python'. *Note scripting language::. -- script: pattern PAT Defines the pattern for the script file name. The '~' at the begiining of the pattern will be replaced with the name of the home directory of the recipient user. The '%u' in pattern will be replaced with the recipient user name, and '%h' with the home directory for that user. 3.12.8 Mailing list implementation ---------------------------------- This subsection explains how to implement mailing lists in 'mda' using the 'prog' mailbox scheme. Delivery to the 'prog' mailbox results in invoking the specified command with the given arguments and passing the message to its standard input. There are two ways to specify a 'prog' mailbox: prog://PROGRAM?ARGS Here, PROGRAM is the absolute pathname of the program binary, and ARGS are its arguments, separated by '&' signs. |PROGRAM ARGS In this notation, ARGS are command line arguments separated by white space. In both cases, ARGS do not include 'argv[0]'. The 'prog' mailbox can be used to implement mailing lists. For example, suppose that the 'mda' configuration contains: auth { authorization (sql, system); authentication (generic, system); } sql { interface mysql; db mail; getpwnam "SELECT user as name, mailbox, " "'x' as passwd, 500 as uid, 2 as gid, " "'/nonexistent' as dir, '/sbin/nologin' as shell " "FROM userdb " "WHERE user='${user}'"; } Then, the following entries in the 'userdb' table implement the mailing list: mysql> select * from userdb; +---------------------+---------------------------------------+ | user | mailbox | +---------------------+---------------------------------------+ | mailman | |/usr/bin/mailman post mailman | | mailman-admin | |/usr/bin/mailman admin mailman | | mailman-bounces | |/usr/bin/mailman bounces mailman | | mailman-confirm | |/usr/bin/mailman confirm mailman | | mailman-join | |/usr/bin/mailman join mailman | | mailman-leave | |/usr/bin/mailman leave mailman | | mailman-owner | |/usr/bin/mailman owner mailman | | mailman-request | |/usr/bin/mailman request mailman | | mailman-subscribe | |/usr/bin/mailman subscribe mailman | | mailman-unsubscribe | |/usr/bin/mailman unsubscribe mailman | +---------------------+---------------------------------------+ 3.13 lmtpd ========== The LMTP is a local mail transport protocol defined in RFC 2033. GNU Mailutils is shipped with 'lmtpd' - a daemon for delivering messages using this protocol. The daemon shares most of its codebase and configuration with 'mda' and consequently provides the same features. *Note mda::, for a detailed description of these. The behavior of 'lmtpd' is affected by the following configuration statements: Statement Reference ------------------------------------------------------------------- server *Note Server Settings:: acl *Note acl statement::. tcp-wrappers *Note tcp-wrappers statement::. debug *Note debug statement::. mailbox *Note mailbox statement::. locking *Note locking statement::. pam *Note pam statement::. sql *Note sql statement::. virtdomain *Note virtdomain statement::. radius *Note radius statement::. ldap *Note ldap statement::. auth *Note auth statement::. mailer *Note mailer statement::. 3.13.1 Using 'lmtpd' with MeTA1. -------------------------------- MeTA1 () communicates with the delivery agent using LMTP. The socket to listen for LMTP requests must be specified using the 'server' statement (*note Server Settings::). For the purposes of this section, let's suppose 'lmtpd' will listen on a UNIX socket '/var/spool/meta1/lmtpsock'. Then, the following (minimal) 'lmtpd' configuration will do the job: # Run as daemon. mode daemon; # Switch to this group after startup. group meta1c; # Configure server: server unix:///var/spool/meta1/lmtpsock { transcript no; }; To configure MeTA1 to use this socket, add the following statement to the 'smtpc' section in '/etc/meta1/meta1.conf': LMTP_socket="lmtpsock"; 3.14 putmail ============ The 'putmail' utility reads a message from its standard input and delivers it to the specified mailbox URL. The usage is: putmail URL For example, to deliver mail to a local mailbox '/var/spool/mail/test': putmail /var/spool/mail/test Of course, this would work only it the 'test' mailbox is writable for the user invoking 'putmail'. The 'smtp' mailbox scheme can be used for remote delivery. For example: putmail 'smtp://mail.example.org;to=ovr' The program will initiate SMTP dialog with the server 'mail.example.org' and will send the message from its standard input to the user 'ovr' on that server. 3.14.1 putmail options ---------------------- '-f EMAIL' '-r EMAIL' '--from=EMAIL' Specify the sender address. If not used, the current user name will be used. '-l NAME' '--language=NAME' Define scripting language for the next '--script' option. Valid arguments are 'sieve', 'scheme' and 'python'. '--message-id-header=HEADER' Use this header to identify messages when logging Sieve actions '-s NAME' '--script=NAME' Set the name of the user-defined mail filter. *Note MDA Scripting::, for a detailed discussion of the scripting feature. 3.14.2 putmail configuration ---------------------------- The behavior of 'putmail' is affected by the following configuration statements: Statement Reference ------------------------------------------------------------------- debug *Note debug statement::. mailbox *Note mailbox statement::. locking *Note locking statement::. pam *Note pam statement::. sql *Note sql statement::. virtdomain *Note virtdomain statement::. radius *Note radius statement::. ldap *Note ldap statement::. auth *Note auth statement::. mailer *Note mailer statement::. The utility also accepts all MDA configuration statements: *Note Conf-mda::. 3.15 mimeview ============= For each file given in its command line, 'mimeview' attempts to autodetect its type and invoke an appropriate file viewer. To detect the file type, 'mimeview' uses 'mime.types' file. This file is a part of Common UNIX Printing System, *note (mime.types(5))mime.types::. By default 'mimeview' searches for 'mime.types' in '$prefix/etc/cups/'(1), however its exact location can be specified at runtime as well (see '--mimetypes' below). Once file MIME type is successfully determined, 'mimeview' consults 'mailcap' files in order to determine how to display the file. It does so essentially in the same manner as 'metamail' utility, i.e., it scans all files specified in 'METAMAIL' environment variable until it finds an entry describing the desired file format or until the list of files is exhausted. If 'METAMAIL' variable is not set, 'mimeview' uses the following default path instead: $HOME/.mailcap:/usr/local/etc/mailcap:\ /usr/etc/mailcap:/etc/mailcap:\ /etc/mail/mailcap:/usr/public/lib/mailcap ---------- Footnotes ---------- (1) The exact location is determined at configuration time by setting environment variable 'DEFAULT_CUPS_CONFDIR'. On most sites running ./configure DEFAULT_CUPS_CONFDIR=/etc/cups should be recommended. 3.15.1 Mimeview Invocation -------------------------- The following table summarizes options specific for 'mimeview': '-a[TYPE-LIST]' '--no-ask[=TYPE-LIST]' By default 'mimeview' asks for confirmation before running interpreter to view a message. If this option is used without argument, it disables the default behavior for all message types. Otherwise, if argument TYPE-LIST is given, it specifies a comma-separated list of MIME types for which no questions should be asked. Elements of this list may include shell-style globbing patterns, e.g. setting --no-ask='text/*,image/jpeg' will disable prompting before displaying any textual files, no matter what their subtype is, and before displaying files with type 'image/jpeg'. Notice, that when the long form is used, its argument must be separated from the option by a single equal sign, as shown in the example above. When the short form ('-a') is used, its argument must follow the option immediately, without any intervening whitespace, e.g. '-a'text/*''). '-d[FLAGS]' '--debug[=FLAGS]' Enables debugging output. FLAGS is a sequence of characters specifying the desired debugging level. Following characters are meaningful in FLAGS: g Enables debugging of 'mime.types' parser l Enables debugging of 'mime.types' lexical analyzer (warning: produces _very_ copious output) 0 Prints basic information about actions to be executed and reports about exit status of executed commands. 1 Additionally displays each file name along with its MIME type 2 Additionally traces the process of looking up the matching entry in 'mailcap' files. 3 Additionally, enables debugging of 'mime.types' parser ('g'). 4 Additionally, enables debugging of 'mime.types' lexer ('l'). digits from 5 to 9 The same as 4, currently. If FLAGS are not given, the default '2' is assumed. '--metamail[=FILE]' Run 'metamail' to display files, instead of using the internal mechanisms. If FILE is specified, it is taken as 'metamail' command line. '-h' '--no-interactive' '--print' This options tells 'mimeview' that it should run in non-interactive mode. In this mode prompting is disabled, and the normal mailcap 'command' field is not executed. Instead 'mimeview' will execute the command specified in the 'print' field. If there is nothing in the print field, the mailcap entry is ignored and the search continues for a matching mailcap entry that does have a 'print' field. Notice, that unlike in 'metamail -h', this option does not force 'mimeview' to send the output to the printer daemon. When used with '--metamail' option, this option passes '-h' flag to the invocation of 'metamail'. By default 'mimeview' behaves as if given '--no-interactive' option whenever its standard input is not a tty device. '-i' '--identify' Identifies and prints the MIME type for each input file. '-n' '--dry-run' Do not do anything, just print what would be done. Implies '--debug=1', unless the debugging level is set up explicitly. '-f FILE' '--mimetypes FILE' Use FILE as 'mime.types' file. If FILE is a directory, use 'FILE/mime.types' '-t' '--lint' Check syntax of the 'mime.types' file and exit. Command line arguments are ignored. 3.15.2 Mimeview Config ---------------------- The following configuration statements affect the behavior of 'mimeview': Statement Reference ------------------------------------------------------------------- debug *Note Debug Statement::. -- Mimeview Config: mimetypes FILE Read FILE instead of the default 'mime.types'. -- Mimeview Config: metamail PROGRAM Use PROGRAM to display files. 3.16 POP3 Daemon ================ The 'pop3d' daemon implements the Post Office Protocol Version 3 server. 'pop3d' has two operation modes: Inetd The server is started from '/etc/inetd.conf' file: pop3 stream tcp nowait root /usr/local/sbin/pop3d pop3d This is the default operation mode. Standalone The server runs as daemon, forking a child for each new connection. The server operation mode is configured using 'mode' statement (*note mode: Server Settings.). 3.16.1 Login delay ------------------ POP3 clients often login frequently to check for new mail. Each new connection implies authenticating the user and opening his maildrop and can be very resource consuming. To reduce server load, it is possible to impose a minimum delay between any two consecutive logins. This is called 'LOGIN-DELAY' capability and is described in RFC 2449. As of version 3.14, GNU Mailutils 'pop3d' allows to set global login delay, i.e. such enforcement will affect all POP3 users. If a user attempts to log in before the specified login delay expires, he will get the following error message: -ERR [LOGIN-DELAY] Attempt to log in within the minimum login delay interval The message will be issued after a valid password is entered. This prevents this feature from being used by malicious clients for account harvesting. To enable the login delay capability, specify the minimum delay using 'login-delay' configuration statement, e.g.: login-delay 60; The 'pop3d' utility keeps each user's last login time in a special DBM file, called "login statistics database", so to be able to use this feature, Mailutils must be compiled with DBM support. By default, the login statistics database is called '/var/run/pop3-login.db'. You can change its name using 'stat-file' configuration statement: login-delay 60; stat-file /tmp/pop.login.db; The login delay facility will be enabled only if 'pop3d' is able to access the statistics database for both reading and writing. If it is not, it will report this using 'syslog' and start up without login delay restrictions. A common error message looks like: Unable to open statistics db: Operation not permitted You can check whether your 'pop3d' uses login delays by connecting to it and issuing the 'CAPA' command. If login delays are in use, there response will contain the string 'LOGIN-DELAY N', where N is the actual login delay value. 3.16.2 Auto-expire ------------------ Automatic expiration of messages allows you to limit the period of time users are permitted to keep their messages on the server. It is enabled by 'expire' configuration statement: 'expire N;' Enable automatic expiration of messages after N days. The current implementation works as follows. When a message is downloaded by 'RETR' or 'TOP' command, it is marked with 'X-Expire-Timestamp: N' header, where N is current value of UNIX timestamp. The exact expiration mechanism depends on you. Mailutils allows you two options: 1. Expired messages are deleted by 'pop3d' upon closing the mailbox. You specify this mechanism using 'delete-expired' configuration statement: 'delete-expired BOOL;' If BOOL is 'true', delete expired messages after receiving the 'QUIT' command. 2. Expired messages remain in the mailbox after closing it. The system administrator is supposed to run a cron job that purges the mailboxes. Such a cron job can be easily implemented using 'sieve' from GNU Mailutils and the following script: require "timestamp"; # Replace "5" with the desired expiration period if timestamp :before "X-Expire-Timestamp" "now - 5 days" { discard; } This script will remove expired messages 5 days after the retrieval. Replace '5' with the desired expiration period and make sure it equals the argument to 'expire' configuration keyword. The statement 'expire 0' means the client is not permitted to leave mail on the server. It always implies 'delete-expired true'. 3.16.3 Bulletins ---------------- The bulletin feature allows you to send important announcements to all POP3 users without mailing them. It works by creating a "bulletin source mailbox" and sending the announcements to it. After a user successfully authenticates, 'pop3d' checks the last "bulletin number" the user receives. The bulletin number refers to the number of the bulletin message in the bulletin source mailbox. If the latter contains more messages, these are appended to the user mailbox. The user last bulletin number can be kept in two places. First, it can be stored in file '.popbull' in his home directory. Secondly, if Mailutils is compiled with DBM support, the numbers can be kept in a DBM file, supplied via 'bulletin-db' configuration statement. If both the database and the '.popbull' file are present, the data from the database take precedence. To enable this feature, use the following configuration statements: 'bulletin-source MBOX' Set the URL of the bulletin source mailbox. 'bulletin-db FILE' Set the name of the database file to keep last bulletin numbers in. The following example instructs 'pop3d' to look for the bulletin messages in MH folder '/var/spool/bull/mbox' and to keep the database of last delivered bulletin numbers in '/var/spool/bull/numbers.db': bulletin-source mh:/var/spool/bull/mbox; bulletin-db /var/spool/bull/numbers.db; 3.16.4 Pop3d Configuration -------------------------- The following configuration file statements affect the behavior of 'pop3d'. Statement Reference ------------------------------------------------------------------- debug *Note debug statement::. tls *Note tls statement::. tls-file-checks *Note tls-file-checks statement::. mailbox *Note mailbox statement::. locking *Note locking statement::. logging *Note logging statement::. pam *Note pam statement::. sql *Note sql statement::. virtdomain *Note virtdomain statement::. radius *Note radius statement::. ldap *Note ldap statement::. auth *Note auth statement::. server *Note Server Settings::. acl *Note acl statement::. tcp-wrappers *Note tcp-wrappers statement::. -- Pop3d Conf: tls-mode MODE Configure the use of TLS encryption for inetd mode. In daemon mode, this statement sets the type of TLS encryption to use in all server blocks that lack the 'tls-mode' statement (*note Server Statement::). Allowed values for MODE are: no TLS is not used. The 'STLS' command won't be available even if the TLS configuration is otherwise complete. ondemand TLS is initiated when the user issues the appropriate command. This is the default when TLS is configured. required Same as above, but the use of TLS is mandatory. The authentication state is entered only after TLS negotiation has succeeded. connection TLS is always forced when the connection is established (POP3S protocol). -- Pop3d Conf: undelete BOOL On startup, clear deletion marks from all the messages. -- Pop3d Conf: expire N Automatically expire read messages after N days. *Note Auto-expire::, for a detailed description. -- Pop3d Conf: delete-expired BOOL Delete expired messages upon closing the mailbox. *Note Auto-expire::, for a detailed description. -- Pop3d Conf: login-delay DURATION Set the minimal allowed delay between two successive logins. *Note Login delay::, for more information. -- Pop3d Conf: stat-file FILE Set the name of login statistics file for the 'login-delay' facility. *Note Login delay::, for more information. -- Pop3d Conf: bulletin-source FILE Get bulletins from the specified mailbox. *Note Bulletins::, for a detailed description. -- Pop3d Conf: bulletin-db FILE Set bulletin database file name. *Note Bulletins::, for a detailed description. 3.16.5 Command line options --------------------------- The following table summarizes all 'pop3d' command line options. '-d[NUMBER]' '--daemon[=NUMBER]' Run in standalone mode. An optional NUMBER specifies the maximum number of child processes allowed to run simultaneously. When it is omitted, it defaults to 10 processes. _Please note_, that there should be no whitespace between the '-d' and its parameter. '-i' '--inetd' Run in inetd mode. '--foreground' Remain in foreground. The Mailutils common options are also understood. *Note Common Options::. 3.17 IMAP4 Daemon ================= GNU 'imap4d' is a daemon implementing IMAP4 rev1 protocol for accessing and handling electronic mail messages on a server. It can be run either as a standalone program or from 'inetd.conf' file. 3.17.1 Namespace ---------------- GNU 'imap4d' supports a notion of "namespaces" defined in RFC 2342. A namespace can be regarded as a list of entities, defining locations to which the user has certain access rights. Each entity includes the "prefix", under which the mailboxes can be found, "hierarchy delimiter", a character used to delimit parts of a path to a mailbox, and a "directory" on the file system on the server, which actually holds the mailboxes. Among these three values, only first two are visible to the client using the IMAP 'NAMESPACE' command. There are three namespaces: Personal Namespace A namespace that is within the personal scope of the authenticated user on a particular connection. The user has all permissions on this namespace. By default, this namespace contains a single prefix: prefix: "" delimiter: / directory: home directory of the user Other Users' Namespace A namespace that consists of mailboxes from the "Personal Namespaces" of other users. The user can read and list mailboxes from this namespace. However, he is not allowed to use '%' and '*' wildcards with 'LIST' command, that is he can access a mailbox only if he knows exactly its location. By default, this namespace is empty. Shared Namespace A namespace that consists of mailboxes that are intended to be shared amongst users and do not exist within a user's Personal Namespace. The user has all permissions on this namespace. By default, this namespace is empty. The default values ensure that each user is able to see or otherwise access mailboxes residing in the directories other than his own home. These defaults can be changed using the 'namespace' block statement: namespace NAME { mailbox-mode MODE; prefix PFX { directory PATH; delimiter CHR; mailbox-type TYPE; } } The NAME argument to the 'namespace' statement declares which namespace is being configured. Allowed values are: 'personal', 'other', and 'shared'. The 'mailbox-mode' statement configures the file mode for the mailboxes created within that namespace (provided that the directory permissions allow the user to create mailboxes). The MODE argument is a comma-delimited list of symbolic mode settings, similar to that used by 'chmod'. Each setting begins with a letter 'g', which means set mode bits for file group, or 'o', which means set mode bits for other users (note, that there is no 'u' specifier, since user ownership of his mailbox cannot be changed). This letter is followed by an '=' (or '+'), and a list of modes to be set. This list can contain only two letters: 'r' to set read permission, and 'w' to set write permission. For example, the following statement sets read and write permissions for the group: mailbox-mode g=rw; The 'prefix' statement configures available prefixes and determines their mappings to the server's file system. The PFX argument defines the prefix which will be visible to the IMAP client. The 'directory' statement defines the directory in the file system to which PFX is mapped. Exactly one 'directory' statement must be present in each 'prefix' block. The inerpretation of its argument depends on the namespace in which it occurs. When used in the 'namespace shared' block, the argument to this statement is interpreted verbatim, as an absolute pathname. When used in 'namespace personal' the argument to 'directory' statement can contain references to the following variables (*note Variables::): user Login name of the user. home Home directory of the user. For example, the following statement maps the default personal namespace to the directory 'imap' in the user's home directory: namespace personal { prefix ""; directory "$home/imap"; } If the 'directory' statement is used within the 'namespace other' block, its value can contain the '$user' and '$home' variables as well, but their meaning is different. For the 'other' namespace, the '$user' variable is expanded to the part of the actual reference contained between the prefix and first hierarchy delimiter (or the end of the reference, if no delimiter occurs to the right of the prefix). Correspondingly, '$home' expands to the home directory of that user. Consider, for example, the following statement: namespace other { prefix "~"; directory "/var/imap/$user"; } If the client issues the following statement: 1 LIST "~smith" "%" then '$user' will expand to the string 'smith' and the server will look for all mailboxes in the directory '/var/imap/smith'. The 'delimiter' statement defines the folder hierarchy delimiter for that prefix. It is optional, the default value being '"/"'. The 'mailbox-type' statement declares the type of the mailboxes within that prefix. If present, its argument must be a valid mailbox type (e.g. 'mailbox', 'maildir', or 'mh'). The IMAP 'LIST' command will display only mailboxes of that type. The 'CREATE' command will create mailboxes of that type. In the absence of the 'mailbox-type' statement, the IMAP 'LIST' command will display mailboxes of any type supported by Mailutils. The type of newly-created mailboxes is then determined by the 'mailbox-type' statement (*note mailbox-type::). Any number of 'prefix' blocks can be present. Consider, for example, the following configuration: namespace personal { prefix "" { directory "$home/mailfolder"; } prefix "#MH:" { directory "$home/Mail"; delimiter "/"; mailbox-type "mh"; } } It defines the personal namespace containing two prefixes. The empty prefix is mapped to the directory 'mailfolder' in the home directory of the currently authenticated user. Any type of mailboxes is supported within that prefix. The prefix '#MH:' is mapped to the directory 'Mail' in the home directory of the user, and is limited to contain only mailboxes in MH format. Note that if the prefixes '""' is not defined in the personal namespace, the following default will be automatically created: prefix "" { directory "$home"; } 3.17.2 Configuration of 'imap4d'. --------------------------------- The behavior of 'imap4d' is altered by the following configuration statements: Statement Reference ------------------------------------------------------------------- debug *Note debug statement::. tls *Note tls statement::. tls-file-checks *Note tls-file-checks statement::. mailbox *Note mailbox statement::. locking *Note locking statement::. logging *Note logging statement::. pam *Note pam statement::. sql *Note sql statement::. virtdomain *Note virtdomain statement::. radius *Note radius statement::. ldap *Note ldap statement::. auth *Note auth statement::. server *Note Server Settings::. acl *Note acl statement::. tcp-wrappers *Note tcp-wrappers statement::. -- Imap4d Conf: namespace NAME { ... } Configures namespace. The argument is one of: 'personal', 'other', 'shared'. The following statements (described below) are allowed within curly braces: 'mailbox-mode' and 'prefix'. *Note Namespace::. -- Imap4d namespace: mailbox-mode MODE Configures the file mode for the mailboxes created within that namespace. The syntax for MODE is: g(+|=)[wr]+,o(+|=)[wr]+ *Note mailbox-mode: Namespace. -- Imap4d namespace: prefix PFX { ... } Configures a prefix and determines its mapping to the server's file system. The PFX argument is the prefix which will be visible to the IMAP client. Available sub-statements are: 'directory', 'delimiter', and 'mailbox-type'. *Note prefix: Namespace. -- Imap4d namespace.prefix: directory PATH Defines the directory in the file system to which the prefix is mapped. *Note directory: Namespace. -- Imap4d namespace.prefix: delimiter CHR Defines the folder hierarchy delimiter for the prefix. Argument must be a single character. *Note delimiter: Namespace. -- Imap4d namespace.prefix: mailbox-type TYPE Defines the type of the mailboxes inside that prefix. *Note mailbox-type: Namespace. -- Imap4d Conf: login-disabled BOOL Disable 'LOGIN' command, if BOOL is 'true'. -- Imap4d Conf: create-home-dir BOOL Create nonexistent user home directories. See also home-dir-mode, below. -- Imap4d Conf: home-dir-mode MODE Set file mode for created user home directories. Mode is specified in octal. The default value for MODE is '700' ('drwx------' in 'ls' terms). -- Imap4d Conf: preauth MODE Configure PREAUTH mode. Valid arguments are: prog:///PROGRAM-NAME 'Imap4d' invokes an external program to authenticate the connection. The command line is obtained from the supplied string, by expanding the following meta-variables: '${client_address}' Remote IP address in dotted-quad notation; '${client_port}' Remote port number; '${server_address}' Local IP address; '${server_port}' Local port number. If the connection is authenticated, the program should print the user name, followed by a newline character, on its standard output and exit with code '0'. Otherwise, it should exit with a non-zero exit code. ident[://:PORT] The remote machine is asked about the requester identity using the identification protocol (RFC 1413). Both plaintext and DES encrypted replies are understood. Optional PORT specifies the port to use, if it differs from the default '113'. It can be either a decimal port number or a symbolic name of a service, listed in '/etc/services'. stdio PREAUTH mode is enabled automatically if imap4d is started from command line in interactive mode ('-i' command line option). The current login name is used as the user name. -- Imap4d Conf: preauth-only BOOL If BOOL is 'true', use only preauth mode. If unable to setup it, disconnect immediately. -- Imap4d Conf: ident-keyfile FILE Set DES keyfile for decoding encrypted ident responses. Used with 'ident://' preauth mode. -- Imap4d Conf: ident-encrypt-only BOOL Use only encrypted IDENT responses. -- Imap4d Conf: id-fields LIST Set list of fields to return in response to ID command. Valid field names are: name Package name ('GNU Mailutils'). version Package version ('3.14'). vendor Vendor name ('GNU'). support-url The string 'http://www.gnu.org/software/mailutils' address The string '51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA'. os OS name. os-version OS version number. command Name of the 'imap4d' binary. arguments Invocation command line. environment List of environment variables with their values. 3.17.3 Starting 'imap4d' ------------------------ 'imap4d' may run either in "standalone" or in "inetd" operation modes. When run in "standalone" mode, the server disconnects from the terminal and runs as a daemon, forking a child for each new connection. The "inetd" mode allows to start the server from '/etc/inetd.conf' file. This is the default operation mode. imap4 stream tcp nowait root /usr/local/sbin/imap4d imap4d Command Line Options -------------------- '-d[NUMBER]' '--daemon[=NUMBER]' Run in standalone mode. An optional NUMBER specifies the maximum number of child processes the daemon is allowed to fork. When it is omitted, it defaults to 20 processes. _Please note_, that there should be no whitespace between the '-d' and its parameter. '-i' '--inetd' Run in inetd mode. '--foreground' Run in foreground. '--preauth' Start in preauth mode '--test' Run in test mode. See also *note Common Options::. 3.18 Comsat Daemon ================== Comsatd is the server which receives reports of incoming mail and notifies users about it. By default, it prints subject, sender name and email, followed by first five lines of each newly arrived message to the tty of the recipient user. Users can customize this behavior. 3.18.1 Starting 'comsatd' ------------------------- '-d' '--daemon' Run as a standalone daemon. '-i' '--inetd' The server is started from '/etc/inetd.conf' file: comsat dgram udp wait root /usr/sbin/comsatd \ comsatd -c /etc/comsat.conf This is the default operation mode. '-t[FILE]' '--test[=FILE]' Test mode. In this mode, 'comsatd' takes two arguments: URL of a mailbox and QID of the message from that mailbox and prints the notification to the current user tty ('/dev/tty'), or FILE, if it is supplied. If the '~/.biffrc' file exists, it will be used. For example: $ comsatd --test /var/mail/root 34589 Notice, that FILE is an optional argument. When supplied, it should follow the short option form immediately, or the long option form after the equals sign, e.g.: $ comsatd --test=logfile /var/mail/root 34589 or $ comsatd -tlogfile /var/mail/root 34589 '--foreground' Don't detach from the controlling terminal, remain in foreground. See also *note Common Options::. 3.18.2 Configuring 'comsatd' ---------------------------- Following configuration statements affect the behavior of 'comsatd': Statement Reference ------------------------------------------------------------------- debug *Note debug statement::. logging *Note logging statement::. mailbox *Note mailbox statement::. locking *Note locking statement::. acl *Note acl statement::. 3.18.2.1 General Settings ......................... These statements control the general behavior of the comsat daemon: -- Comsatd Conf: max-lines NUMBER Set maximum number of message body lines to be output. -- Comsatd Conf: allow-biffrc BOOL Enable or disable processing of user's '.biffrc' file. By default, it is enabled. 3.18.2.2 Security Settings .......................... These statements control the way 'comsatd' fights possible flooding attacks. -- Comsatd Conf: max-requests NUMBER Set maximum number of incoming requests per 'request-control-interval'. -- Comsatd Conf: request-control-interval DURATION Set the request control interval. -- Comsatd Conf: overflow-delay-time DURATION Set initial amount of time to sleep, after the first overflow occurs. -- Comsatd Conf: overflow-control-interval DURATION Set overflow control interval. If two consecutive overflows happen within that interval, the overflow-delay-time is doubled. 3.18.3 A per-user Configuration File ------------------------------------ By default, when a notification arrives, 'comsatd' prints subject, from headers and the first five lines from the new message to the user's tty. The user is allowed to change this behavior by using his own configuration file. This file should be located in the user's home directory and should be named '.biffrc'. It must be owned by the user and have its permissions bits set to 0600. (_Please note_, that the use of per-user configuration files may be disabled, by specifying 'allow-biffrc no' in the main configuration file, see *note Configuring comsatd::). The '.biffrc' file consists of a series of statements. Each statement occupies one line and defines an action to be taken upon arrival of a new mail. Very long lines may be split using '\' as the last character on the line. As usual, comments may be introduced with '#' character. The actions specified in '.biffrc' file are executed in turn. The following actions are defined: beep Produce an audible signal. echo [-n] STRING [STRING...] Output the arguments to the user's terminal device. If several arguments are given they will be output separated by single spaces. The newline character will be printed at the end of the output, unless the '-n' option is used. exec PROG ARGLIST Execute program PROG with arguments from ARGLIST. PROG must be specified with absolute pathname. It may not be a setuid or setgid program. In the description above, STRING denotes any sequence of characters. This sequence must be enclosed in a pair of double-quotes, if it contains whitespace characters. The '\' character inside a string starts a C escape sequence. Following meta-characters may be used in strings: $u Expands to username $h Expands to hostname $H{name} Expands to value of message header 'name'. $B(C,L) Expands to message body. C and L give maximum number of characters and lines in the expansion. When omitted, they default to 400, 5. Example I ......... Dump to the user's terminal the contents of 'From' and 'Subject' headers followed by at most 5 lines of message body. echo "Mail to \a$u@$h\a\n---\n\ From: $H{from}\n\ Subject: $H{Subject}\n\ ---\n\ $B(,5)\ ---\n" The above example can also be written as: echo Mail to \a$u@$h\a echo --- echo From: $H{From} echo Subject: $H{Subject} echo --- echo $B(,5) echo --- Example II .......... Produce a bell, then pop up the xmessage window on display :0.0 with the text formatted in the same manner as in the previous example. beep exec /usr/X11R6/bin/xmessage \ -display :0.0 -timeout 10 "Mail to $u@$h \n---\n\ From: $H{from}\n\ Subject: $H{Subject}\n\ ---\n\ $B(,5)\ ---\n" 3.19 MH -- The MH Message Handling System ========================================= The primary aim of this implementation is to provide an interface between Mailutils and Emacs using mh-e module. To use Mailutils MH with Emacs, add the following line to your site-start.el or .emacs file: (load "mailutils-mh") For the information about the current state of Mailutils MH implementation please refer to file 'mh/TODO' in the Mailutils distribution directory. 3.19.1 Major differences between Mailutils MH and other MH implementations -------------------------------------------------------------------------- 1. Sequence numbers increase monotonically; Message sequence numbers are used as UIDs and thus increase monotonically. This means, in particular, that if your inbox has messages in the range 'X--Y' and you delete all messages and then incorporate new mail, the first incorporated message will be assigned sequence number 'Y + 1' (other MH implementations will assign '1'). If this behavior bugs you, add the following setting to your '.mh_profile': Volatile-uidnext: true You can always renumber your messages starting from '1' by running folder -pack=1 2. UUCP addresses are not supported; 3. Mailutils supports a set of new format specifications (*note Format String Diffs::); 4. Mailutils provides a set of new profile variables (*note Profile Variable Diffs::); 5. All programs recognize '--help' and '--version' options These options are recognized only if no other arguments are present in the command line. Abbreviations are not recognized. This makes Mailutils MH implementation compatible with the standard usage for GNU tools. 6. Several programs behave differently (*note Program Diffs::); 3.19.1.1 New and Differing MH Format Specifications ................................................... -- MH Format: string decode (string STR) Decodes the input string STR as per RFC 2047. Useful in printing 'From:', 'To:' and 'Subject:' headers. Notice that, unlike the similar NMH function, 'decode' checks the value of the global profile variable 'Charset' (*note Charset variable::) to determine the charset to output the result in. If this variable is not set, 'decode' returns its argument without any change. If this variable is set to 'auto', 'decode' tries to determine the charset name from the setting of 'LC_ALL' environment variable. Otherwise, the value of 'Charset' is taken to be the name of the character set. -- MH Format: string package () Returns package name (string 'mailutils'). -- MH Format: string package_string () Returns full package string (e.g. 'GNU Mailutils 2.1') -- MH Format: string version () Returns mailutils version. -- MH Format: string unre (string STR) The function removes any leading whitespace and eventual 'Re:' prefix from its argument. Useful for creating subjects in reply messages: %<{subject}Subject: Re: %(unre{subject})\\n%> -- MH Format: void reply_regex (string R) Sets the regular expression used to recognize reply messages. The argument R should be a POSIX extended regular expression. Matching is case insensitive. For example, the following invocation %(reply_regex ^\(re|aw|ang|odp\)\(\\[[0-9]+\\]\)?:[[:blank:]]) corresponds to English 'Re', Polish 'Odp', Norwegian 'Aw' or German 'Ang', optionally followed by a number in brackets, followed by colon and any amount of whitespace. Notice proper quoting of the regex metacharacters. See also 'Reply-Regex' (*note Reply-Regex variable::) and 'isreply' (*note isreply MH function::) below. -- MH Format: boolean isreply ([string STR]) If STR is not given, the value of 'Subject:' header is taken. The function returns true if its argument matches the "reply subject" regular expression. This expression is set via the global profile variable 'Reply-Regex' (*note Reply-Regex variable::) or via the format function 'reply_regex'. This function is useful for creating 'Subject:' headers in reply messages. For example, consider the following construction: %<{subject}%(lit)%<(isreply)%?\ (profile reply-prefix)%(concat)%|%(concat Re:)%>\ %(concat{subject})%(printhdr Subject: )\n%> If the 'Subject:' header already contained reply prefix, this construct leaves it unchanged. Otherwise it prepends to it the value of 'Reply-Prefix' profile variable, or, if it is unset, the string 'Re:'. This expression is used in default 'replcomps' and 'replgroupcomps' files. -- MH Format: boolean rcpt ('to' | 'cc' | 'me' | 'all') This function returns true if the given element is present in the recipient mask (as modified by '-cc' or '-nocc' options) and false otherwise. It is used in default formats for 'repl' and 'comp', e.g.: %(lit)%<(rcpt to)%(formataddr{to})%> Notice that this means that usual 'replcomps' file will be ignoring '-cc' and '-nocc' options, unless it has been modified as shown above. -- MH Format: string concat () Appends whitespace + arg to string register. -- MH Format: string printhdr (string STR) Prints the value of string register, prefixed by STR. The output is formatted as a RFC 822 header, i.e. it is split at whitespace characters nearest to the width boundary and each subsequent segment is prefixed with horizontal tabulation. -- MH Format: string in_reply_to () Generates the value for 'In-reply-to:' header according to RFC 2822. -- MH Format: string references () Generates the value for 'References:' header according to RFC 2822. 3.19.1.2 New MH Profile Variables ................................. -- Variable: MH Variable string Charset Controls the character set in which the components decoded via the 'decode' (*note decode function::) format function should be output. -- Variable: MH Variable string Reply-Regex Keeps the regular expression used to recognize reply messages. The argument should be a POSIX extended regular expression. Matching is case insensitive. For more information, please see *Note reply_regex function::. 3.19.1.3 Differences in MH Program Behavior ........................................... 'anno' The prompt in interactive mode is 'Component name:', instead of 'Enter component name:' displayed by the RAND 'anno'. If a '-component field' is not specified and standard input is not connected to a terminal, 'anno' does not display the prompt before reading the component from the standard input. RAND 'anno' displays the prompt anyway. 'burst' The utility is able to burst both RFC 934 digest messages and MIME multipart messages. It provides two additional command line options: '-recurse' and '-length'. The '-recurse' option instructs the utility to recursively expand the digest. The '-length' option can be used to set the minimal encapsulation boundary length for RFC 934 digests. Default length is 1, i.e. encountering one dash immediately following a newline triggers digest decoding. It is OK for messages that follow RFC 934 specification. However, many user agents do not precisely follow it, in particular, they often do not escape lines starting with a dash by '- ' sequence. 'Mailman' is one of such agents. To cope with such digests you can set encapsulation boundary length to a higher value. For example, 'bounce -length 8' has been found to be sufficient for most Mailman-generated digests. 'comp' Understands '-build' option. 'fmtdump' This command is not provided. Use 'fmtcheck' instead. 'inc' * The '-moveto' option. The '-moveto' option instructs 'inc' to move messages into another folder after incorporating them. This option has effect only if the '-truncate' option has also been specified and the underlying mailbox supports the 'move' operation. Currently only 'imap' and 'imaps' mailboxes support it. For example, the following command moves incorporated messages into the 'archive' folder: inc -file imaps://imap.gmail.com -moveto=archive The 'moveto' URL parameter can be used instead of this option, e.g.: inc -file 'imaps://imap.gmail.com;moveto=archive' * Multiple sources Mailutils 'inc' is able to incorporate messages from several source mailboxes. These are specified via multiple '-file' options, e.g.: inc -truncate \ -file 'imaps://imap.gmail.com;moveto=archived' \ -file pops://mail.gnu.org \ -file /var/mail/root * URL parameters The following additional parameters can be used in the mailbox URLs supplied with the '-file' option: 'moveto=FOLDER' Moves incorporated messages into another folder. This was discussed above. 'nomoveto' Disables the previous '-moveto' option. 'truncate[=BOOL]' Controls source mailbox truncation. If BOOL is not given or it is 'yes', the mailbox will be truncated after successful processing. If BOOL is 'no', the source mailbox will not be truncated. 'mhl' The 'ignores' keyword can be used in variable list. In that case, if its value contains more than one component name it must be enclosed in double-quotes, e.g.: leftadjust,compwidth=9,"ignores=msgid,message-id,received" The above is equivalent to the following traditional notation: leftadjust,compwidth=9 ignores=msgid,message-id,received The 'MessageName' component is not yet implemented. Interactive prompting is not yet implemented. The following format variables are silently ignored: 'center', 'split', 'datefield'. 'mhn' * New option New option '-compose' forces 'mhn' editing mode. This is also the default mode. This differs from the standard 'mhn', which switches to the editing mode only if no other options were given and the input file name coincides with the value of 'mhdraft' environment variable. * Show mode ('-show') If an appropriate mhn-show-type[/subtype] was not found, GNU 'mhn' prints the decoded message content using 'moreproc' variable. Standard 'mhn' in this case used to print 'don't know how to display content' diagnostic. The default behaviour is to pipe the content to the standard input of the mhn-show-type[/subtype] command. This is altered to using a temporary file if the command contains '%f' or '%F' escapes. * Store mode ('-store') If the 'Content-Disposition' header contains 'filename=', and 'mhn' is invoked with '-auto' switch, it transforms the file name into the absolute notation and uses it only if it lies below the current mhn-storage directory. Standard 'mhn' only requires that the file name do not begin with '/'. Before saving a message part, GNU 'mhn' checks if the file already exists. If so, it asks whether the user wishes to rewrite it. This behaviour is disabled when '-quiet' option was given. 'mhparam' The '-all' mode does not display commented out entries. 'pick' New command line option '-cflags' allows to control the type of regular expressions used. The option must occur right before '--COMPONENT PATTERN' or equivalent construct (like '-cc', '-from', etc.) The argument to this option is a string of type specifications: B Use basic regular expressions E Use extended regular expressions I Ignore case C Case sensitive Default is 'EI'. The flags remain in effect until the next occurrence of '-cflags' option. Sample usage: pick -cflag BC -subject '*a string' The date comparison options ('-before' and '-after' accept date specifications in a wide variety of formats, e.g.: pick -after 20030301 pick -after 2003-03-01 pick -after 01-mar-2003 pick -after 2003-mar-01 pick -before '1 year ago' etc... 'prompter' 1. Prompter attempts to use GNU Readline library, if it is installed. Consequently, arguments to '-erase' and '-kill' option must follow GNU style key sequence notation (*note keyseq: (readline)Readline Init File Syntax.). If 'prompter' is built without 'readline', it accepts the following character notations: \NNNN Here, N stands for a single octal digit. ^CHR This notation is translated to the ASCII code 'CHR + 0100'. 2. Component continuation lines are not required to begin with a whitespace. If leading whitespace is not present, 'prompter' will add it automatically. 'refile' 1. Linking messages between folders goes against the logic of Mailutils, so 'refile' never makes links even if called with '-link' option. The latter is actually a synonym for '-copy', which preserves the original message. 2. The '-preserve' option is not implemented. It is retained for backward compatibility only. 3. Message specs and folder names may be interspersed. 'repl' Understands '-use' option. Disposition shell provides 'use' command. 'rmm' 1. Different behaviour if one of the messages in the list does not exist: Mailutils 'rmm' does not delete any messages. Standard 'rmm' in this case deletes all messages preceding the non-existent one. 2. The 'rmm' utility will unlink messages, if the 'rmmproc' profile component has empty value, e.g.: rmmproc: 'sortm' New option '-numfield' specifies numeric comparison for the given field. Any number of '-datefield', '-textfield' and '-numfield' options may be given, thus allowing to build sort criteria of arbitrary complexity. The order of '-.*field' options sets the ordering priority. This differs from the behaviour of the standard 'sortm', which always orders datefield-major, textfield-minor. Apart from sorting the mailfolder the following actions may be specified: '-list' List the ordered messages using a format string given by '-form' or '-format' option. '-dry-run' Do not actually sort messages, rather print what would have been done. This is useful for debugging purposes. 3.20 mailutils ============== The 'mailutils' utility is a multi-purpose tool shipped with Mailutils. It can be used for various mail and database-related tasks, as well as an auxiliary tool for compiling and linking programs with Mailutils. 3.20.1 Invocation Syntax ------------------------ 'Mailutils' is a command line tool. Its invocation syntax is: mailutils [OPTIONS] COMMAND [ARGS] where OPTIONS are options that affect the behavior of 'mailutils' as a whole, COMMAND instructs it what it is to do and ARGS are any arguments the COMMAND needs in order to be executed. The commands are: 2047 Decodes or encodes email message headers. acl Tests Mailutils access control lists. cflags Shows compiler options needed to compile with Mailutils. dbm Invokes a DBM management tool. ;filter Applies a chain of filters to the input. help Displays a terse help summary. imap Invokes an IMAP4 client shell (in development). info Displays information about Mailutils compile-time configuration. ldflags Constructs a 'ld'(1) command line for linking a program with Mailutils. logger Logs information using Mailutils log facility. pop Invokes a POP3 client shell. query Queries configuration values. wicket Scans wicket for matching URLs 3.20.2 mailutils help --------------------- The 'mailutils help' command lists all available options and command names along with short descriptions of what each of them does. It is similar to the 'mailutils --help' option. A command name can be supplied as an argument to 'help', in which case it will display a help page for that particular command, e.g.: mailutils help ldflags will output help for the 'ldflags' command. It is synonymous to the '--help' option used with that particular command, e.g.: 'mailutils ldflags --help'. 3.20.3 mailutils info --------------------- The 'mailutils info' command displays information about Mailutils compile-time configuration. In normal form its output lists a single configuration flag per line, e.g.: $ mailutils info VERSION=2.99.93 SYSCONFDIR=/etc MAILSPOOLDIR=/var/mail/ SCHEME=mbox LOG_FACILITY=mail IPV6 USE_LIBPAM HAVE_LIBLTDL WITH_GDBM WITH_GNUTLS WITH_GSASL A configuration flag can consist either of a single word, indicating that a particular capability has been enabled at compile time, or of a keyword/value pair delimited by an equal sign, which indicates a particular value used by default for that feature. For example, 'IPV6' means that Mailutils was compiled with support for IPv6, whereas 'SYSCONFDIR=/etc' means that the default place for configuration files is in '/etc' directory. Such short output is convenient for using 'mailutils info' in scripts to decide whether it is possible to use a given feature. To assist human users, the '--verbose' ('-v') option is provided. It prints a short description next to each flag: $ mailutils info --verbose VERSION=2.99.93 - Version of this package SYSCONFDIR=/etc - System configuration directory MAILSPOOLDIR=/var/mail/ - Default mail spool directory SCHEME=mbox - Default mailbox type LOG_FACILITY=mail - Default syslog facility IPV6 - IPv6 support USE_LIBPAM - PAM support HAVE_LIBLTDL - a portable `dlopen' wrapper library WITH_GDBM - GNU DBM WITH_GNUTLS - TLS support using GNU TLS WITH_GSASL - SASL support using GNU SASL 3.20.4 mailutils cflags ----------------------- The 'mailutils cflags' command shows compiler options needed to compile a C source with Mailutils. It is intended for use in configuration scripts and Makefiles, e.g.: CFLAGS=-g -O2 `mailutils cflags` 3.20.5 mailutils ldflags ------------------------ The 'mailutils ldflags' command is a counterpart of 'cflags' which is used for linking. It constructs a 'ld' command line for linking a program with Mailutils. When used without arguments, it outputs 'ld' arguments which would link only with the core Mailutils library 'libmailutils', e.g.: $ mailutils ldflags -L/usr/local/lib -lmailutils This command accepts a number of keywords which allow to select a particular subset of Mailutils libraries to link with. In particular, the argument 'all' instructs it to link in all available libraries: $ mailutils ldflags all -L/usr/local/lib -lmu_mbox -lmu_mh -lmu_maildir -lmu_imap -lmu_pop \ -lmu_mailer -lmu_compat -lmailutils -lmu_auth -lgsasl -lgnutls -lgcrypt \ -lldap -lgnuradius -lpam -ldl Other available keywords are: mbox Link in the UNIX mbox format support. mh Link in the MH format support. maildir Link in the Maildir format support. imap Link in the IMAP protocol support. pop Link in the POP protocol support. mailer Enable support for mailers. sieve Link in the support for Sieve mail filtering language. dbm Link in the support for DBM databases (libmu_dbm library). auth Link in the Mailutils authentication library. guile Provide Guile language bindings. python Provide Python language bindings. 3.20.6 mailutils stat --------------------- The command 'mailutils stat' shows status of a mailbox. The name or URL of the mailbox to operate upon is supplied in the first argument. If not given, the command will display status of the invoking user system mailbox. $ mailutils stat type: maildir path: /var/mail/smith URL: /var/mail/smith size: 3498 messages: 24 recent messages: 3 first unseen: 20 uidvalidity: 1338543026 next uid: 87 access: 2016-12-15 09:15:08 +0200 The output format is controlled by the '--format' ('-c') option. Its argument is the desired format string, composed of ordinary characters, which are reporduced on standard output verbatim, backslash sequences, and format specifiers, beginning with '%'. "Backslash sequences" are interpreted as in C. A "format specifier" consists of a leading '%' followed by a letter. Optional ':' may occur between '%' and the letter. Its presense instructs the program to print the description of the corresponding value before the value itself. The following format sequences are understood: %f Name of the mailbox as supplied in the command line. If 'mailutils stat' was used without explicit mailbox argument, '%f' is equivalent to '%U'. %t Type of the mailbox ('mbox', 'maildir', etc.). The description string is 'type'. %p Path to the mailbox. In case of remote mailboxes, it is the path part of the mailbox URL. Description string: 'path'. %U URL of the mailbox. Description string: 'URL'. %s Size of the mailbox in octets. Description string: 'size'. %c Number of messages in the mailbox. Description string: 'messages'. %r Number of recent (unread) messages in the mailbox. Description string: 'recent messages'. %u Index of the first unseen message. Description string: 'first unseen'. %v The UIDVALIDITY value. Description string: 'uidvalidity'. %n The UID value which will be assigned to the new message to be incorporated into the mailbox. Description string: 'next uid'. %a Access time of the mailbox, as a number of seconds since the epoch. %A Access time of the mailbox in human-readable format. 3.20.7 mailutils query ---------------------- The 'mailutils query' command queries values from Mailutils configuration files. It takes one or more configuration paths (*note Paths::) as its arguments. On output, it displays the values it found, each value on a separate line. If the requested value is a block statement it is displayed in full. For example, if main configuration file contained: logging { syslog yes; facility mail; } Then: $ mailutils query .logging.syslog syslog yes; $ mailutils query .logging.syslog .logging.facility syslog yes; facility mail; $ mailutils query .logging logging { syslog yes; facility mail; }; Several command line options allow to modify output format. The '--value' option instructs the command to output only values: $ mailutils query --value .logging.syslog yes The '--path' option instructs it to print full pathnames for each value: $ mailutils query --path .logging.syslog logging.syslog: yes The '--program' option instructs 'mailutils' to behave as if it was called under another program name. For example, the following command: $ mailutils query --program=pop3d .server.transcript will return the value of the '.server.transcript' statement which the 'pop3d' utility would see. By default, 'mailutils query' operates on the main configuration file. Another configuration file can be supplied using the '--file' ('-f') option: $ mailutils query --file /usr/local/etc/file.conf .pidfile 3.20.8 mailutils 2047 --------------------- The 'mailutils 2047' command is a filter for decoding or encoding email message headers formatted in accordance with RFC 2047 (see . By default, it operates in encode mode and assumes the 'iso-8859-1' encoding. If arguments are supplied in the command line, they are treated as the text to operate upon. Otherwise the command acts as a UNIX filter, reading lines from the standard input and printing results on the standard output. For example: $ mailutils 2047 'Keld Jørn Simonsen ' =?ISO-8859-1?Q?Keld_J=F8rn_Simonsen?= The decode mode can be requested via the '--decode' ('-d') option: $ mailutils 2047 --decode '=?ISO-8859-1?Q?Keld_J=F8rn_Simonsen?= \ ' Keld Jørn Simonsen The '--charset' ('-c') option changes the default character set. It is meaningful both in decode and in encode modes. In decode mode it instructs the utility to convert the output to the given character set. In encode mode it indicates the encoding of the input data, which will be reflected in the resulting string: $ mailutils 2047 --charset=utf-8 'Keld Jørn Simonsen ' =?utf-8?Q?Keld J=C3=B8rn Simonsen ?= The '--encoding' ('-E') option can be used in encode mode to change the output encoding. Valid arguments for this option are: 'quoted-printable' (the default) or 'base64'. The '--newline' ('-n') option prints an additional newline character after each line of output. 3.20.9 mailutils filter ----------------------- The 'mailutils filter' command applies a chain of filters to the input. The filters to apply and their arguments are given in the command line. The full invocation syntax is: mailutils filter [OPTION] FILTER-CHAIN The syntax for FILTER-CHAIN in Backus-Naur form follows: ::= | "+" ::= * ::= | "~" where stands for the filter name and represents filter arguments. To obtain a list of known filter names, run: mailutils filter --list Filters are applied in the order of their appearance, from left to right and operate in encode mode. The plus sign has the same meaning as pipe in shell. The default mode can be changed using the '--decode' ('-d') and '--encode' ('-e') options. Whatever the default mode is, a '~' character before filter name reverts the mode for that filter alone. For example, to encode the contents of file 'file.txt' in Base64 run: mailutils filter base64 < file.txt To convert it to base64 and use CRLF as line delimiters, run: mailutils filter base64 + crlf < file.txt The following command will decode the produced output: mailutils filter --decode crlf + base64 It can also be written as mailutils filter ~crlf + ~base64 The following example converts the input from ISO-8859-2 to UTF-8, quotes eventual 'From' occurring at the beginning of a line, encodes the result in Base64 and changes line delimiters to CRLF: mailutils filter iconv iso-8859-2 utf-8 + from + base64 + crlf This final example removes UNIX-style comments from the input and joins continuation lines: mailutils filter --decode inline-comment -S '#' + linecon Such invocation can be useful in shell scripts to facilitate configuration file processing. 3.20.10 mailutils acl --------------------- The 'mailutils acl' command tests Mailutils Access Control Lists. By default it reads ACL from the Mailutils configuration file section 'acl'. The command takes a list of IP addresses as its arguments, applies the ACL to each of them in turn and prints the result. To select the ACL to test, two options are provided. The '--file' ('-f') option supplies the name of configuration file to read instead of the default one. The '--path' ('-p' option supplies the pathname (*note Paths::) of the ACL section to use instead of the default '.acl'. For example, to test ACL in section 'server 213.130.1.232' of file '/etc/pop3d.conf' use: mailutils acl --file=/etc/pop3d.conf \ --path=/server="213.130.1.232"/acl ADDRESS As an example of its use, consider file 'test.conf' with the following contents: acl { deny from 10.10.10.1; deny from 10.10.1.0/24; log from any "Connect from ${address}"; allow from 10.0.0.0/8; allow from 192.168.1.0/24; deny from any; } Then, running 'mailutils acl --file=test.conf 127.0.0.1' you will get: Testing 127.0.0.1: mailutils: Connect from 127.0.0.1 127.0.0.1: deny More examples: $ mailutils acl --file=test.conf 127.0.0.1 10.10.10.1 \ 10.10.1.3 10.5.3.1 192.168.1.0 192.168.2.0 Testing 127.0.0.1: mailutils: Connect from 127.0.0.1 127.0.0.1: deny Testing 10.10.10.1: 10.10.10.1: deny Testing 10.10.1.3: 10.10.1.3: deny Testing 10.5.3.1: mailutils: Connect from 10.5.3.1 10.5.3.1: accept Testing 192.168.1.0: mailutils: Connect from 192.168.1.0 192.168.1.0: accept Testing 192.168.2.0: mailutils: Connect from 192.168.2.0 192.168.2.0: accept The 'mailutils' option '--debug-level' will give you a deeper insight into the address matching algorithm: $ mailutils --debug-level=acl.trace9 acl --file test.conf 127.0.0.1 Testing 127.0.0.1: mailutils: Checking sockaddr 127.0.0.1 mailutils: 1:deny: Does 10.10.10.1/255.255.255.255 match 127.0.0.1? no; mailutils: 2:deny: Does 10.10.1.0/255.255.255.0 match 127.0.0.1? no; mailutils: 3:log: Does any match 127.0.0.1? yes; mailutils: Expanding "Connect from ${address}"; mailutils: Expansion: "Connect from 127.0.0.1";. mailutils: Connect from 127.0.0.1 mailutils: 4:accept: Does 10.0.0.0/255.0.0.0 match 127.0.0.1? no; mailutils: 5:accept: Does 192.168.0.0/255.255.0.0 match 127.0.0.1? no; mailutils: 6:deny: Does any match 127.0.0.1? yes; 127.0.0.1: deny *Note acl: Debugging Categories. 3.20.11 mailutils wicket ------------------------ The 'mailutils wicket' command looks up matching URLs in the Mailutils ticket file (by default, '~/.mu-tickets') and prints them. The URLs to look for are supplied in the command line. Consider the following ticket file as an example: smtp://foo:bar@* smtp://bar:baz@gnu.org *://baz:qux@* *://quux:bar@gnu.org Now, running 'mailutils wicket smtp://bar@gnu.org' will show: smtp://bar@gnu.org: /home/USER/.mailutils-tickets:2 (where USER is your login name). This means that this URL matches the line 2 in your '.mailutils-tickets' file. The 'wicket' command does not show the actual matching line to avoid revealing eventual security-sensitive information. You can instruct it to do so using the '--verbose' ('-v') option: $ mailutils wicket -v smtp://bar@gnu.org smtp://bar@gnu.org: /home/USER/.mu-tickets:2: smtp://bar:***@gnu.org As you see, even in that case the tool hides the actual password part by replacing it with three asterisks. If you are working in a secure environment, you can tell 'mu wicket' to show passwords as well, by supplying the '-v' option twice. A counterpart of '--verbose' is the '--quite' ('-q') option, which instructs 'wicket' to suppress any output, excepting error messages. This can be used in scripts, which analyze the 'mailutils wicket' exit code to alter the control flow. The 'mailutils wicket' tool exits with code 0 if all URLs were matched and with code 1 if some of them were not matched in the ticket file. If an error occurred, the code 2 is returned. 3.20.12 mailutils dbm --------------------- The 'mailutils dbm' tool manages DBM files using 'libmu_dbm' The invocation syntax is: mailutils dbm SUBCOMMAND [OPTIONS] FILE [KEYS] or mailutils dbm [OPTIONS] SUBCOMMAND FILE [KEYS] where SUBCOMMAND selects the operation mode, OPTIONS modify the tool behavior and FILE specifies the DBM file to operate upon. Some COMMANDs allow for optional KEYS to be specified. The FILE argument can be either a DBM file name or a Database URL. 3.20.12.1 Create a Database ........................... The 'create' subcommand and its synonym 'load' instruct the tool to create a new database: mailutils dbm create file.db If the argument file already exists, it will be truncated prior to adding new records to it. The data to populate the database with are read from the standard input. The 'mailutils dbm' command supports several formats for these data, which are discussed later. In the simplest case (a so called 'format 0.0') each input line must consist of two fields separated by any amount of whitespace. The first field is treated as a key and the second one as the corresponding value. The usual way to read data from a file is, of course, by redirecting the file to the standard input as in: mailutils dbm create file.db < input.txt There is also a special option for that purpose: '--file' ('-f'). Thus, the following command is equivalent to the one above: mailutils dbm create --file input.txt file.db The '--file' option has the advantage that it allows, in conjunction with another options, for copying input file metadata (owner UID, GID and file mode) to the created database. For example, the following command ensures that the created database file will have the same metadata as the input file: mailutils dbm create --file input.txt --copy-permissions file.db The '--copy-permissions' ('-P') option is the one that does the job. There are also other ways to control mode and ownership of the created database, which are described below. More advanced dump formats (e.g. 'version 1.0' format) carry additional information about the file, including its original name, ownership and mode. If input is in one of these formats, the file name argument becomes optional. If it is not supplied, the name stored in the input stream will be used. For example, supposing that the file 'users.dump' is in format 1.0, the following command suffices to restore the original filename, ownership, mode and, of course, data: mailutils dbm create --file users.dump 3.20.12.2 Add Records to a Database ................................... The 'add' subcommand adds records to a database. Records are read from the standard input and must be formatted as for 'create': mailutils dbm add file.db If the argument file does not exist, it will be created. Adding a record with a key which is already present in the database produces an error. To replace existing records, use the 'replace' subcommand instead. The same options that affect the behavior of 'create' apply to 'add' and 'replace' as well, e.g.: mailutils dbm replace --file input.txt --copy-permissions file.db 3.20.12.3 Delete Records ........................ To delete records, use the 'delete' subcommand. It reads a list of keys to delete to be specified as arguments in the command line: mailutils dbm delete file.db foo bar The command above will delete from 'file.db' records with keys 'foo' and 'bar'. It is not an error to attempt to delete a key that does not exist in the database, although such use will produce a warning message. By default, keys are matched literally. It is also possible to use various pattern matching techniques, depending on the option specified. The '--glob' ('-G') option instructs the tool to use UNIX globbing pattern matching. For example, the command below will delete all keys starting with 'foo' and ending with a decimal digit: mailutils dbm delete file.db 'foo*[0-9]' (note the quoting necessary to prevent shell from interpreting the metacharacters itself). Another option, '--regex' ('-R') instructs 'mailutils' to treat supplied keys as extended regular expressions: mailutils dbm delete --regex file.db 'foo.*[0-9]{1,3}' Both options are affected by the '--ignore-case' ('-i') option, which turns on case-insensitive matching. Using pattern matching to delete records can be a risky operation as selecting a wrong pattern will lead to removing wrong records. It is recommended to first use the list mode described below to verify that the patterns match the right keys. 3.20.12.4 List the Database ........................... The 'list' command lists the content of the database: mailutils dbm list file.db By default, entire content is listed on the standard output. If supplied more than one command line argument, this mode treats the rest of arguments after the database file name as the keys to look for and lists only records with these keys: $ mailutils dbm list file.db foo bar foo 1 bar 56 The '--glob' and '--regex' options instruct the tool to use UNIX globbing or extended regular expression matching, correspondingly. These were described in detail above. 3.20.12.5 Dump the Database ........................... The 'dump' subcommand dumps the database to the standard output in a format suitable for backup or sending over the network (a version 1.0 format). mailutils dbm dump file.db < file.dump The produced file is suitable for input to the 'create' ('load') command. Among other uses, it provides an easy way to convert databases between various formats supported by Mailutils. For example this is how to convert the database file 'file.db' to the GDBM database 'new.db': mailutils dbm dump file.db | mailutils dbm create gdbm://new.db Both 'list' and 'dump' subcommands share the same set of options. In fact, they are pretty similar, except that use different defaults. The 'list' subcommand is designed to produce a human-readable output, whereas the dump subcommand is oriented towards backup purposes. 3.20.12.6 Dump Formats ...................... As of version 3.14, 'mailutils dbm' supports two formats for dumping DBM databases. Both formats are line-oriented. Comments are introduced with a sharp ('#') sign in the column 0 of a line, followed by at least one white space character (space or tab). Sharp sign followed by a colon ('#:') introduces a "pragmatic comment", which carries some additional information to the loader. The "version 0.0" format is suitable for databases whose records contain only ASCII data. In this format, each record occupies a separate line, which consists of the key and value separated by a single TAB character. Empty lines are ignored. For example: $ mailutils list /etc/mail/users.db root guessme smith pAssword qed fooBar The output in version 0.0 format is human readable and can be used as input to the popauth utility (see popauth. However, version 0.0 has serious drawbacks. First of all, it is not suitable for databases that contain binary data. Secondly, it cannot properly handle keys beginning with a sharp sign or containing TAB. The version 1.0 format is free from these drawbacks. The "version 1.0" dump format begins with a "header" containing important information about the file, such as its file name, ownership and file mode. This information is stored in pragmatic comments and allows 'mailutils dbm load' to easily recreate an exact copy of the file. The following comments are defined: #:version=1.0 Indicates that the data that follow are in version 1.0 format. #:filename=S Original database file name, without directory parts. #:uid=N Owner UID. #:user=S Owner name. #:gid=N Owner GID #:group=S Owner group name. #:mode=O File mode in octal Following this header are actual data. Each record is output in two parts: key and value. Each part begins with a '#:len=N' construct on a line by itself, where N is the length of the data in decimal. This line is followed by one or more lines of the actual data, encoded in base64. The data are formatted so that each line does not exceed 76 bytes in length (not counting the terminating newline). An example of this format follows: # Database dump file created by GNU Mailutils 2.99.93 on # Tue Nov 1 13:28:03 2011 #:version=1.0 #:file=users.db #:uid=0,user=root,gid=25,group=mail,mode=640 #:len=6 c21pdGgA #:len=9 cEFzc3dvcmQA #:len=5 cm9vdAA= #:len=8 Z3Vlc3NtZQA= #:len=4 cWVkAA== #:len=7 Zm9vQmFyAA== 3.20.12.7 Dbm Exit Codes ........................ The table below summarizes exit codes used by 'mailutils dbm': Code Symbolic name Meaning --------------------------------------------------------------------------- 0 EX_OK Successful termination 64 EX_USAGE Command line usage error 65 EX_DATAERR Error in user-supplied data: the input file is badly formatted, or some of the data supplied in the command line are invalid (e.g. user name, uid or the like), etc. 66 EX_NOINPUT Cannot open input file 67 EX_NOUSER No such user or UID when trying to set output file ownership 69 EX_UNAVAILABLE Operation cannot be performed due to some kind of problem (e.g. access to the file denied, etc.) 70 EX_SOFTWARE Internal software error 74 EX_IOERR Input/output error 3.20.13 mailutils logger ------------------------ The 'mailutils logger' tool logs information using Mailutils log facility. Syntax: mailutils logger [OPTIONS] [MESSAGE] The MESSAGE argument, if supplied, gives the text to log. If not supplied, the utility reads lines of text from standard input or a file (if the '--file' option is given) and sends them to log: # Send text to log $ mailutils logger I am here # Log each line from file.txt $ mailutils logger --file file.txt # Read stdin and log it: $ mailutils logger The default logging channel is bound to standard error. To bind it to syslog, use the '--syslog' command line option. In that case 'mailutils' uses facility 'user' and priority 'err'. You can change this by using the '--priority' ('-p') option. Its argument is either a syslog facility name or facility and severity names separated by a dot. For example, the following invocation will use facility 'auth', severity 'info': mailutils logger --priority auth.info The syslog tag can be set using the '--tag' ('-t') option: mailutils logger --tag myprog The default tag is 'mu-logger'. The '--severity' ('-s') option sets the Mailutils severity level. Its argument can be any of the following: 'debug', 'info', 'notice', 'warning', 'error', 'crit', 'alert', 'emerg'. Finally, the '--locus' ('-l') option binds log messages to a location in a file. Its argument has the following syntax: FILE:LINE[:COL] where FILE is the file name, LINE is the line number and optional COL is the column number in that file. For example, the following invocation: mailutils logger --locus mailutils.conf:34 Suspicious statement will send the following to the log: mu-logger: mailutils.conf:34: Suspicious statement 3.20.14 mailutils pop --------------------- The 'mailutils pop' command invokes an interactive POP3 client shell. It reads commands from the standard input, executes them and displays the results on the standard output. If the standard input is connected to a terminal, the readline and history facilities are enabled (provided that Mailutils is configured with GNU Readline). The 'mailutils pop' commands form two major groups. POP3 protocol commands interact with the remote POP3 server and display responses obtained from it. These commands are named after their POP3 equivalents. Another group, "internal commands", are used to configure the shell itself. POP protocol commands ..................... connect [-tls] HOSTNAME [PORT] Open connection to HOSTNAME. If the '-tls' option is given, TLS encryption (also known as POPS protocol) will be used. If PORT argument is not given, the command uses port 110 for a plain POP connection or 995 for POPS (if '-tls' is given). stls Start TLS negotiation. This command is valid only after successful unencrypted connection has been initiated (using 'connect' without '-tls' argument). user NAME Send user name to the server. The 'pass' command must follow. pass [PASSWORD] Send password. This command is valid only after 'user'. If the PASSWORD argument is omitted, the shell will ask you to enter it. While entering, both echoing and history recording will be disabled. Use this to avoid compromising your password. apop USER [PASSWORD] Authenticate with APOP. If the PASSWORD argument is omitted, you will be asked to supply it. While entering, both echoing and history recording will be disabled. capa [-reread] [NAME...] List server capabilities. Any number of arguments is accepted. If given, the shell will display only the named capabilities, otherwise it displays entire list. By default 'capa' reuses the response of its previous invocation (if there was any), instead of resending the 'CAPA' command to the server. To force it do so, use the '-reread' option. noop Send a 'NOOP' ("no operation") command to the server. stat Get the mailbox size and number of messages in it. uidl [NUMBER] Shows unique message identifiers. Without arguments, shows identifiers for each message in the mailbox. If NUMBER is given, the command returns the UIDL of that particular message only. list [NUMBER] Lists messages. See above for the meaning of NUMBER. Each line of the produced listing contains describes a single message and contains at least the message number and size in bytes. Depending on the POP3 server implementation, additional fields may be present. For example, Mailutils 'pop3d' can also output number of lines in the message in the additional third field. retr NUMBER Retrieve a message. top MSGNO [NUMBER] Display message headers and first NUMBER (default 5) of lines of its body. dele NUMBER Mark message for deletion. rset Remove deletion marks. quit Quit pop3 session. disconnect Close existing connection. Internal commands ................. verbose [on|off|mask|unmask] [secure [payload]] Control output verbosity. Without arguments the 'verbose' command shows current settings. The argument 'off' (the default) turns off all additional output. The 'verbose on' command enables POP3 protocol tracing output. Additional arguments can be used to provide more verbosity. The 'secure' argument enables display of user passwords in the trace output and the 'payload' argument enables showing payload data (e.g. response body sent in the reply to 'RETR' command, etc.) Thus, the full diagnostics output is obtained by verbose on secure payload The 'mask' and 'unmask' arguments allow to disable and enable such additional verbosity. For example, supposing the command above is in action, the following command will suppress the display of user passwords in the traces: verbose mask secure Similarly, 'verbose unmask secure' will turn it back again. prompt STRING Set command prompt. The argument can contain "variable references" in any of the following forms: $NAME ${NAME} where NAME is the variable name. Such references are expanded to the actual value of the variable at the time of expansion. The following variables are defined: Variable Expansion -------------------------------------------------------------------------- user Login name of the authenticated POP3 user. If the session is not authenticated yet, expands to '[nouser]'. host Name of the remote host, or '[nohost]' if no connection is established. program-name Name of the program, as typed on the command line to invoke it. canonical-program-name 'mailutils' package 'Mailutils' version Mailutils version number (3.14) status Session status. One of: 'disconnected', 'connected' or 'logged in'. For example: prompt "[${user}@$host " Notice the use of quotes to include the space character in the prompt. exit Exit the program. help [COMMAND] ? [COMMAND] Without arguments displays a list of commands with possible arguments and short descriptions. With one argument, displays a terse description for the given COMMAND. history Shows command history. 3.20.15 mailutils imap ---------------------- The 'mailutils imap' command invokes an interactive IMAP4 client shell. It reads commands from the standard input, executes them and displays the results on the standard output. The shell is similar to the 'mailutils pop' (*note mailutils pop::) shell. IMAP protocol commands ...................... Most commands in this group correspond (with minor differences) to IMAP commands described in RFC 3501(1). -- imap command: connect [-tls] HOST [PORT] Opens connection to the server HOST. If the '-tls' option is given, TLS encryption (also known as IMAPS protocol) will be used. If PORT argument is not supplied, the command uses port 143 for a plain IMAP connection or 993 for IMAPS (if '-tls' is given). -- imap command: capability [-reread] [NAME...] Lists server capabilities. Any number of NAMEs is accepted. If at least one is given, the shell will display only the named capabilities, otherwise it displays the entire list. By default, 'capability' reuses the response of its previous invocation (if there was any), instead of resending the CAPABILITY command to the server. To force it do so, use the '-reread' option. -- imap command: starttls Starts TLS negotiation. This command is valid only after unencrypted connection has been successfully initiated using connect without the '-tls' option. -- imap command: login USER [PASSWORD] Logs in to the server as USER with optional PASSWORD. If the pass argument is omitted, the shell will ask you to enter it. While entering, both echoing and history recording will be disabled. Use this to avoid compromising your password. -- imap command: logout -- imap command: quit Quits the imap session. -- imap command: id [-test KW] [ARG...] Sends IMAP ID command. See RFC 2971(2), for a discussion of arguments. By default, this command outputs entire ID list. If, however, the '-test' option is given, it will check whether the keyword KW is defined and display its value if so. -- imap command: check Requests a server checkpoint. -- imap command: select [MBOX] Selects the named mailbox. Without argument, selects 'INBOX'. -- imap command: examine [MBOX] Examines the named mailbox, i.e. selects it in read-only mode. If MBOX is not given, 'INBOX' is assumed. -- imap command: status MBOX KW [KW...] Gets mailbox status. Valid keywords (KW arguments) are: 'MESSAGES', 'RECENT', 'UIDNEXT', 'UIDVALIDITY', and 'UNSEEN'. Keywords are case-insensitive. -- imap command: fetch MSGSET ITEMS Fetches message data. See RFC 3501, section 6.4.5(3), for a discussion of its arguments. -- imap command: store MSGSET ITEMS Alters mailbox data. See RFC 3501, section 6.4.6(4), for a discussion of its arguments. -- imap command: close Closes the currently selected mailbox (with expunge). -- imap command: unselect Closes the currently selected mailbox (without expunge). -- imap command: delete MBOX Deletes the mailbox MBOX. -- imap command: rename OLD-NAME NEW-NAME Renames existing mailbox OLD-NAME to NEW-NAME. -- imap command: expunge Permanently removes messages marked for deletion. -- imap command: create NAME Creates new mailbox with the given NAME. -- imap command: append [-time DATETIME] [-flag FLAG] MAILBOX FILE Reads an RFC-822 message from FILE and appends it to the MAILBOX. Use the '-time' option to supply envelope date for the message. Use the '-flag' option to supply message flags. For example: append -time "25-Aug-2002 18:00:00 +0200" -flag \Seen INBOX input.msg -- imap command: list REF MBOX Lists matching mailboxes. See RFC 3501, section 6.3.8(5), for a discussion of its arguments. -- imap command: lsub REF MBOX Lists subscribed mailboxes (RFC 3501, section 6.3.9(6)). -- imap command: subscribe MBOX Subscribes to a mailbox. -- imap command: unsubscribe MBOX Removes mailbox MBOX from the subscription list. -- imap command: noop Sends a "no operation" command. -- imap command: disconnect Closes existing connection. Internal commands ................. The 'imap' shell implements the same set of internal commands as 'pop' shell: *Note Internal commands: mailutils pop. There is only one imap-specific internal command: -- imap command: uid [on|off] Controls the UID mode. When the UID mode is on, the commands 'fetch' and 'store' operate on and return message UIDs instead of their sequence numbers. To examine the current state of the UID mode, issue the 'uid' command without arguments. ---------- Footnotes ---------- (1) See . (2) (3) (4) (5) (6) 3.20.16 mailutils send ---------------------- Reads an RFC-822 message from a file and sends it over to a specified SMTP server. The syntax is: mailutils send [OPTIONS] HOST FILE where HOST defines the SMTP server through which to send the message, and FILE is the name of the input file containing the message. For example, to send a message from file 'input.msg' using SMTP service at localhost, one would write: $ mailutils send localhost input.msg The HOST argument can be an IP address, hostname, or a valid SMTP URL. The following command line options are understood: '-F ADDRESS' '--from=ADDRESS' Supplies envelope sender address. '-T ADDRESS' '--rcpt=ADDRESS' Supplies envelope recipient address. It can be specified multiple times. '-t' '--read-recipients' Instructs the program to read recipient email addresses from the message 'To:', 'Cc:', and 'Bcc:' headers. 3.20.17 mailutils smtp ---------------------- The 'mailutils smtp' command invokes an interactive SMTP client shell. It reads commands from the standard input, executes them and displays the results on the standard output. If the standard input is connected to a terminal, the readline and history facilities are enabled (provided that Mailutils is configured with GNU Readline). Initializing connection ....................... -- smtp command: connect [-tls] HOST [PORT] Connects to SMTP server at HOST (IP address or host name). If the '-tls' option is given, TLS encryption (also known as SMTPS protocol) will be used. The default port number is 25 for plain SMTP and 465 for SMTPS. Explicit PORT argument overrides the default value. Connection parameters ..................... A number of parameters is associated with an open connection: domain Domain name used in EHLO statement. Defaults to the current host name. The following parameters are used for ESMTP authentication: username User name. password User password. service GSASL service name. realm Realm name. host Host name. url SMTP URL. It can contain all of the above. Default is smtp:// These parameters are manipulated using the following statements: -- smtp command: set PARAM VALUE [PARAM VALUE...] Sets parameter PARAM to VALUE. Several parameters can be set with one 'set' statement. -- smtp command: clear [PARAM...] Unset the supplied connection parameters. If used without arguments, unsets all parameters. -- smtp command: list [PARAM...] Lists the values of the connection parameters. If used without arguments, lists all parameters. SMTP commands ............. -- smtp command: ehlo [DOMAIN] Sends the ESMTP greeting. Unless DOMAIN is supplied, the connection parameter 'domain' is used. -- smtp command: capa [NAME...] Lists the server capabilities. -- smtp command: starttls Initiates encrypted connection. This command is disabled if the connection is opened with the '-tls' option. -- smtp command: auth MECH [MECH...] Authenticate using the supplied mechanisms. -- smtp command: rset Reset the session state. -- smtp command: from [EMAIL] Sets sender email address. If used without arguments, prints the sender email address. -- smtp command: to [EMAIL] Sets recipient email address. If used without arguments, prints all recepient names collected so far. -- smtp command: smtp COMMAND [ARGS...] Sends the COMMAND with its arguments verbatim. -- smtp command: quit Quits the SMTP session. -- smtp command: send [FILE] Reads the message from FILE and sends it. If FILE is not supplied, the action depends on whether a 'send' command was used prevously within the same session. If so, 'mailutils' will first ask whether to reuse the already supplied message. If not, it will start an editor, allowing you to enter the new message. When you exit from the editor, you will be prompted what to do with the message: send, edit, or quit (discard) it. Internal commands ................. Internal commands are the same as in 'pop' shell: *Note Internal commands: mailutils pop. 3.20.18 mailutils maildir_fixup ------------------------------- This command fixes attributes and UID assignments in 'maildir' mailboxes created by mailutils versions prior to 3.10.90. Attribute flags used in 'maildir' mailboxes by these versions of mailutils were a bit different from those described in the original description of the 'maildir' format(1) and those used by another implementations. The discrepancy has been reported in the Mailutils bug tracker(2) and was fixed in version 3.10.90. Along with this fix, measures has been taken to ensure persistence of UID assignments between different sessions. Starting from version 3.10.90, whenever 'mailutils' library opens a maildir mailbox, it determines the version that created it. If the mailbox is writable and the library determines that the mailbox is affected by the two problems described above, it fixes the mailbox on the fly. This process is completely transparent to the user. If you operate a site with a large number of mailboxes in 'maildir' formats, you may choose to fix up all of them at once. That's what the 'maildir_fixup' command is for. It takes one or more directory names as its arguments and recursively scans these directories in search for 'maildir' mailboxes. Each mailbox found is analyzed and a fix-up is performed, if necessary. If a mailbox is already in the new format, it remains untouched. The following options modify the program's behavior: '-v' '--verbose' List each maildir name before processing it. '-n' '--dry-run' Don't touch maildirs, just print their names, The 'maildir_fixup' tool reads main mailutils configuration file by default. It looks for program-specific settings in the section 'program maildir_fixup'. If the 'include' statement is present that has a directory name as its argument, the file 'maildir_fixup' is looked up in that directory and parsed, if present. The program uses the following configuration statements: Statement Reference ------------------------------------------------------------------- debug *Note debug statement::. locking *Note locking statement::. mandatory-locking See mandatory-locking statement. ---------- Footnotes ---------- (1) (2) 3.21 dotlock ============ A stand-alone mailbox-locking utility. It is the default program used by 'mailutils' if the 'locking.type' configuration statement is set to 'external' (*note external locking type::). The program usage syntax is: # To lock MBOX: dotlock OPTIONS MBOX # To unlock it: dotlock -u OPTIONS MBOX By default the program implements the 'dotlock' locking (*note dotlock locking type::). This can be changed either in the configuration file, or via the command line options. The following common configuration statements affect the behavior of 'dotlock': Statement Reference ------------------------------------------------------------------- debug *Note Debug Statement::. locking *Note Locking Statement::. The program understands the following command line options: '-d' '--debug' Print details of failure reasons to stderr. '-f[N]' '--force[=N]' If a lock file exists and is more than N minutes old, forcibly remove it and re-lock the mailbox. Default N is 10 minutes. '-p' '--pid-check' Check if the PID of lock owner is still active. If not, break the lock. '-r N' '--retry=N' Number of times to retry acquiring the lock, if it is held by another process. The default is 10 times. '-t N' '--delay=N' Sets delay in seconds between two successive locking attempts. The default is 1 second. '-u' '--unlock' Unlock the mailbox. 4 Mailutils Libraries ********************* ================================================================== *Editor's note:* This node is to be written. ================================================================== 5 Sieve Language **************** The input language understood by the GNU Sieve Library is a superset of the Sieve language as described in RFC 3028. 5.1 Lexical Structure ===================== Whitespace and Comments ----------------------- Comments are semantically equivalent to whitespace and can be used anyplace that whitespace is (with one exception in multi-line strings, as described below). There are two kinds of comments: hash comments, that begin with a '#' character that is not contained within a string and continue until the next newline, and C-style or bracketed comments, that are delimited by '/*' and '*/' tokens. The bracketed comments may span multiple lines. E.g.: if size :over 100K { # this is a comment discard; } if size :over 100K { /* this is a comment this is still a comment */ discard /* this is a comment again */ ; } Like in C, bracketed comments do not nest. Lexical Tokens -------------- The basic lexical entities are "identifiers" and "literals". An "identifier" is a sequence of letters, digits and underscores, that begins with a letter or underscore. For example, 'header' and 'check_822_again' are valid identifiers, whereas '1st' is not. A special form of identifier is "tag": it is an identifier prefixed with a colon (':'), e.g.: ':comparator'. A "literal" is a data that is not executed, merely evaluated "as is", to be used as arguments to commands. There are four kinds of literals: * Number "Numbers" are given as ordinary unsigned decimal numbers. An optional suffix may be used to indicate a multiple of a power of two. The suffixes are: 'K' specifying "kibi-", or 1,024 (2^10) times the value of the number; 'M' specifying "mebi-", or 1,048,576 (2^20) times the value of the number; and 'G' specifying "tebi-", or 1,073,741,824 (2^30) times the value of the number. The numbers have 32 bits of magnitude. * String A "string" is any sequence of characters enclosed in double quotes ('"'). A string cannot contain newlines and double quote characters. This limitation will disappear in future releases. * Multiline Strings A "multiline string" is used to represent large blocks of text with embedded newlines and special characters. It starts with the keyword 'text:' followed by a newline and ends with a dot ('.') on a newline by itself. Any characters between these two markers are taken verbatim. For example: text: ** This is an automatic response from my message ** ** filtering program. ** I can not attend your message right now. However it will be saved, and I will read it as soon as I am back. Regards, Fred . Notice that a hashed comment or whitespace may occur between 'text:' and the newline. However, when used inside the multiline string a hash sign looses its special meaning (except in one case, see below) and is taken as is, as well as bracketed comment delimiters. In other words, no comments are allowed within a multiline string. E.g.: text: # This is a comment Sample text # This line is taken verbatim /* And this line too */ . The only exception to this rule is that preprocessor 'include' statement is expanded as usual when found within a multiline string (*note Preprocessor::), e.g.: text: #include . This results in the contents of file 'myresponse.txt' being read and interpreted as the contents of the multiline string. GNU libmu_sieve extends the described syntax as follows. If the keyword 'text:' is immediately followed by a dash ('-'), then all leading tab characters are stripped from input lines and the line containing delimiter ('.'). This allows multiline strings within scripts to be indented in a natural fashion. Furthermore, if the 'text:' (optionally followed by '-') is immediately followed by a word, this word will be used as ending delimiter of multiline string instead of the default dot. For example: if header "from" "me@example.com" { reject text:-EOT I do not accept messages from this address. . . EOT # Notice that this the multiline string ends here. # The single dots above will be part of it. ; } * String Lists A "string list" is a comma-delimited list of quoted strings, enclosed in a pair of square brackets, e.g.: ["me@example.com", "me00@landru.example.edu"] For convenience, in any context where a list of strings is appropriate, a single string is allowed without being a member of a list: it is equivalent to a list with a single member. For example, the following two statements are equivalent: exists "To"; exists ["To"]; 5.2 Syntax ========== Being designed for the sole purpose of filtering mail, Sieve has a very simple syntax. 5.2.1 Commands -------------- The basic syntax element is a "command". It is defined as follows: COMMAND-NAME [TAGS] ARGS where COMMAND-NAME is an identifier representing the name of the command, TAGS is an optional list of "optional" or "tagged arguments" and ARGS is a list of "required" or "positional arguments". Positional arguments are literals delimited with whitespace. They provide the command with the information necessary to its proper functioning. Each command has a fixed number of positional arguments. It is an error to supply more arguments to the command or to give it fewer arguments than it accepts. Optional arguments allow to modify the behaviour of the command, like command line options in UNIX do. They are a list of "tags" (*note Lexical Structure::) separated by whitespace. An optional argument may have at most one parameter. Each command understands a set of optional arguments. Supplying it tags that it does not understand results in an error. For example, consider the following command header :mime :comparator "i;octet" ["to", "from"] "bug-mailutils@gnu.org" Here, given that 'header' takes two positional arguments: 'header' is command name, the list '["to", "from"]' is first positional argument and the string '"bug-mailutils@gnu.org"' is second positional argument. There are two optional arguments: ':mime' and ':comparator'. The latter has a string '"i;octet"' as its parameter. 5.2.2 Actions Described ----------------------- An "action" is a Sieve command that performs some operation over a message. Actions do the main job in any Sieve program. Syntactically, an action is a command terminated with semicolon, e.g.: keep; fileinto "mbox"; GNU Sieve provides the full set of actions described in RFC 3028. It also allows to extend this set using loadable actions. *Note Actions::, for detailed discussion of actions. 5.2.3 Control Flow ------------------ The only control flow statement Sieve has is 'if' statement. In its simplest form it is: if condition { ... } The effect of this statement is that the sequence of actions between the curly braces is executed only if the 'condition' evaluates to 'true'. A more elaborate form of this statement allows to execute two different sets of actions depending on whether the condition is true or not: if condition { ... } else { ... } The most advanced form of the "if" statement allows to select an action depending on what condition from the set of conditions is met. if cond1 { ... } elsif cond2 { ... } else { ... } There may be any number of "elsif" branches in an "if" statement. However it may have at most one "else" branch. Notes for C programmers: 1. The braces surrounding each branch of an "if" statement are required. 2. The "else if" construct is disallowed. Use "elsif" keyword instead. Here's an example of "if" statement: if header :contains "from" "coyote" { discard; } elsif header :contains ["subject"] ["$$$"] { discard; } else { fileinto "INBOX"; } The following section describes in detail conditions used in "if" statements. 5.2.4 Tests and Conditions -------------------------- "Tests" are Sieve commands that return boolean value. E.g. the test header :contains "from" "coyote" returns true only if the header "From" of the current message contains substring "coyote". The tests shipped with the GNU Sieve are described in *note Tests::. "Condition" is a Sieve expression that evaluates to 'true' or 'false'. In its simplest form, condition is just a Sieve test. To reverse the sense of a condition use keyword 'not', e.g.: not header :contains "from" "coyote" The results of several conditions may be joined together by logical 'and' and 'or' operations. The special form 'allof' takes several tests as its arguments and computes the logical 'and' of their results. Similarly, the form 'anyof' performs logical 'or' over the results of its arguments. E.g.: if anyof (not exists ["From", "Date"], header :contains "from" "fool@example.edu") { discard; } 5.3 Preprocessor ================ Preprocessor statements are a GNU extension to the Sieve language. The syntax for a preprocessor statement is similar to that used in 'C' programming language, i.e. a pound character ('#') followed by a preprocessor directive and its arguments. Any amount of whitespace can be inserted between the '#' and the directive. Currently implemented directives are 'include' and 'searchpath'. 5.3.1 Sieve #include directive ------------------------------ The '#include' directive reads in the contents of the given file. The contents is "inserted" into the text being parsed starting at the line where the directive appears. The directive takes two forms: '#include "FILENAME"' The FILENAME is taken relative to the current directory. '#include "' The FILENAME is searched in the list of include directories as specified by the '-I' command line options. If FILENAME starts with a directory separator character ('/') both forms have the same effect. 5.3.2 Sieve #searchpath directive --------------------------------- The '#searchpath' directive adds its argument to the list of directories searched for loadable modules. It has the same effect as 'library-path' Sieve configuration statement (*note library-path: Sieve Configuration.). 5.4 Require Statement ===================== Syntax: require STRING; require STRING-LIST; The require statement informs the parser that a script makes use of a certain extension. Multiple capabilities can be declared using the second form of the statement. The actual handling of a capability name depends on its suffix. If the name starts with 'comparator-', it is understood as a request to use the specified comparator. The comparator name consists of the characters following the suffix. If the name starts with 'test-', it means a request to use the given test. The test name consists of the characters following the suffix. Otherwise, the capability is understood as a name of an action to be used. The 'require' statement, if present, must be used before any other statement that is using the required capability. As an extension, the GNU sieve allows the 'require' and any other statements to be interspersed. By default the following actions and comparators need not be explicitly required: * stop * keep * discard * i;octet * i;ascii-casemap Example: require ["fileinto", "reject"]; require "fileinto"; require "comparator-i;ascii-numeric"; When processing arguments for 'require' statement, GNU libmu_sieve uses the following algorithm: 1. Look up the name in a symbol table. If the name begins with 'comparator-' it is looked up in the comparator table. If it begins with 'test-', the test table is used instead. Otherwise the name is looked up in the action table. 2. If the name is found, the search is terminated. 3. Otherwise, transform the name. First, any 'comparator-' or 'test-' prefix is stripped. Then, any character other than alphanumeric characters, '.' and ',' is replaced with dash ('-'). The name thus obtained is used as a file name of an external loadable module. 4. Try to load the module. The module is searched in the following search paths (in the order given): 1. Mailutils module directory. By default it is '$prefix/lib/mailutils'. 2. Sieve library path as given with the '-L' options in the command line 3. Additional search directories specified with the '#searchpath' directive. 4. The value of the environment variable 'LTDL_LIBRARY_PATH'. 5. System library search path: The system dependent library search path (e.g. on Linux it is set by the contents of the file '/etc/ld.so.conf' and the value of the environment variable 'LD_LIBRARY_PATH'). The value of 'LTDL_LIBRARY_PATH' and 'LD_LIBRARY_PATH' must be a colon-separated list of absolute directories, for example, '"/usr/lib/mypkg:/lib/foo"'. In any of these directories, 'libmu_sieve' first attempts to find and load the given filename. If this fails, it tries to append the following suffixes to the file name: 1. the libtool archive extension '.la' 2. the extension used for native dynamic libraries on the host platform, e.g., '.so', '.sl', etc. 5. If the module is found, 'libmu_sieve' executes its initialization function (see below) and again looks up the name in the symbol table. If found, search terminates successfully. 6. If either the module is not found, or the symbol wasn't found after execution of the module initialization function, search is terminated with an error status. 'libmu_sieve' then issues the following diagnostic message: source for the required action NAME is not available 5.5 Comparators =============== GNU libmu_sieve supports the following built-in comparators: 'i;octet' This comparator simply compares the two arguments octet by octet 'i;ascii-casemap' It treats uppercase and lowercase characters in the ASCII subset of UTF-8 as the same. This is the default comparator. 'i;ascii-numeric' Treats the two arguments as ASCII representation of decimal numbers and compares their numeric values. This comparator must be explicitly required prior to use. 5.6 Tests ========= This section describes the built-in tests supported by GNU libmu_sieve. In the discussion below the following macro-notations are used: MATCH-TYPE This tag specifies the matching type to be used with the test. It can be one of the following: ':is' The ':is' match type describes an absolute match; if the contents of the first string are absolutely the same as the contents of the second string, they match. Only the string "frobnitzm" is the string "frobnitzm". The null key ":is" and only ":is" the null value. This is the default match-type. ':contains' The ':contains' match type describes a substring match. If the value argument contains the key argument as a substring, the match is true. For instance, the string "frobnitzm" contains "frob" and "nit", but not "fbm". The null key "" is contained in all values. ':matches' The ':matches' version specifies a wildcard match using the characters '*' and '?'. '*' matches zero or more characters, and '?' matches a single character. '?' and '*' may be escaped as '\\?' and '\\*' in strings to match against themselves. The first backslash escapes the second backslash; together, they escape the '*'. ':regex' The ':regex' version specifies a match using POSIX Extended Regular Expressions. ':value RELATION' The ':value' match type does a relational comparison between strings. Valid values for RELATION are: "eq" Equal "ne" Not Equal "gt" Greater Than "ge" Greater than or Equal "lt" Less Than "le" Less than or Equal ':count RELATION' This match type first determines the number of the specified entities (headers, addresses, etc.) in the message and does a relational comparison of the number of entities to the values specified in the test expression. The test expression must be a list of one element. COMPARATOR A COMPARATOR syntax item is defined as follows: :comparator "COMPARATOR-NAME" It instructs sieve to use the given comparator with the test. If COMPARATOR-NAME is not one of 'i;octet', 'i;ascii-casemap' it must be required prior to using it. For example: require "comparator-i;ascii-numeric"; if header :comparator "i;ascii-numeric" :is "X-Num" "10" { ... ADDRESS-PART This syntax item is used when testing structured Internet addresses. It specifies which part of an address must be used in comparisons. Exactly one of the following tags may be used: ':all' Use the whole address. This is the default. ':localpart' Use local part of the address. ':domain' Use domain part of the address. _Notice_, that MATCH-TYPE modifiers interact with comparators. Some comparators are not suitable for matching with ':contains' or ':matches'. If this occurs, sieve issues an appropriate error message. For example, the statement: if header :matches :comparator "i;ascii-numeric" would result in the following error message: comparator `i;ascii-numeric' is incompatible with match type `:matches' in call to `header' GNU Sieve supports two kinds of tests. "Built-in tests" are defined within the library and do not require any external files. "External tests" are loadable modules that can be linked in at run time using the 'require' statement (*note Require Statement::). 5.6.1 Built-in Tests -------------------- -- Test: false This test always evaluates to "false". -- Test: true This test always evaluates to "true". -- Test: address [ADDRESS-PART] [COMPARATOR] [MATCH-TYPE] HEADER-NAMES KEY-LIST Tagged arguments: ADDRESS-PART Selects the address part to compare. Default is the whole email address (':all'). COMPARATOR Specifies the comparator to be used instead of the default 'i;ascii-casemap'. MATCH-TYPE Specifies the match type to be used instead of the default ':is'. Required arguments: HEADER-NAMES A list of header names. KEY-LIST A list of address values. The 'address' test matches Internet addresses in structured headers that contain addresses. It returns 'true' if any header contains any key in the specified part of the address, as modified by COMPARATOR and MATCH-TYPE optional arguments. This test returns 'true' if any combination of the HEADER-NAMES and KEY-LIST arguments match. The 'address' primitive never acts on the phrase part of an email address, nor on comments within that address. Use the 'header' test instead. It also never acts on group names, although it does act on the addresses within the group construct. Example: if address :is :all "from" "tim@example.com" { discard; } -- Test: size [:over | :under] LIMIT(number) The 'size' test deals with the size of a message. The required argument LIMIT represents the size of the message in bytes. It may be suffixed with the following quantifiers: 'k' 'K' The number is expressed in kilobytes. 'm' 'M' The number is expressed in megabytes. 'g' 'G' The number is expressed in gigabytes. If the tagged argument is ':over', and the size of the message is greater than NUMBER, the test is true; otherwise, it is false. If the argument is ':under', and the size of the message is less than the NUMBER, the test is true; otherwise, it is false. Otherwise, the test is true only if the size of the message equals exactly NUMBER. This is a GNU extension. The size of a message is defined to be the number of octets from the initial header until the last character in the message body. -- Test: envelope [ADDRESS-PART] [COMPARATOR] [MATCH-TYPE] ENVELOPE-PART(string-list) KEY-LIST(string-list) Tagged arguments: ADDRESS-PART Selects the address part to compare. Default is the whole email address (':all'). COMPARATOR Specifies the comparator to be used instead of the default 'i;ascii-casemap'. MATCH-TYPE Specifies the match type to be used instead of the default ':is'. Required arguments: ENVELOPE-PARTS A list of envelope parts to operate upon. KEY-LIST A list of address values. The 'envelope' test is true if the specified part of the SMTP envelope matches the specified key. If the envelope-part strings is (case insensitive) 'from', then matching occurs against the FROM address used in the 'SMTP MAIL' command. _Notice_, that due to the limitations imposed by SMTP envelope structure the use of any other values in ENVELOPE-PARTS header is meaningless. -- Test: exists HEADER-NAMES(string-list) Required arguments: HEADER-NAMES List of message header names. The 'exists' test is 'true' if the headers listed in HEADER-NAMES argument exist within the message. All of the headers must exist or the test is false. The following example throws out mail that doesn't have a From header and a Date header: if not exists ["From","Date"] { discard; } -- Test: header [COMPARATOR] [MATCH-TYPE] [:mime] HEADER-NAMES(string-list) KEY-LIST(string-list) Tagged arguments: COMPARATOR Specifies the comparator to be used instead of the default 'i;ascii-casemap'. MATCH-TYPE Specifies the match type to be used instead of the default ':is'. :mime This tag instructs 'header' to search through the mime headers in multipart messages as well. Required arguments: HEADER-NAMES A list of header names. KEY-LIST A list of header values. The 'header' test evaluates to true if any header name matches any key. The type of match is specified by the optional match argument, which defaults to ":is" if not explicitly given. The test returns 'true' if any combination of the HEADER-NAMES and KEY-LIST arguments match. If a header listed in HEADER-NAMES exists, it contains the null key ('""'). However, if the named header is not present, it does not contain the null key. So if a message contained the header X-Caffeine: C8H10N4O2 these tests on that header evaluate as follows: header :is ["X-Caffeine"] [""] => false header :contains ["X-Caffeine"] [""] => true 5.6.2 External Tests -------------------- -- Test: numaddr [:over | :under] HEADER-NAMES(string-list) COUNT(number) Synopsis: require "test-numaddr"; ... if numaddr ARGS { ... } Description: This test is provided as an example of loadable extension tests. You must use 'require "test-numaddr"' statement before actually using it. The 'numaddr' test counts Internet addresses in structured headers that contain addresses. It returns true if the total number of addresses satisfies the requested relation. If the tagged argument is ':over' and the number of addresses is greater than COUNT, the test is true; otherwise, it is false. If the tagged argument is ':under' and the number of addresses is less than COUNT, the test is true; otherwise, it is false. If the tagged argument is not given, ':over' is assumed. -- Test: pipe [:envelope] [:header] [:body] [:exit CODE(number)] [:signal CODE(number)] COMMAND(string) Synopsis: require "test-pipe"; if pipe COMMAND { ... } Description: The 'pipe' test executes a shell command specified by its argument and pipes the entire message (including envelope) to its standard input. When given, tags ':envelope', ':header', and ':body' control what parts of the message to pipe to the command. In the absence of the ':exit' tag, the test returns true if the command exits with code 0. If ':exit' is given, the test returns true if the command exits with code equal to its argument. The ':signal' tag determines the result of the test in case if the program exits on signal. By default, the test returns false. If ':signal' is given and the number of signal which caused the program to terminate matches its argument, the test returns true. -- Test: spamd [:host TCP-HOST(string)] [:port TCP-PORT(number)] [:socket UNIX-SOCKET(string)] [:user NAME(string)] [:over | :under LIMIT(string)] Synopsis: require "test-spamd"; ... if spamd ARGS { # This is spam ... } Description: This test is an interface to SpamAssassin filter. It connects to the 'spamd' daemon using connection parameters specified by tagged arguments ':host' and ':port' (if the daemon is listening on an INET socket), or ':socket' (if the daemon is listening on a UNIX socket) and returns true, if SpamAssassin qualifies the message as spam. Tagged argument LIMIT alters the default behavior. Its value is a string representation of a floating point number. If the tag ':over' is used, then the test returns true if the spam score returned from SpamAssassin is greater than LIMIT. Otherwise, if ':under' is used, the test returns true if the spam score is less than LIMIT. The comparison takes into account three decimal digits. Tagged argument ':user' allows to select a specific user profile. If it is not given, the user name is determined using the effective UID. Before returning, the 'spamd' test adds the following headers to the message: X-Spamd-Status 'YES' or 'NO', depending on whether the message is qualified as spam or ham. X-Spamd-Score Actual spam score value. X-Spamd-Threshold Spam score threshold, as configured in SpamAssassin settings. X-Spamd-Keywords Comma-separated list of keywords, describing the spam checks that succeeded for this message. Example: request "test-spamd"; if spamd :host 127.0.0.1 :port 3333 { discard; } -- Test: list [COMPARATOR] [MATCH-TYPE] [ :delim DELIMITERS(string) ] HEADERS(string-list) KEYS(string-list) Synopsis: require "test-list"; if list ARGS { ... } Description: The 'list' test evaluates to true if any of HEADERS matches any key from KEYS. Each header is regarded as containing a list of keywords. By default, comma is assumed as list separator. This can be overridden by specifying the ':delim' tag, whose value is a string consisting of valid list delimiter characters. Example: This test can be used in conjunction with the 'spamd' test described above: require ["fileinto", "test-spamd", "test-list"]; if spamd :host 127.0.0.1 :port 3333 { if list :matches :delim " ," "X-Spamd-Keywords" [ "HTML_*", "FORGED_*" ] { fileinto "~/mail/spam"; } else { discard; } } -- Test: timestamp [:before | :after] HEADER(string) DATE(string) Synopsis: require "test-timestamp"; if timestamp ARG { ... } Description: The 'timestamp' test compares the value of a structured date header field (HEADER) with the given date (DATE). If the tagged argument is ':after' and the date from the header is after the specified date the result is true, otherwise, if the header date is before the given date, the result is false. If the tagged argument is ':before' and the date from the header is before the specified date the result is true, otherwise, if the header date is after the given date, the result is false. If no tagged argument is supplied, ':after' is assumed. Almost any date format is understood. *Note Date Input Formats::, for a detailed information on date formats. Example: The test below succeeds if the date in 'X-Expire-Timestamp' header is more than 5 days older than the current date: require "test-timestamp"; if timestamp :before "X-Expire-Timestamp" "now - 5 days" { discard; } 5.7 Actions =========== There are two groups of GNU Sieve actions: "built-in actions", which are defined within the library, and "external actions", i.e. loadable modules that can be linked in at run time using the 'require' statement (*note Require Statement::). 5.7.1 Built-in Actions ---------------------- The GNU libmu_sieve supports the following built-in actions: * stop * keep * discard * fileinto * reject * redirect Among them the first three actions do not need to be explicitly required by a 'require' statement, while the others do. These actions are described in detail below. -- Action: stop The 'stop' action ends all processing. If no actions have been executed, then the 'keep' action is taken. -- Action: keep The effect of this action is to preserve the current message in the mailbox. This action is executed if no other action has been executed. -- Action: discard 'Discard' silently throws away the current message. No notification is returned to the sender, the message is deleted from the mailbox. Example: if header :contains ["from"] ["idiot@example.edu"] { discard; } -- Action: fileinto [:permissions MODE] FOLDER Required arguments: FOLDER A string representing the folder name Tagged arguments: ':permissions MODE' Specifies the permissions to use, if the mailbox is created. The 'fileinto' action delivers the message into the specified folder. If the folder is local, it is created using permissions '0600', for regular files, and '0700' for directories. This default can be changed by using the ':permissions' tag. Its argument is a mode specification, similar to that used by 'chmod' shell utility. It is a list of permissions settings separated by commas. Each setting begins with one of the following letters: g Set permissions for the users in the file group. o Set permissions for users not in the file's group. This letter must be followed by either '+' or '=' and the list of permissions to be set. This latter list is a string containing any one or both of the following characters: r Grant permission to read. w Grant permission to write. For example, the following instruction creates the mailbox '~/shared' which will be world readable and writable for the group: fileinto :permissions "g=rw,o=r" "~/shared" Notice that: 1. The ':permissions' setting are affected by the current umask value. 2. Only 'r' and 'w' permissions can be set, since other permissions do not seem to be useful for mailboxes. However, for mailboxes that have a directory structure (such as maildir and MH), any settings in 'g' and 'o' sets imply setting the executable bit. 3. Owner's permissions cannot be set. The owner always has all permissions on the mailbox he created. 4. The ':permissions' settings apply only to local mailboxes. They are ignored for remote mailboxes. -- Action: reject REASON The optional 'reject' action refuses delivery of a message by sending back a message delivery notification to the sender. It resends the message to the sender, wrapping it in a "reject" form, noting that it was rejected by the recipient. The required argument REASON is a string specifying the reason for rejecting the message. Example: If the message contained Date: Tue, 1 Apr 1997 09:06:31 -0800 (PST) From: coyote@desert.example.org To: roadrunner@acme.example.com Subject: I have a present for you I've got some great birdseed over here at my place. Want to buy it? and the user's script contained: if header :contains "from" "coyote@desert.example.org" { reject "I am not taking mail from you, and I don't want your birdseed, either!"; } then the original sender would receive the following notification: To: X-Authentication-Warning: roadrunner set sender using -f flag Content-Type: multipart/mixed; boundary=----- =_aaaaaaaaaa0 MIME-Version: 1.0 ----- =_aaaaaaaaaa0 The original message was received at Tue, 1 Apr 1997 09:07:15 -0800 from coyote@desert.example.org. Message was refused by recipient's mail filtering program. Reason given was as follows: I am not taking mail from you, and I don't want your birdseed, either! ----- =_aaaaaaaaaa0 Content-Type: message/delivery-status Reporting-UA: sieve; GNU Mailutils 0.1.3 Arrival-Date: Tue, 1 Apr 1997 09:07:15 -0800 Final-Recipient: RFC822; roadrunner@acme.example.com Action: deleted Disposition: automatic-action/MDN-sent-automatically;deleted Last-Attempt-Date: Tue, 1 Apr 1997 09:07:15 -0800 ----- =_aaaaaaaaaa0 Content-Type: message/rfc822 From: coyote@desert.example.org To: roadrunner@acme.example.com Subject: I have a present for you I've got some great birdseed over here at my place. Want to buy it? ----- =_aaaaaaaaaa0 If the REASON argument is rather long, the common approach is to use the combination of the 'text:' and '#include' keywords, e.g.: if header :mime :matches "Content-Type" [ "*application/msword;*", "*audio/x-midi*" ] { reject text: #include "nomsword.txt" . ; } -- Action: redirect ADDRESS The 'redirect' action is used to send the message to another user at a supplied ADDRESS, as a mail forwarding feature does. This action makes no changes to the message body or existing headers, but it may add new headers. It also modifies the envelope recipient. The 'redirect' command performs an MTA-style "forward" -- that is, what you get from a '.forward' file using 'sendmail' under UNIX. The address on the SMTP envelope is replaced with the one on the 'redirect' command and the message is sent back out. _Notice_, that it differs from the MUA-style forward, which creates a new message with a different sender and message ID, wrapping the old message in a new one. 5.7.2 External Actions ---------------------- GNU Mailutils is shipped with a set of external Sieve actions. These actions are compiled as loadable modules and must be required prior to use (*note Require Statement::). -- Action: moderator [:keep] [:address ADDRESS(string)] [:source SIEVE-FILE(string)] [:program SIEVE-TEXT(string)] Synopsis: require "moderator" moderator ARGS; Description: This action is a moderator robot for Mailman-driven mail archives. A Mailman moderation request is a MIME message consisting of the following three parts: N Content-Type Description --------------------------------------------------------------------------- 1 text/plain Introduction for the human reader. 2 message/rfc822 Original submission. 3 message/rfc822 Mailman control message. Replying to part 3 (keeping the subject intact) instructs Mailman to discard the original submission. Replying to part 3 while adding an 'Approved:' header with the list password in it approves the submission. The 'moderator' action spawns an inferior Sieve machine and filters the original submission (part 2) through it. If the inferior machine marks the message as deleted, the action replies to the control message, thereby causing the submission to be discarded. The 'From:' address of the reply can be modified using ':address' tag. After discarding the message, 'moderator' marks it as deleted, unless it is given ':keep' tag. If the ':source' tag is given, its argument specifies a Sieve source file to be used on the message. Otherwise, if ':program' is given, its argument supplies a Sieve program to be used on this message. At most one of these tags may be specified. Supplying them both, or supplying several instances of the same tag, is an error. The behavior of the action in this case is undefined. If neither ':program' nor ':source' is given, 'moderator' will create a copy of the existing Sieve machine and use it on the message. The action checks the message structure: it will bail out if the message does not have exactly 3 MIME parts, or if parts 2 and 3 are not of 'message/rfc822' type. It is the responsibility of the caller to make sure the message is actually a valid Mailman moderation request (see the example below). Example: if allof(header :is "Sender" "mailman-bounces@gnu.org", header :is "X-List-Administrivia" "yes") { moderator :source "~/.sieve/mailman.sv"; } -- Action: pipe [:envelope] [:header] [:body] COMMAND(string) Synopsis: require "pipe"; pipe COMMAND Description: The 'pipe' action executes a shell command specified by its argument and pipes the entire message (including envelope) to its standard input. When given, tags ':envelope', ':header', and ':body' control what parts of the message to pipe to the command. Example: The example below uses the 'putmail' utility (*note putmail::) to forward the message to user 'gray' on the machine 'mail.gnu.org'. require "pipe"; pipe "/usr/bin/putmail smtp://gray@mail.gnu.org" -- Action: vacation [:days NDAYS(number)] [:subject SUBJECT(string)] [:aliases ADDRLIST(string-list)] [:noreply NOREPLY-ADDRESS(string-list)] [:reply_regex EXPR(string)] [:reply_prefix PREFIX(string)] [:sender EMAIL(string)] [:database PATH(string)] [:return_address EMAIL(string)] [:header HEADERS(string-list)] [:mime] [:always_reply] [:rfc2822] [:file] TEXT(string) Syntax: require "vacation"; vacation ARGS; Description: The 'vacation' action returns a message with TEXT to the sender. It is intended to inform the sender that the recipient is not currently reading his mail. If the ':file' tag is present, TEXT is treated as the name of the file to read the body of the reply message from. When used together with tag ':rfc2822', the file should be formatted as a valid RFC 2822 message, i.e. headers followed by empty line and body. Headers may not contain 'To', 'From', and 'Subject', as these will be generated automatically. If the ':subject' tag is given, its argument sets the subject of the message. Otherwise, the subject is formed by prefixing original subject with 'Re:', or the PREFIX given with the ':reply_prefix' tag. Before prefixing, any original prefixes matching extended regular expression EXPR (':reply_regex' tag) are stripped from the subject line. If ':reply_regex' is not specified, the default regexp is '^re: *'. Another headers can be added using the ':header' tag. Its argument is a list of header strings, each one having the form '"NAME:VALUE"'. Additional whitespace is allowed on both sides of the colon. The ':aliases' tag instructs 'vacation' to handle messages for any address in ADDRLIST in the same manner as those received for the user's principal email. Before processing, 'vacation' compares the sender address with its "address exclusion list". Elements of this list are extended case-insensitive regular expressions. If the sender address matches any of these expressions, the message will not be replied. The default exclusion list is: .*-REQUEST@.* .*-RELAY@.* .*-OWNER@.* ^OWNER-.* ^postmaster@.* ^UUCP@.* ^MAILER@.* ^MAILER-DAEMON@.* New entries can be added to this list using ':noreply' tag. The ':days' tag sets the "reply interval". A reply is sent to each sender once in NDAYS days. GNU Sieve keeps track of sender addresses and dates in file '.vacation' stored in the user's home directory. The file name can be changed using the ':database' tag. The tag ':always_reply' instructs vacation to respond to the message regardless of whether the user email is listed as a recipient for the message. 5.8 Extensions ============== The following extensions are implemented 5.8.1 The encoded-character extension ------------------------------------- The 'encoded-character' extension complies with 'RFC 5228', part 2.4.2.4. It provides a way of incorporating multibyte sequences in a Sieve script using only ASCII characters. This is a built-in extension. It is enabled using the following statement: require "encoded-character"; When this extension is enabled, the sequences '${hex: ...}', and '${unicode: ...}' can appear inside of quoted strings. The sequence ${hex: XX} where XX is a sequence of one or two-digit hex numbers separated by any amount of whitespace, is replaced with the octets with the hexadecimal values given by each hex number. For example, "${hex: 24 24}" => "$$" Thus, the following script will discard any message containing three contiguous dollar signs in its 'Subject' header: require "encoded-character"; if header :contains "Subject" "$${hex:24 24}" { discard; } The 'hex:' keyword is case-insensitive. If XX contains invalid hex numbers, the entire sequence is left verbatim. This is illustrated by the following example: "$${hex:40}" => "$@" "${hex: 40 }" => "@" "${HEX: 40}" => "@" "${hex:40" => "${hex:40" "${hex:400}" => "${hex:400}" "${hex:4${hex:30}}" => "${hex:40}" The sequence ${unicode: HEXNUM} where HEXNUM is a list of hexadecimal numbers separated with whitespace, will be replaced by the UTF-8 encoding of the specified Unicode characters, which are identified by the hexadecimal value of HEXNUM. For example, the following string represents a single '@' sign: "${UNICODE:40}" Similarly to 'hex:', the 'unicode:' indicator is case insensitive. The following examples demonstrate the handling of several valid and invalid encodings: "${unicode:40}" => "@" "${ unicode:40}" => "${ unicode:40}" "${UNICODE:40}" => "@" "${UnICoDE:0000040}" => "@" "${Unicode:40}" => "@" "${Unicode:Cool}" => "${Unicode:Cool}" "${unicode:200000}" => error "${Unicode:DF01} => error 5.8.2 The relational extension ------------------------------ The 'relational' extension complies with 'RFC 3431'. It is a built-in extension. When enabled, the two new match types become available: ':count' and ':value'. Both keywords take a single argument defining the relational operator to use: '"gt"' greater than ('>') '"ge"' greater than or equal ('>=') '"lt"' less than ('<') '"le"' less than or equal ('<=') '"eq"' equal to ('==') '"ne"' not equal to ('!=') The ':value' keyword requires a relational comparison between strings. The left side of the relation is formed by the value from the message. The right side of the relation is the value from the test expression. If there are multiple values on either side or both sides, the test is considered true if any pair is true. For example, require ["relational", "fileinto"]; if header :value "gt" :comparator "i;ascii-numeric" ["x-spam-level] ["5"] { fileinto "spam"; } The ':count' keyword counts the specified entities in the message and compares their number with the value given in the test expression. The latter must be a list of one element. This match type can only be used with numeric comparators. For example, the following script will discard any message with 10 or more recipient addresses in the 'To' and 'Cc' headers: require "relational"; if address :count "ge" :comparator "i;ascii-numeric" ["to", "cc"] ["10"] { discard; } 5.8.3 The variables extension ----------------------------- The 'variables' extension is defined in 'RFC 5229'. It is a built-in extension. It introduces support for variables in Sieve scripts. There are two kind of variables: user-defined and match variables. A "user-defined" variable is initialized using the 'set' action: -- Action: set [MODIFIERS] NAME(string) VALUE(string) Stores the specified VALUE in the variable identified by NAME. Optional MODIFIERS are applied on VALUE before it is stored in the variable. The following modifiers are available: ':lower' Convert value to lower case letters. ':upper' Convert value to upper case letters. ':lowerfirst' Convert the first character in value to lower case. ':upperfirst' Convert the first character in value to upper case. ':quotewildcard' Quote wildcard characters ('*', '?', '\') by prefixing each occurrence with a backslash ('\'). This can be used to ensure that the variable will only match a literal occurrence if used as a parameter to ':matches'. ':length' The value is the decimal number of characters in the expansion, converted to a string. When several modifiers are present, they are applied in the following order of precedence (largest value first): precedence modifiers -------------------------------------------------------------------------- 40 ':lower' or ':upper' 30 ':lowerfirst' or ':upperfirst' 20 ':quotewildcard' 10 ':length' Modifiers having the same precedence (i.e. listed on the same row in the above table) cannot be used together. Variables are referenced within text strings using the construct '${NAME}', where NAME is the name of the variable as it appeared in the first parameter to the 'set' statement. For example: require "variables"; set "sender" "root ": if envelope :matches "${sender}" { ... } "Match variables" refer to parts of the most recently evaluated successful match of type ':matches' or ':regex'. They have names consisting entirely of decimal digits. The variable '${0}' refers to the entire matched expression. The variable '${1}' refers to the substring matching the first occurrence of the wildcard ('?' and '*'), '${2}' refers to the second occurrence and so on. The wildcards match as little as possible (non-greedy matching). For example: require ["variables", "fileinto"]; if header :matches "List-ID" "*<* " { fileinto "INBOX.lists.${2}"; stop; } If ':regex' match is used, the match variables starting from '${1}' refer to the substrings of the argument value matching subsequent parenthesized groups of the regular expression. -- Test: string [COMPARATOR] [MATCH-TYPE] SOURCE(string-list) KEYS(string-list) The 'string' test compares two strings according to the selected comparator and match type. The test evaluates to 'true' if any two strings from SOURCE and KEYS match. The ':count' match used in 'string' counts each empty string as 0, and each non-empty one as 1. The count of a string list is the sum of the counts of the member strings. 5.8.4 environment ----------------- The 'environment' extension complies with 'RFC 5183'. It is a built-in extension. It introduces the following test: -- Test: environment [COMPARATOR] [MATCH-TYPE] NAME(string) KEYS(string-list) The 'environment' test evaluates to 'true' if the value of the environment items NAME matches any string from KEYS. The following environment items are defined: domain The primary DNS domain of the machine where the Sieve script is executing. host The fully-qualified domain name of the host where the Sieve script is executing. location Type of service that is evaluating the script. Depending on the utility that is evaluating the script it is: Utility Location -------------------------------------------------------------------------- sieve '"MUA"', or set with the '--environment' option. maidag '"MDA"' inc '"MUA"' name The string 'GNU Mailutils' phase The point relative to final delivery where the Sieve script is being evaluated. Depending on the utility that is evaluating the script it is: Utility Location -------------------------------------------------------------------------- sieve 'post' unless set with the '--environment' option. maidag '"during"' inc '"post"' version Mailutils version string (e.g. '3.14'). 5.8.5 The numaddr extension --------------------------- This is an example loadable extension. *note numaddr: External Tests. 5.8.6 The editheader extension ------------------------------ The 'editheader' extension complies with 'RFC 5293'. It provides the following actions: -- Action: addheader [:last] FIELD-NAME(string) VALUE(string) Adds a header field to the existing message header. By default the header is inserted at the beginning of the header list. If the tag ':last' is specified, it is appended at the end. -- Action: deleteheader" [:index FIELDNO(number) :last] [COMPARATOR] [MATCH-TYPE] FIELD-NAME(string) [VALUE-PATTERNS(string-list)] Deletes occurrences of the header field matching the criteria. The VALUE-PATTERNS, if specified, determines which occurrences of the header fielde to delete. If not supplied, COMPARATOR and MATCH-TYPE are silently ignored. If ':index FIELDNO' is specified, only the numbered occurrence of the named header field will be matched (header numbering begins at 1), If ':last' is specified, the count is backwards; 1 denotes the last named header field, 2 the second to last, and so on. The counting happens before the VALUE-PATTERNS match, if any. Thus, e.g. the action deleteheader :index 1 :contains "Delivered-To" "bob@example.com"; would delete the first 'Delivered-To' header field if it contains the string 'bob@example.com'. 5.8.7 The list extension ------------------------ *note list: External Tests. 5.8.8 The moderator extension ----------------------------- A loadable extension implementing a moderator robot for Mailman-driven mail archives. *note moderator: External Actions. 5.8.9 The pipe extension ------------------------ A loadable extension for external command execution. It provides the 'pipe' action (*note pipe: External Actions.) and test (*note pipe: External Tests.). 5.8.10 The spamd extension -------------------------- Implements a test which interfaces to SpamAssassin filter. This is a loadable extension. *note spamd: External Tests. 5.8.11 The timestamp extension ------------------------------ The loadable extension 'timestamp' implements a test for comparing the value of a structured date header field with the given date. Note: this extension will probably phase away in favor of the 'date' Sieve extension ('RFC 5260'). 5.8.12 The vacation extension ----------------------------- The loadable extension 'vacation' provides the action intended to inform the sender that the recipient is not currently reading his mail. *Note vacation: External Actions. 5.9 GNU Extensions ================== This section summarizes the GNU extensions to the sieve language 1. Multiline strings syntax GNU libmu_sieve understands the following multiline string syntax: text:[-][DELIMITER] .... DELIMITER The meaning of optional flags is the same as in shell "here document" construct: the dash strips all leading tab characters from the string body, thus allowing it to be indented in a natural fashion; DELIMITER introduces the new end-of-text delimiter instead of the default dot. If DELIMITER starts with a backslash, no preprocessing will be performed within a string. 2. Handling of the 'require' statement. * According to the RFC an error must occur if a 'require' appears after a command other than 'require'. The GNU sieve library allows interspersing the 'require' and other statements. The only requirement is that 'require' must occur before a statement that is using the required capability (*note Require Statement::). * Prefixing the required capability with "test" requires the use of an extension test. 3. 'header' test The 'header' takes an optional argument ':mime', meaning to scan the headers from each part of a multipart message. 4. 'size' test The 'size' test allows to omit the optional argument (:over|:under). In this case exact equality is assumed. 5. 'envelope' test The only value that can be meaningfully used as the first required argument of an 'envelope' test is 'from'. This limitation may disappear from the subsequent releases. 6. 'fileinto' action The 'fileinto' action allows to specify permissions on the mailbox, in case it will be created (*note fileinto::). 7. Match type optional argument. Along with the usual ':is', ':matches' and ':contains' matching type, GNU sieve library understands ':regex' type. This matching type toggles POSIX Extended Regular Expression matching. 6 Reporting Bugs **************** Email bug reports to . As the purpose of bug reporting is to improve software, please be sure to include maximum information when reporting a bug. The information needed is: * Version of the package you are using. * Compilation options used when configuring the package. * Conditions under which the bug appears. The archives of bug-mailutils mailing list are available from . 7 Getting News About GNU Mailutils ********************************** The two places to look for any news regarding GNU Mailutils are the Mailutils homepage at or , and the project page at . The updated versions of this manual are available online from . See also Mailutils Wiki (http://mailutils.org/wiki) for the latest updates. 8 Acknowledgement ***************** In no particular order, * Jakob Kaivo , * Jeff Bailey , * Sean Perry , * Thomas Fletcher , * Dave Inglis , * Brian Edmond , * Sam Roberts , * Sergey Poznyakoff , * François Pinard . * Jordi Mallach * Wojciech Polak Appendix A References ********************* ================================================================== *Editor's note:* This node is to be written. ================================================================== Appendix B Date Input Formats ***************************** First, a quote: Our units of temporal measurement, from seconds on up to months, are so complicated, asymmetrical and disjunctive so as to make coherent mental reckoning in time all but impossible. Indeed, had some tyrannical god contrived to enslave our minds to time, to make it all but impossible for us to escape subjection to sodden routines and unpleasant surprises, he could hardly have done better than handing down our present system. It is like a set of trapezoidal building blocks, with no vertical or horizontal surfaces, like a language in which the simplest thought demands ornate constructions, useless particles and lengthy circumlocutions. Unlike the more successful patterns of language and science, which enable us to face experience boldly or at least level-headedly, our system of temporal calculation silently and persistently encourages our terror of time. ... It is as though architects had to measure length in feet, width in meters and height in ells; as though basic instruction manuals demanded a knowledge of five different languages. It is no wonder then that we often look into our own immediate past or future, last Tuesday or a week from Sunday, with feelings of helpless confusion. ... -- Robert Grudin, 'Time and the Art of Living'. This section describes the textual date representations that GNU programs accept. These are the strings you, as a user, can supply as arguments to the various programs. The C interface (via the 'get_date' function) is not described here. B.1 General date syntax ======================= A "date" is a string, possibly empty, containing many items separated by whitespace. The whitespace may be omitted when no ambiguity arises. The empty string means the beginning of today (i.e., midnight). Order of the items is immaterial. A date string may contain many flavors of items: * calendar date items * time of day items * time zone items * day of the week items * relative items * pure numbers. We describe each of these item types in turn, below. A few ordinal numbers may be written out in words in some contexts. This is most useful for specifying day of the week items or relative items (see below). Among the most commonly used ordinal numbers, the word 'last' stands for -1, 'this' stands for 0, and 'first' and 'next' both stand for 1. Because the word 'second' stands for the unit of time there is no way to write the ordinal number 2, but for convenience 'third' stands for 3, 'fourth' for 4, 'fifth' for 5, 'sixth' for 6, 'seventh' for 7, 'eighth' for 8, 'ninth' for 9, 'tenth' for 10, 'eleventh' for 11 and 'twelfth' for 12. When a month is written this way, it is still considered to be written numerically, instead of being "spelled in full"; this changes the allowed strings. In the current implementation, only English is supported for words and abbreviations like 'AM', 'DST', 'EST', 'first', 'January', 'Sunday', 'tomorrow', and 'year'. The output of the 'date' command is not always acceptable as a date string, not only because of the language problem, but also because there is no standard meaning for time zone items like 'IST'. When using 'date' to generate a date string intended to be parsed later, specify a date format that is independent of language and that does not use time zone items other than 'UTC' and 'Z'. Here are some ways to do this: $ LC_ALL=C TZ=UTC0 date Mon Mar 1 00:21:42 UTC 2004 $ TZ=UTC0 date +'%Y-%m-%d %H:%M:%SZ' 2004-03-01 00:21:42Z $ date --iso-8601=ns | tr T ' ' # --iso-8601 is a GNU extension. 2004-02-29 16:21:42,692722128-0800 $ date --rfc-2822 # a GNU extension Sun, 29 Feb 2004 16:21:42 -0800 $ date +'%Y-%m-%d %H:%M:%S %z' # %z is a GNU extension. 2004-02-29 16:21:42 -0800 $ date +'@%s.%N' # %s and %N are GNU extensions. @1078100502.692722128 Alphabetic case is completely ignored in dates. Comments may be introduced between round parentheses, as long as included parentheses are properly nested. Hyphens not followed by a digit are currently ignored. Leading zeros on numbers are ignored. Invalid dates like '2005-02-29' or times like '24:00' are rejected. In the typical case of a host that does not support leap seconds, a time like '23:59:60' is rejected even if it corresponds to a valid leap second. B.2 Calendar date items ======================= A "calendar date item" specifies a day of the year. It is specified differently, depending on whether the month is specified numerically or literally. All these strings specify the same calendar date: 1972-09-24 # ISO 8601. 72-9-24 # Assume 19xx for 69 through 99, # 20xx for 00 through 68. 72-09-24 # Leading zeros are ignored. 9/24/72 # Common U.S. writing. 24 September 1972 24 Sept 72 # September has a special abbreviation. 24 Sep 72 # Three-letter abbreviations always allowed. Sep 24, 1972 24-sep-72 24sep72 The year can also be omitted. In this case, the last specified year is used, or the current year if none. For example: 9/24 sep 24 Here are the rules. For numeric months, the ISO 8601 format 'YEAR-MONTH-DAY' is allowed, where YEAR is any positive number, MONTH is a number between 01 and 12, and DAY is a number between 01 and 31. A leading zero must be present if a number is less than ten. If YEAR is 68 or smaller, then 2000 is added to it; otherwise, if YEAR is less than 100, then 1900 is added to it. The construct 'MONTH/DAY/YEAR', popular in the United States, is accepted. Also 'MONTH/DAY', omitting the year. Literal months may be spelled out in full: 'January', 'February', 'March', 'April', 'May', 'June', 'July', 'August', 'September', 'October', 'November' or 'December'. Literal months may be abbreviated to their first three letters, possibly followed by an abbreviating dot. It is also permitted to write 'Sept' instead of 'September'. When months are written literally, the calendar date may be given as any of the following: DAY MONTH YEAR DAY MONTH MONTH DAY YEAR DAY-MONTH-YEAR Or, omitting the year: MONTH DAY B.3 Time of day items ===================== A "time of day item" in date strings specifies the time on a given day. Here are some examples, all of which represent the same time: 20:02:00.000000 20:02 8:02pm 20:02-0500 # In EST (U.S. Eastern Standard Time). More generally, the time of day may be given as 'HOUR:MINUTE:SECOND', where HOUR is a number between 0 and 23, MINUTE is a number between 0 and 59, and SECOND is a number between 0 and 59 possibly followed by '.' or ',' and a fraction containing one or more digits. Alternatively, ':SECOND' can be omitted, in which case it is taken to be zero. On the rare hosts that support leap seconds, SECOND may be 60. If the time is followed by 'am' or 'pm' (or 'a.m.' or 'p.m.'), HOUR is restricted to run from 1 to 12, and ':MINUTE' may be omitted (taken to be zero). 'am' indicates the first half of the day, 'pm' indicates the second half of the day. In this notation, 12 is the predecessor of 1: midnight is '12am' while noon is '12pm'. (This is the zero-oriented interpretation of '12am' and '12pm', as opposed to the old tradition derived from Latin which uses '12m' for noon and '12pm' for midnight.) The time may alternatively be followed by a time zone correction, expressed as 'SHHMM', where S is '+' or '-', HH is a number of zone hours and MM is a number of zone minutes. The zone minutes term, MM, may be omitted, in which case the one- or two-digit correction is interpreted as a number of hours. You can also separate HH from MM with a colon. When a time zone correction is given this way, it forces interpretation of the time relative to Coordinated Universal Time (UTC), overriding any previous specification for the time zone or the local time zone. For example, '+0530' and '+05:30' both stand for the time zone 5.5 hours ahead of UTC (e.g., India). This is the best way to specify a time zone correction by fractional parts of an hour. The maximum zone correction is 24 hours. Either 'am'/'pm' or a time zone correction may be specified, but not both. B.4 Time zone items =================== A "time zone item" specifies an international time zone, indicated by a small set of letters, e.g., 'UTC' or 'Z' for Coordinated Universal Time. Any included periods are ignored. By following a non-daylight-saving time zone by the string 'DST' in a separate word (that is, separated by some white space), the corresponding daylight saving time zone may be specified. Alternatively, a non-daylight-saving time zone can be followed by a time zone correction, to add the two values. This is normally done only for 'UTC'; for example, 'UTC+05:30' is equivalent to '+05:30'. Time zone items other than 'UTC' and 'Z' are obsolescent and are not recommended, because they are ambiguous; for example, 'EST' has a different meaning in Australia than in the United States. Instead, it's better to use unambiguous numeric time zone corrections like '-0500', as described in the previous section. If neither a time zone item nor a time zone correction is supplied, time stamps are interpreted using the rules of the default time zone (*note Specifying time zone rules::). B.5 Day of week items ===================== The explicit mention of a day of the week will forward the date (only if necessary) to reach that day of the week in the future. Days of the week may be spelled out in full: 'Sunday', 'Monday', 'Tuesday', 'Wednesday', 'Thursday', 'Friday' or 'Saturday'. Days may be abbreviated to their first three letters, optionally followed by a period. The special abbreviations 'Tues' for 'Tuesday', 'Wednes' for 'Wednesday' and 'Thur' or 'Thurs' for 'Thursday' are also allowed. A number may precede a day of the week item to move forward supplementary weeks. It is best used in expression like 'third monday'. In this context, 'last DAY' or 'next DAY' is also acceptable; they move one week before or after the day that DAY by itself would represent. A comma following a day of the week item is ignored. B.6 Relative items in date strings ================================== "Relative items" adjust a date (or the current date if none) forward or backward. The effects of relative items accumulate. Here are some examples: 1 year 1 year ago 3 years 2 days The unit of time displacement may be selected by the string 'year' or 'month' for moving by whole years or months. These are fuzzy units, as years and months are not all of equal duration. More precise units are 'fortnight' which is worth 14 days, 'week' worth 7 days, 'day' worth 24 hours, 'hour' worth 60 minutes, 'minute' or 'min' worth 60 seconds, and 'second' or 'sec' worth one second. An 's' suffix on these units is accepted and ignored. The unit of time may be preceded by a multiplier, given as an optionally signed number. Unsigned numbers are taken as positively signed. No number at all implies 1 for a multiplier. Following a relative item by the string 'ago' is equivalent to preceding the unit by a multiplier with value -1. The string 'tomorrow' is worth one day in the future (equivalent to 'day'), the string 'yesterday' is worth one day in the past (equivalent to 'day ago'). The strings 'now' or 'today' are relative items corresponding to zero-valued time displacement, these strings come from the fact a zero-valued time displacement represents the current time when not otherwise changed by previous items. They may be used to stress other items, like in '12:00 today'. The string 'this' also has the meaning of a zero-valued time displacement, but is preferred in date strings like 'this thursday'. When a relative item causes the resulting date to cross a boundary where the clocks were adjusted, typically for daylight saving time, the resulting date and time are adjusted accordingly. The fuzz in units can cause problems with relative items. For example, '2003-07-31 -1 month' might evaluate to 2003-07-01, because 2003-06-31 is an invalid date. To determine the previous month more reliably, you can ask for the month before the 15th of the current month. For example: $ date -R Thu, 31 Jul 2003 13:02:39 -0700 $ date --date='-1 month' +'Last month was %B?' Last month was July? $ date --date="$(date +%Y-%m-15) -1 month" +'Last month was %B!' Last month was June! Also, take care when manipulating dates around clock changes such as daylight saving leaps. In a few cases these have added or subtracted as much as 24 hours from the clock, so it is often wise to adopt universal time by setting the 'TZ' environment variable to 'UTC0' before embarking on calendrical calculations. B.7 Pure numbers in date strings ================================ The precise interpretation of a pure decimal number depends on the context in the date string. If the decimal number is of the form YYYYMMDD and no other calendar date item (*note Calendar date items::) appears before it in the date string, then YYYY is read as the year, MM as the month number and DD as the day of the month, for the specified calendar date. If the decimal number is of the form HHMM and no other time of day item appears before it in the date string, then HH is read as the hour of the day and MM as the minute of the hour, for the specified time of day. MM can also be omitted. If both a calendar date and a time of day appear to the left of a number in the date string, but no relative item, then the number overrides the year. B.8 Seconds since the Epoch =========================== If you precede a number with '@', it represents an internal time stamp as a count of seconds. The number can contain an internal decimal point (either '.' or ','); any excess precision not supported by the internal representation is truncated toward minus infinity. Such a number cannot be combined with any other date item, as it specifies a complete time stamp. Internally, computer times are represented as a count of seconds since an epoch--a well-defined point of time. On GNU and POSIX systems, the epoch is 1970-01-01 00:00:00 UTC, so '@0' represents this time, '@1' represents 1970-01-01 00:00:01 UTC, and so forth. GNU and most other POSIX-compliant systems support such times as an extension to POSIX, using negative counts, so that '@-1' represents 1969-12-31 23:59:59 UTC. Traditional Unix systems count seconds with 32-bit two's-complement integers and can represent times from 1901-12-13 20:45:52 through 2038-01-19 03:14:07 UTC. More modern systems use 64-bit counts of seconds with nanosecond subcounts, and can represent all the times in the known lifetime of the universe to a resolution of 1 nanosecond. On most hosts, these counts ignore the presence of leap seconds. For example, on most hosts '@915148799' represents 1998-12-31 23:59:59 UTC, '@915148800' represents 1999-01-01 00:00:00 UTC, and there is no way to represent the intervening leap second 1998-12-31 23:59:60 UTC. B.9 Specifying time zone rules ============================== Normally, dates are interpreted using the rules of the current time zone, which in turn are specified by the 'TZ' environment variable, or by a system default if 'TZ' is not set. To specify a different set of default time zone rules that apply just to one date, start the date with a string of the form 'TZ="RULE"'. The two quote characters ('"') must be present in the date, and any quotes or backslashes within RULE must be escaped by a backslash. For example, with the GNU 'date' command you can answer the question "What time is it in New York when a Paris clock shows 6:30am on October 31, 2004?" by using a date beginning with 'TZ="Europe/Paris"' as shown in the following shell transcript: $ export TZ="America/New_York" $ date --date='TZ="Europe/Paris" 2004-10-31 06:30' Sun Oct 31 01:30:00 EDT 2004 In this example, the '--date' operand begins with its own 'TZ' setting, so the rest of that operand is processed according to 'Europe/Paris' rules, treating the string '2004-10-31 06:30' as if it were in Paris. However, since the output of the 'date' command is processed according to the overall time zone rules, it uses New York time. (Paris was normally six hours ahead of New York in 2004, but this example refers to a brief Halloween period when the gap was five hours.) A 'TZ' value is a rule that typically names a location in the 'tz' database (http://www.twinsun.com/tz/tz-link.htm). A recent catalog of location names appears in the TWiki Date and Time Gateway (http://twiki.org/cgi-bin/xtra/tzdate). A few non-GNU hosts require a colon before a location name in a 'TZ' setting, e.g., 'TZ=":America/New_York"'. The 'tz' database includes a wide variety of locations ranging from 'Arctic/Longyearbyen' to 'Antarctica/South_Pole', but if you are at sea and have your own private time zone, or if you are using a non-GNU host that does not support the 'tz' database, you may need to use a POSIX rule instead. Simple POSIX rules like 'UTC0' specify a time zone without daylight saving time; other rules can specify simple daylight saving regimes. *Note Specifying the Time Zone with 'TZ': (libc)TZ Variable. B.10 Authors of 'get_date' ========================== 'get_date' was originally implemented by Steven M. Bellovin () while at the University of North Carolina at Chapel Hill. The code was later tweaked by a couple of people on Usenet, then completely overhauled by Rich $alz () and Jim Berets () in August, 1990. Various revisions for the GNU system were made by David MacKenzie, Jim Meyering, Paul Eggert and others. This chapter was originally produced by François Pinard () from the 'getdate.y' source code, and then edited by K. Berry (). Appendix C Date/time Format String ********************************** This appendix documents the format specifications for outputting date/time values. It is used, in particular, by the 'mail' utility (*note headline::). Essentially, it is a reproduction of the man page for GNU 'strftime' function. Some of the conversion specifiers might not be available on all systems, due to differences in 'strftime' between systems. If unsure, please consult *note strftime: (strftime(3))strftime. Ordinary characters placed in the format string are reproduced without conversion. Conversion specifiers are introduced by a '%' character, and are replaced as follows: %a The abbreviated weekday name according to the current locale. %A The full weekday name according to the current locale. %b The abbreviated month name according to the current locale. %B The full month name according to the current locale. %c The preferred date and time representation for the current locale. %C The century number (year/100) as a 2-digit integer. %d The day of the month as a decimal number (range 01 to 31). %D Equivalent to '%m/%d/%y'. %e Like '%d', the day of the month as a decimal number, but a leading zero is replaced by a space. %E Modifier: use alternative format, see below (*note conversion specs::). %F Equivalent to '%Y-%m-%d' (the ISO 8601 date format). %G The ISO 8601 year with century as a decimal number. The 4-digit year corresponding to the ISO week number (see '%V'). This has the same format and value as '%y', except that if the ISO week number belongs to the previous or next year, that year is used instead. %g Like '%G', but without century, i.e., with a 2-digit year (00-99). %h Equivalent to '%b'. %H The hour as a decimal number using a 24-hour clock (range 00 to 23). %I The hour as a decimal number using a 12-hour clock (range 01 to 12). %j The day of the year as a decimal number (range 001 to 366). %k The hour (24-hour clock) as a decimal number (range 0 to 23); single digits are preceded by a blank. (See also '%H'.) %l The hour (12-hour clock) as a decimal number (range 1 to 12); single digits are preceded by a blank. (See also '%I'.) %m The month as a decimal number (range 01 to 12). %M The minute as a decimal number (range 00 to 59). %n A newline character. %O Modifier: use alternative format, see below (*note conversion specs::). %p Either 'AM' or 'PM' according to the given time value, or the corresponding strings for the current locale. Noon is treated as 'pm' and midnight as 'am'. %P Like '%p' but in lowercase: 'am' or 'pm' or a corresponding string for the current locale. %r The time in 'a.m.' or 'p.m.' notation. In the POSIX locale this is equivalent to '%I:%M:%S %p'. %R The time in 24-hour notation ('%H:%M'). For a version including the seconds, see '%T' below. %s The number of seconds since the Epoch, i.e., since 1970-01-01 00:00:00 UTC. %S The second as a decimal number (range 00 to 61). %t A tab character. %T The time in 24-hour notation ('%H:%M:%S'). %u The day of the week as a decimal, range 1 to 7, Monday being 1. See also '%w'. %U The week number of the current year as a decimal number, range 00 to 53, starting with the first Sunday as the first day of week 01. See also '%V' and '%W'. %V The ISO 8601:1988 week number of the current year as a decimal number, range 01 to 53, where week 1 is the first week that has at least 4 days in the current year, and with Monday as the first day of the week. See also '%U' and '%W'. %w The day of the week as a decimal, range 0 to 6, Sunday being 0. See also '%u'. %W The week number of the current year as a decimal number, range 00 to 53, starting with the first Monday as the first day of week 01. %x The preferred date representation for the current locale without the time. %X The preferred time representation for the current locale without the date. %y The year as a decimal number without a century (range 00 to 99). %Y The year as a decimal number including the century. %z The time-zone as hour offset from GMT. Required to emit RFC822-conformant dates (using '%a, %d %b %Y %H:%M:%S %z') %Z The time zone or name or abbreviation. %+ The date and time in 'date(1)' format. %% A literal '%' character. Some conversion specifiers can be modified by preceding them by the 'E' or 'O' modifier to indicate that an alternative format should be used. If the alternative format or specification does not exist for the current locale, the behaviour will be as if the unmodified conversion specification were used. The Single Unix Specification mentions '%Ec', '%EC', '%Ex', '%EX', '%Ry', '%EY', '%Od', '%Oe', '%OH', '%OI', '%Om', '%OM', '%OS', '%Ou', '%OU', '%OV', '%Ow', '%OW', '%Oy', where the effect of the 'O' modifier is to use alternative numeric symbols (say, roman numerals), and that of the 'E' modifier is to use a locale-dependent alternative representation. Appendix D Configuring Help Summary *********************************** Running 'PROG --help' displays the short usage summary for PROG utility (*note Common Options::). This summary is organized by "groups" of semantically close options. The options within each group are printed in the following order: a short option, eventually followed by a list of corresponding long option names, followed by a short description of the option. For example, here is an excerpt from the actual 'sieve --help' output: -c, --compile-only Compile script and exit -d, --debug[=FLAGS] Debug flags -e, --email=ADDRESS Override user email address The exact visual representation of the help output is configurable via 'ARGP_HELP_FMT' environment variable. The value of this variable is a comma-separated list of "format variable" assignments. There are two kinds of format variables. An "offset variable" keeps the offset of some part of help output text from the leftmost column on the screen. A "boolean" variable is a flag that toggles some output feature on or off. Depending on the type of the corresponding variable, there are two kinds of assignments: Offset assignment The assignment to an offset variable has the following syntax: VARIABLE=VALUE where VARIABLE is the variable name, and VALUE is a numeric value to be assigned to the variable. Boolean assignment To assign 'true' value to a variable, simply put this variable name. To assign 'false' value, prefix the variable name with 'no-'. For example: # Assign true value: dup-args # Assign false value: no-dup-args Following variables are declared: -- Help Output: boolean dup-args If true, arguments for an option are shown with both short and long options, even when a given option has both forms, for example: -e ADDRESS, --email=ADDRESS Override user email address If false, then if an option has both short and long forms, the argument is only shown with the long one, for example: -e, --email=ADDRESS Override user email address and a message indicating that the argument is applicable to both forms is printed below the options. This message can be disabled using 'dup-args-note' (see below). The default is false. -- Help Output: boolean dup-args-note If this variable is true, which is the default, the following notice is displayed at the end of the help output: Mandatory or optional arguments to long options are also mandatory or optional for any corresponding short options. Setting 'no-dup-args-note' inhibits this message. Normally, only one of variables 'dup-args' or 'dup-args-note' should be set. -- Help Output: offset short-opt-col Column in which short options start. Default is 2. $ sieve --help|grep ADDRESS -e, --email=ADDRESS Override user email address $ ARGP_HELP_FMT=short-opt-col=6 sieve --help|grep ARCHIVE -e, --email=ADDRESS Override user email address -- Help Output: offset long-opt-col Column in which long options start. Default is 6. For example: $ sieve --help|grep ADDRESS -e, --email=ADDRESS Override user email address $ ARGP_HELP_FMT=long-opt-col=16 sieve --help|grep ADDRESS -e, --email=ADDRESS Override user email address -- Help Output: offset doc-opt-col Column in which "doc options" start. A doc option isn't actually an option, but rather an arbitrary piece of documentation that is displayed in much the same manner as the options. For example, in the output of 'folder --help': Usage: folder [OPTION...] [action] [msg] GNU MH folder Actions are: --list List the contents of the folder stack ... the string 'Actions are:' is a doc option. Thus, if you set 'ARGP_HELP_FMT=doc-opt-col=6' the above part of the help output will look as follows: Usage: folder [OPTION...] [action] [msg] GNU MH folder Actions are: --list List the contents of the folder stack ... -- Help Output: offset opt-doc-col Column in which option description starts. Default is 29. $ sieve --help|grep ADDRESS -e, --email=ADDRESS Override user email address $ ARGP_HELP_FMT=opt-doc-col=19 sieve --help|grep ADDRESS -e, --email=ADDRESS Override user email address $ ARGP_HELP_FMT=opt-doc-col=9 sieve --help|grep -i ADDRESS -e, --email=ADDRESS Override user email address Notice, that the description starts on a separate line if 'opt-doc-col' value is too small. -- Help Output: offset header-col Column in which "group headers" are printed. A group header is a descriptive text preceding an option group. For example, in the following text: Sieve options -I, --includedir=DIR Append directory DIR to the list of include directories the text 'Sieve options' is a group header. The default value is 1. -- Help Output: offset usage-indent Indentation of wrapped usage lines. Affects '--usage' output. Default is 12. -- Help Output: offset rmargin Right margin of the text output. Used for wrapping. Appendix E GNU Free Documentation License ***************************************** Version 1.2, November 2002 Copyright (C) 2000-2022 Free Software Foundation, Inc. 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA Everyone is permitted to copy and distribute verbatim copies of this license document, but changing it is not allowed. 0. PREAMBLE The purpose of this License is to make a manual, textbook, or other functional and useful document "free" in the sense of freedom: to assure everyone the effective freedom to copy and redistribute it, with or without modifying it, either commercially or noncommercially. Secondarily, this License preserves for the author and publisher a way to get credit for their work, while not being considered responsible for modifications made by others. This License is a kind of "copyleft", which means that derivative works of the document must themselves be free in the same sense. It complements the GNU General Public License, which is a copyleft license designed for free software. We have designed this License in order to use it for manuals for free software, because free software needs free documentation: a free program should come with manuals providing the same freedoms that the software does. But this License is not limited to software manuals; it can be used for any textual work, regardless of subject matter or whether it is published as a printed book. We recommend this License principally for works whose purpose is instruction or reference. 1. APPLICABILITY AND DEFINITIONS This License applies to any manual or other work, in any medium, that contains a notice placed by the copyright holder saying it can be distributed under the terms of this License. Such a notice grants a world-wide, royalty-free license, unlimited in duration, to use that work under the conditions stated herein. The "Document", below, refers to any such manual or work. Any member of the public is a licensee, and is addressed as "you". You accept the license if you copy, modify or distribute the work in a way requiring permission under copyright law. A "Modified Version" of the Document means any work containing the Document or a portion of it, either copied verbatim, or with modifications and/or translated into another language. A "Secondary Section" is a named appendix or a front-matter section of the Document that deals exclusively with the relationship of the publishers or authors of the Document to the Document's overall subject (or to related matters) and contains nothing that could fall directly within that overall subject. (Thus, if the Document is in part a textbook of mathematics, a Secondary Section may not explain any mathematics.) The relationship could be a matter of historical connection with the subject or with related matters, or of legal, commercial, philosophical, ethical or political position regarding them. The "Invariant Sections" are certain Secondary Sections whose titles are designated, as being those of Invariant Sections, in the notice that says that the Document is released under this License. If a section does not fit the above definition of Secondary then it is not allowed to be designated as Invariant. The Document may contain zero Invariant Sections. If the Document does not identify any Invariant Sections then there are none. The "Cover Texts" are certain short passages of text that are listed, as Front-Cover Texts or Back-Cover Texts, in the notice that says that the Document is released under this License. A Front-Cover Text may be at most 5 words, and a Back-Cover Text may be at most 25 words. A "Transparent" copy of the Document means a machine-readable copy, represented in a format whose specification is available to the general public, that is suitable for revising the document straightforwardly with generic text editors or (for images composed of pixels) generic paint programs or (for drawings) some widely available drawing editor, and that is suitable for input to text formatters or for automatic translation to a variety of formats suitable for input to text formatters. A copy made in an otherwise Transparent file format whose markup, or absence of markup, has been arranged to thwart or discourage subsequent modification by readers is not Transparent. An image format is not Transparent if used for any substantial amount of text. A copy that is not "Transparent" is called "Opaque". Examples of suitable formats for Transparent copies include plain ASCII without markup, Texinfo input format, LaTeX input format, SGML or XML using a publicly available DTD, and standard-conforming simple HTML, PostScript or PDF designed for human modification. Examples of transparent image formats include PNG, XCF and JPG. Opaque formats include proprietary formats that can be read and edited only by proprietary word processors, SGML or XML for which the DTD and/or processing tools are not generally available, and the machine-generated HTML, PostScript or PDF produced by some word processors for output purposes only. The "Title Page" means, for a printed book, the title page itself, plus such following pages as are needed to hold, legibly, the material this License requires to appear in the title page. For works in formats which do not have any title page as such, "Title Page" means the text near the most prominent appearance of the work's title, preceding the beginning of the body of the text. A section "Entitled XYZ" means a named subunit of the Document whose title either is precisely XYZ or contains XYZ in parentheses following text that translates XYZ in another language. (Here XYZ stands for a specific section name mentioned below, such as "Acknowledgements", "Dedications", "Endorsements", or "History".) To "Preserve the Title" of such a section when you modify the Document means that it remains a section "Entitled XYZ" according to this definition. The Document may include Warranty Disclaimers next to the notice which states that this License applies to the Document. These Warranty Disclaimers are considered to be included by reference in this License, but only as regards disclaiming warranties: any other implication that these Warranty Disclaimers may have is void and has no effect on the meaning of this License. 2. VERBATIM COPYING You may copy and distribute the Document in any medium, either commercially or noncommercially, provided that this License, the copyright notices, and the license notice saying this License applies to the Document are reproduced in all copies, and that you add no other conditions whatsoever to those of this License. You may not use technical measures to obstruct or control the reading or further copying of the copies you make or distribute. However, you may accept compensation in exchange for copies. If you distribute a large enough number of copies you must also follow the conditions in section 3. You may also lend copies, under the same conditions stated above, and you may publicly display copies. 3. COPYING IN QUANTITY If you publish printed copies (or copies in media that commonly have printed covers) of the Document, numbering more than 100, and the Document's license notice requires Cover Texts, you must enclose the copies in covers that carry, clearly and legibly, all these Cover Texts: Front-Cover Texts on the front cover, and Back-Cover Texts on the back cover. Both covers must also clearly and legibly identify you as the publisher of these copies. The front cover must present the full title with all words of the title equally prominent and visible. You may add other material on the covers in addition. Copying with changes limited to the covers, as long as they preserve the title of the Document and satisfy these conditions, can be treated as verbatim copying in other respects. If the required texts for either cover are too voluminous to fit legibly, you should put the first ones listed (as many as fit reasonably) on the actual cover, and continue the rest onto adjacent pages. If you publish or distribute Opaque copies of the Document numbering more than 100, you must either include a machine-readable Transparent copy along with each Opaque copy, or state in or with each Opaque copy a computer-network location from which the general network-using public has access to download using public-standard network protocols a complete Transparent copy of the Document, free of added material. If you use the latter option, you must take reasonably prudent steps, when you begin distribution of Opaque copies in quantity, to ensure that this Transparent copy will remain thus accessible at the stated location until at least one year after the last time you distribute an Opaque copy (directly or through your agents or retailers) of that edition to the public. It is requested, but not required, that you contact the authors of the Document well before redistributing any large number of copies, to give them a chance to provide you with an updated version of the Document. 4. MODIFICATIONS You may copy and distribute a Modified Version of the Document under the conditions of sections 2 and 3 above, provided that you release the Modified Version under precisely this License, with the Modified Version filling the role of the Document, thus licensing distribution and modification of the Modified Version to whoever possesses a copy of it. In addition, you must do these things in the Modified Version: A. Use in the Title Page (and on the covers, if any) a title distinct from that of the Document, and from those of previous versions (which should, if there were any, be listed in the History section of the Document). You may use the same title as a previous version if the original publisher of that version gives permission. B. List on the Title Page, as authors, one or more persons or entities responsible for authorship of the modifications in the Modified Version, together with at least five of the principal authors of the Document (all of its principal authors, if it has fewer than five), unless they release you from this requirement. C. State on the Title page the name of the publisher of the Modified Version, as the publisher. D. Preserve all the copyright notices of the Document. E. Add an appropriate copyright notice for your modifications adjacent to the other copyright notices. F. Include, immediately after the copyright notices, a license notice giving the public permission to use the Modified Version under the terms of this License, in the form shown in the Addendum below. G. Preserve in that license notice the full lists of Invariant Sections and required Cover Texts given in the Document's license notice. H. Include an unaltered copy of this License. I. Preserve the section Entitled "History", Preserve its Title, and add to it an item stating at least the title, year, new authors, and publisher of the Modified Version as given on the Title Page. If there is no section Entitled "History" in the Document, create one stating the title, year, authors, and publisher of the Document as given on its Title Page, then add an item describing the Modified Version as stated in the previous sentence. J. Preserve the network location, if any, given in the Document for public access to a Transparent copy of the Document, and likewise the network locations given in the Document for previous versions it was based on. These may be placed in the "History" section. You may omit a network location for a work that was published at least four years before the Document itself, or if the original publisher of the version it refers to gives permission. K. For any section Entitled "Acknowledgements" or "Dedications", Preserve the Title of the section, and preserve in the section all the substance and tone of each of the contributor acknowledgements and/or dedications given therein. L. Preserve all the Invariant Sections of the Document, unaltered in their text and in their titles. Section numbers or the equivalent are not considered part of the section titles. M. Delete any section Entitled "Endorsements". Such a section may not be included in the Modified Version. N. Do not retitle any existing section to be Entitled "Endorsements" or to conflict in title with any Invariant Section. O. Preserve any Warranty Disclaimers. If the Modified Version includes new front-matter sections or appendices that qualify as Secondary Sections and contain no material copied from the Document, you may at your option designate some or all of these sections as invariant. To do this, add their titles to the list of Invariant Sections in the Modified Version's license notice. These titles must be distinct from any other section titles. You may add a section Entitled "Endorsements", provided it contains nothing but endorsements of your Modified Version by various parties--for example, statements of peer review or that the text has been approved by an organization as the authoritative definition of a standard. You may add a passage of up to five words as a Front-Cover Text, and a passage of up to 25 words as a Back-Cover Text, to the end of the list of Cover Texts in the Modified Version. Only one passage of Front-Cover Text and one of Back-Cover Text may be added by (or through arrangements made by) any one entity. If the Document already includes a cover text for the same cover, previously added by you or by arrangement made by the same entity you are acting on behalf of, you may not add another; but you may replace the old one, on explicit permission from the previous publisher that added the old one. The author(s) and publisher(s) of the Document do not by this License give permission to use their names for publicity for or to assert or imply endorsement of any Modified Version. 5. COMBINING DOCUMENTS You may combine the Document with other documents released under this License, under the terms defined in section 4 above for modified versions, provided that you include in the combination all of the Invariant Sections of all of the original documents, unmodified, and list them all as Invariant Sections of your combined work in its license notice, and that you preserve all their Warranty Disclaimers. The combined work need only contain one copy of this License, and multiple identical Invariant Sections may be replaced with a single copy. If there are multiple Invariant Sections with the same name but different contents, make the title of each such section unique by adding at the end of it, in parentheses, the name of the original author or publisher of that section if known, or else a unique number. Make the same adjustment to the section titles in the list of Invariant Sections in the license notice of the combined work. In the combination, you must combine any sections Entitled "History" in the various original documents, forming one section Entitled "History"; likewise combine any sections Entitled "Acknowledgements", and any sections Entitled "Dedications". You must delete all sections Entitled "Endorsements." 6. COLLECTIONS OF DOCUMENTS You may make a collection consisting of the Document and other documents released under this License, and replace the individual copies of this License in the various documents with a single copy that is included in the collection, provided that you follow the rules of this License for verbatim copying of each of the documents in all other respects. You may extract a single document from such a collection, and distribute it individually under this License, provided you insert a copy of this License into the extracted document, and follow this License in all other respects regarding verbatim copying of that document. 7. AGGREGATION WITH INDEPENDENT WORKS A compilation of the Document or its derivatives with other separate and independent documents or works, in or on a volume of a storage or distribution medium, is called an "aggregate" if the copyright resulting from the compilation is not used to limit the legal rights of the compilation's users beyond what the individual works permit. When the Document is included an aggregate, this License does not apply to the other works in the aggregate which are not themselves derivative works of the Document. If the Cover Text requirement of section 3 is applicable to these copies of the Document, then if the Document is less than one half of the entire aggregate, the Document's Cover Texts may be placed on covers that bracket the Document within the aggregate, or the electronic equivalent of covers if the Document is in electronic form. Otherwise they must appear on printed covers that bracket the whole aggregate. 8. TRANSLATION Translation is considered a kind of modification, so you may distribute translations of the Document under the terms of section 4. Replacing Invariant Sections with translations requires special permission from their copyright holders, but you may include translations of some or all Invariant Sections in addition to the original versions of these Invariant Sections. You may include a translation of this License, and all the license notices in the Document, and any Warranty Disclaimers, provided that you also include the original English version of this License and the original versions of those notices and disclaimers. In case of a disagreement between the translation and the original version of this License or a notice or disclaimer, the original version will prevail. If a section in the Document is Entitled "Acknowledgements", "Dedications", or "History", the requirement (section 4) to Preserve its Title (section 1) will typically require changing the actual title. 9. TERMINATION You may not copy, modify, sublicense, or distribute the Document except as expressly provided for under this License. Any other attempt to copy, modify, sublicense or distribute the Document is void, and will automatically terminate your rights under this License. However, parties who have received copies, or rights, from you under this License will not have their licenses terminated so long as such parties remain in full compliance. 10. FUTURE REVISIONS OF THIS LICENSE The Free Software Foundation may publish new, revised versions of the GNU Free Documentation License from time to time. Such new versions will be similar in spirit to the present version, but may differ in detail to address new problems or concerns. See . Each version of the License is given a distinguishing version number. If the Document specifies that a particular numbered version of this License "or any later version" applies to it, you have the option of following the terms and conditions either of that specified version or of any later version that has been published (not as a draft) by the Free Software Foundation. If the Document does not specify a version number of this License, you may choose any version ever published (not as a draft) by the Free Software Foundation. E.1 ADDENDUM: How to use this License for your documents ======================================================== To use this License in a document you have written, include a copy of the License in the document and put the following copyright and license notices just after the title page: Copyright (C) YEAR YOUR NAME. Permission is granted to copy, distribute and/or modify this document under the terms of the GNU Free Documentation License, Version 1.2 or any later version published by the Free Software Foundation; with no Invariant Sections, no Front-Cover Texts, and no Back-Cover Texts. A copy of the license is included in the section entitled ``GNU Free Documentation License''. If you have Invariant Sections, Front-Cover Texts and Back-Cover Texts, replace the "with...Texts." line with this: with the Invariant Sections being LIST THEIR TITLES, with the Front-Cover Texts being LIST, and with the Back-Cover Texts being LIST. If you have Invariant Sections without Cover Texts, or some other combination of the three, merge those two alternatives to suit the situation. If your document contains nontrivial examples of program code, we recommend releasing these examples in parallel under your choice of free software license, such as the GNU General Public License, to permit their use in free software. Function Index ************** This is an alphabetical list of all Mailutils functions. * Menu: * $: Moving Within a Mailbox. (line 3710) * *: Obtaining Online Help. (line 3693) * =: Displaying Information. (line 3796) * ?: Obtaining Online Help. (line 3688) * ^: Moving Within a Mailbox. (line 3707) * |: Displaying Messages. (line 3878) * a: Aliasing. (line 4028) * acl: Server Statement. (line 2202) * addheader: editheader. (line 11811) * address: Built-in Tests. (line 10832) * ago in date strings: Relative items in date strings. (line 12247) * alias: Aliasing. (line 4027) * allow: acl statement. (line 1843) * allow-biffrc: General Settings. (line 8358) * allow-table: tcp-wrappers statement. (line 1972) * alt: Aliasing. (line 4042) * alternates: Aliasing. (line 4041) * am in date strings: Time of day items. (line 12161) * append: mailutils imap. (line 9964) * auth: radius statement. (line 2501) * auth <1>: mailutils smtp. (line 10124) * authentication: auth statement. (line 2305) * authorization: auth statement. (line 2269) * backlog: Server Statement. (line 2163) * base: ldap statement. (line 2743) * binddn: ldap statement. (line 2746) * bulletin-db: Conf-pop3d. (line 7884) * bulletin-source: Conf-pop3d. (line 7880) * c: Saving Messages. (line 3997) * C: Saving Messages. (line 4002) * ca-file: tls-file-checks statement. (line 2901) * capa: mailutils smtp. (line 10117) * capability: mailutils imap. (line 9894) * cd: Changing mailbox/directory. (line 3724) * cert-file: tls-file-checks statement. (line 2897) * ch: Changing mailbox/directory. (line 3726) * chdir: Changing mailbox/directory. (line 3725) * check: mailutils imap. (line 9923) * clear: mailutils smtp. (line 10102) * clear-include-path: Sieve Configuration. (line 6484) * clear-library-path: Sieve Configuration. (line 6481) * close: mailutils imap. (line 9946) * concat: Format String Diffs. (line 8612) * config-file, --config-file option, described: configuration. (line 857) * config-file, --config-file option, introduced: Common Options. (line 775) * config-help, --config-help option, described: configuration. (line 898) * config-help, --config-help option, introduced: Common Options. (line 778) * config-lint, --config-lint option, described: configuration. (line 891) * config-lint, --config-lint option, introduced: Common Options. (line 781) * config-verbose, --config-verbose option, described: configuration. (line 861) * config-verbose, --config-verbose option, introduced: Common Options. (line 784) * connect: mailutils imap. (line 9888) * connect <1>: mailutils smtp. (line 10065) * copy: Saving Messages. (line 3996) * Copy: Saving Messages. (line 4001) * create: mailutils imap. (line 9961) * create-home-dir: Conf-imap4d. (line 8155) * d: Disposing of Messages. (line 3923) * daemon: tcp-wrappers statement. (line 1967) * database: Conf-mda. (line 7294) * day in date strings: Relative items in date strings. (line 12239) * day in date strings <1>: Relative items in date strings. (line 12253) * db: sql statement. (line 2616) * debug: ldap statement. (line 2755) * debug <1>: Sieve Configuration. (line 6510) * dec: Displaying Messages. (line 3858) * decode: Displaying Messages. (line 3857) * decode <1>: Format String Diffs. (line 8523) * delete: Disposing of Messages. (line 3922) * delete <1>: mailutils imap. (line 9952) * delete-expired: Conf-pop3d. (line 7868) * deleteheader": editheader. (line 11816) * delimiter: Conf-imap4d. (line 8141) * deliver: Conf-mda. (line 7248) * deny: acl statement. (line 1846) * deny-table: tcp-wrappers statement. (line 1975) * di: Controlling Header Display. (line 3782) * directory: radius statement. (line 2450) * directory <1>: Conf-imap4d. (line 8135) * discard: Controlling Header Display. (line 3781) * discard <1>: Built-in Actions. (line 11225) * disconnect: mailutils imap. (line 9987) * domain: Conf-mda. (line 7256) * domainpart: Variables. (line 1258) * dp: Disposing of Messages. (line 3933) * dt: Disposing of Messages. (line 3934) * e: Editing Messages. (line 4015) * edit: Editing Messages. (line 4014) * ehlo: mailutils smtp. (line 10113) * emacs: Movemail Configuration. (line 5779) * email: Sieve Configuration. (line 6521) * enable: tcp-wrappers statement. (line 1964) * enable <1>: ldap statement. (line 2737) * envelope: Built-in Tests. (line 10904) * environment: environment. (line 11756) * ex: Quitting the Program. (line 3673) * examine: mailutils imap. (line 9929) * exec: acl statement. (line 1874) * exec <1>: acl statement. (line 1916) * exists: Built-in Tests. (line 10939) * exit: Quitting the Program. (line 3672) * exit-multiple-delivery-success: Conf-mda. (line 7259) * exit-tempfail: Conf-mda. (line 7303) * expire: Conf-pop3d. (line 7864) * expire-timeout: locking statement. (line 1713) * expunge: mailutils imap. (line 9958) * external-locker: locking statement. (line 1730) * f: Displaying Information. (line 3804) * F: Replying. (line 4107) * facility: logging statement. (line 1361) * false: Built-in Tests. (line 10824) * fetch: mailutils imap. (line 9938) * fi: Changing mailbox/directory. (line 3731) * field-map: sql statement. (line 2690) * field-map <1>: ldap statement. (line 2759) * file: Changing mailbox/directory. (line 3730) * file <1>: Conf-mda. (line 7271) * file, --file option, mail option: Reading Mail. (line 3422) * file-checks: Conf-mda. (line 7280) * fileinto: Built-in Actions. (line 11237) * first in date strings: General date syntax. (line 12042) * fo: Replying. (line 4101) * fold: Changing mailbox/directory. (line 3733) * folder: mailbox statement. (line 1561) * folder <1>: Changing mailbox/directory. (line 3732) * folder <2>: Conf-readmsg. (line 6115) * folders: Displaying Information. (line 3825) * followup: Replying. (line 4100) * Followup: Replying. (line 4106) * foreground: General Server Configuration. (line 2048) * form-feeds: Conf-readmsg. (line 6112) * fortnight in date strings: Relative items in date strings. (line 12239) * forward: Conf-mda. (line 7263) * from: Displaying Information. (line 3803) * from <1>: mailutils smtp. (line 10130) * g: Aliasing. (line 4030) * getpass: sql statement. (line 2681) * getpwnam: radius statement. (line 2511) * getpwnam <1>: sql statement. (line 2640) * getpwnam <2>: ldap statement. (line 2791) * getpwuid: radius statement. (line 2535) * getpwuid <1>: sql statement. (line 2674) * getpwuid <2>: ldap statement. (line 2797) * get_date: Date Input Formats. (line 11993) * group: Aliasing. (line 4029) * guimb-end: guimb. (line 6674) * guimb-getopt: guimb. (line 6666) * guimb-message: guimb. (line 6660) * h: Displaying Information. (line 3800) * handshake-timeout: tls statement. (line 2848) * header: Conf-readmsg. (line 6100) * header <1>: Built-in Tests. (line 10959) * headers: Displaying Information. (line 3799) * hel: Obtaining Online Help. (line 3687) * help: Obtaining Online Help. (line 3686) * help, --help option, described: Common Options. (line 712) * ho: Marking Messages. (line 3910) * hold: Marking Messages. (line 3909) * home-dir-mode: Conf-imap4d. (line 8159) * host: sql statement. (line 2605) * hour in date strings: Relative items in date strings. (line 12239) * id: mailutils imap. (line 9917) * id-fields: Conf-imap4d. (line 8215) * ident-encrypt-only: Conf-imap4d. (line 8212) * ident-keyfile: Conf-imap4d. (line 8208) * ifexec: acl statement. (line 1849) * ig: Controlling Header Display. (line 3784) * ignore: Controlling Header Display. (line 3783) * ignore-errors: Movemail Configuration. (line 5783) * include-path: Sieve Configuration. (line 6496) * interface: sql statement. (line 2588) * in_reply_to: Format String Diffs. (line 8623) * isreply: Format String Diffs. (line 8575) * keep: Built-in Actions. (line 11219) * keep-going: Sieve Configuration. (line 6500) * key-file: tls-file-checks statement. (line 2873) * language: Conf-mda. (line 7318) * last DAY: Day of week items. (line 12220) * last in date strings: General date syntax. (line 12042) * library-path: Sieve Configuration. (line 6487) * library-path-prefix: Sieve Configuration. (line 6491) * line-info: Sieve Configuration. (line 6517) * list: Obtaining Online Help. (line 3692) * list <1>: mailutils imap. (line 9971) * list <2>: mailutils smtp. (line 10106) * list <3>: External Tests. (line 11115) * localpart: Variables. (line 1254) * log: acl statement. (line 1884) * login: mailutils imap. (line 9907) * login-delay: Conf-pop3d. (line 7872) * login-disabled: Conf-imap4d. (line 8152) * logout: mailutils imap. (line 9913) * lsub: mailutils imap. (line 9975) * m: Replying. (line 4054) * M: Replying. (line 4062) * mail: Replying. (line 4053) * Mail: Replying. (line 4061) * mail-spool: mailbox statement. (line 1438) * mailbox-mode: Conf-imap4d. (line 8119) * mailbox-ownership: Movemail Configuration. (line 5835) * mailbox-pattern: mailbox statement. (line 1448) * mailbox-type: mailbox statement. (line 1555) * mailbox-type <1>: Conf-imap4d. (line 8147) * max-children: General Server Configuration. (line 2054) * max-lines: General Settings. (line 8355) * max-messages: Movemail Configuration. (line 5856) * max-requests: Security Settings. (line 8368) * mb: Saving Messages. (line 3983) * mbox: Saving Messages. (line 3982) * mbox-url: Sieve Configuration. (line 6504) * metamail: Mimeview Config. (line 7665) * midnight in date strings: Time of day items. (line 12161) * mimetypes: Mimeview Config. (line 7662) * minute in date strings: Relative items in date strings. (line 12239) * mode: General Server Configuration. (line 2021) * moderator: External Actions. (line 11394) * month in date strings: Relative items in date strings. (line 12239) * n: Moving Within a Mailbox. (line 3714) * namespace: Conf-imap4d. (line 8112) * next: Moving Within a Mailbox. (line 3713) * next DAY: Day of week items. (line 12220) * next in date strings: General date syntax. (line 12042) * no-config, --no-config option, introduced: Common Options. (line 793) * no-header: Conf-readmsg. (line 6109) * no-site-config, --no-site-config option, described: configuration. (line 820) * no-site-config, --no-site-config option, introduced: Common Options. (line 787) * no-user-config, --no-user-config option, described: configuration. (line 846) * no-user-config, --no-user-config option, introduced: Common Options. (line 790) * noon in date strings: Time of day items. (line 12161) * noop: mailutils imap. (line 9984) * now in date strings: Relative items in date strings. (line 12257) * numaddr: External Tests. (line 11006) * onerror: Movemail Configuration. (line 5862) * overflow-control-interval: Security Settings. (line 8379) * overflow-delay-time: Security Settings. (line 8375) * p: Displaying Messages. (line 3839) * P: Displaying Messages. (line 3852) * package: Format String Diffs. (line 8537) * package_string: Format String Diffs. (line 8541) * passwd: sql statement. (line 2622) * passwd <1>: ldap statement. (line 2749) * passwd-dir: virtdomain statement. (line 2392) * password-encryption: sql statement. (line 2625) * pattern: Conf-mda. (line 7323) * pid-check: locking statement. (line 1718) * pidfile: General Server Configuration. (line 2063) * pipe: Displaying Messages. (line 3877) * pipe <1>: External Tests. (line 11033) * pipe <2>: External Actions. (line 11451) * pm in date strings: Time of day items. (line 12161) * port: General Server Configuration. (line 2070) * port <1>: sql statement. (line 2611) * pre: Marking Messages. (line 3912) * preauth: Conf-imap4d. (line 8165) * preauth-only: Conf-imap4d. (line 8204) * prefix: Conf-imap4d. (line 8127) * preserve: Marking Messages. (line 3911) * preserve <1>: Movemail Configuration. (line 5773) * prev: Moving Within a Mailbox. (line 3718) * previous: Moving Within a Mailbox. (line 3717) * print: Displaying Messages. (line 3838) * Print: Displaying Messages. (line 3851) * print-severity: logging statement. (line 1370) * printhdr: Format String Diffs. (line 8616) * program-id: Movemail Configuration. (line 5787) * quit: Quitting the Program. (line 3648) * quit <1>: mailutils imap. (line 9914) * quit <2>: mailutils smtp. (line 10141) * quota: Conf-mda. (line 7284) * r: Replying. (line 4081) * R: Replying. (line 4090) * rcpt: Format String Diffs. (line 8599) * redirect: Built-in Actions. (line 11372) * references: Format String Diffs. (line 8628) * reject: Built-in Actions. (line 11295) * rename: mailutils imap. (line 9955) * reply: Replying. (line 4079) * Reply: Replying. (line 4088) * reply_regex: Format String Diffs. (line 8557) * request-control-interval: Security Settings. (line 8372) * respond: Replying. (line 4080) * Respond: Replying. (line 4089) * ret: Controlling Header Display. (line 3789) * retain: Controlling Header Display. (line 3788) * retry-count: locking statement. (line 1704) * retry-sleep: locking statement. (line 1707) * retry-timeout: locking statement. (line 1708) * reverse: Movemail Configuration. (line 5776) * rset: mailutils smtp. (line 10127) * s: Saving Messages. (line 3943) * S: Saving Messages. (line 3958) * save: Saving Messages. (line 3942) * Save: Saving Messages. (line 3957) * script: Conf-mda. (line 7310) * select: mailutils imap. (line 9926) * send: mailutils smtp. (line 10144) * service: pam statement. (line 2360) * session-id: logging statement. (line 1378) * set: mailutils smtp. (line 10098) * set <1>: variables. (line 11665) * set, --set option, described: configuration. (line 913) * set, --set option, introduced: Common Options. (line 796) * severity: logging statement. (line 1373) * shell: Variables. (line 1262) * show-all-match: Conf-readmsg. (line 6118) * show-config-options, --show-config-options option, described: Common Options. (line 764) * si: Displaying Information. (line 3821) * sieve: Sieve Configuration. (line 6474) * single-process: Server Statement. (line 2145) * size: Displaying Information. (line 3820) * size <1>: Built-in Tests. (line 10877) * smtp: mailutils smtp. (line 10138) * spamd: External Tests. (line 11058) * sql-query: Conf-mda. (line 7298) * ssl-ca-file: tls statement. (line 2841) * ssl-certificate-file: tls statement. (line 2835) * ssl-key-file: tls statement. (line 2838) * ssl-priorities: tls statement. (line 2844) * starttls: mailutils imap. (line 9902) * starttls <1>: mailutils smtp. (line 10120) * stat-file: Conf-pop3d. (line 7876) * status: mailutils imap. (line 9933) * stderr: Conf-mda. (line 7245) * stop: Built-in Actions. (line 11214) * store: mailutils imap. (line 9942) * string: variables. (line 11740) * struct: Displaying Messages. (line 3883) * su: Displaying Information. (line 3829) * subscribe: mailutils imap. (line 9978) * summary: Displaying Information. (line 3828) * syslog: logging statement. (line 1352) * t: Displaying Messages. (line 3841) * T: Displaying Messages. (line 3854) * ta: Marking Messages. (line 3899) * tag: logging statement. (line 1366) * tag <1>: Marking Messages. (line 3898) * text-type: mime statement. (line 1590) * text-type <1>: mime statement. (line 1591) * this in date strings: Relative items in date strings. (line 12257) * ticket: Sieve Configuration. (line 6507) * timeout: General Server Configuration. (line 2078) * timeout <1>: Server Statement. (line 2159) * timestamp: External Tests. (line 11151) * tls: Server Statement. (line 2189) * tls <1>: ldap statement. (line 2752) * tls-mode: Server Statement. (line 2166) * tls-mode <1>: Conf-pop3d. (line 7835) * to: Displaying Messages. (line 3872) * to <1>: mailutils smtp. (line 10134) * today in date strings: Relative items in date strings. (line 12257) * tomorrow in date strings: Relative items in date strings. (line 12253) * top: Displaying Messages. (line 3871) * tou: Saving Messages. (line 3990) * touch: Saving Messages. (line 3989) * transcript: Server Statement. (line 2150) * true: Built-in Tests. (line 10828) * type: locking statement. (line 1650) * type <1>: Displaying Messages. (line 3840) * Type: Displaying Messages. (line 3853) * u: Disposing of Messages. (line 3930) * uid: mailutils imap. (line 9997) * uidl: Movemail Configuration. (line 5828) * una: Aliasing. (line 4036) * unalias: Aliasing. (line 4035) * undelete: Disposing of Messages. (line 3929) * undelete <1>: Conf-pop3d. (line 7861) * unre: Format String Diffs. (line 8549) * unread: Marking Messages. (line 3916) * unselect: mailutils imap. (line 9949) * unsubscribe: mailutils imap. (line 9981) * unt: Marking Messages. (line 3904) * untag: Marking Messages. (line 3903) * url: mailer statement. (line 1756) * url <1>: ldap statement. (line 2740) * usage, --usage option, described: Common Options. (line 749) * user: sql statement. (line 2619) * user, --user option, mail option: Reading Mail. (line 3444) * v: Editing Messages. (line 4020) * vacation: External Actions. (line 11473) * ve: Obtaining Online Help. (line 3697) * verbose: Movemail Configuration. (line 5832) * verbose <1>: Sieve Configuration. (line 6514) * version: Obtaining Online Help. (line 3696) * version <1>: Format String Diffs. (line 8545) * version, --version option, described: Common Options. (line 760) * visual: Editing Messages. (line 4019) * w: Saving Messages. (line 3973) * W: Saving Messages. (line 3978) * wa: Obtaining Online Help. (line 3701) * warranty: Obtaining Online Help. (line 3700) * weedlist: Conf-readmsg. (line 6103) * week in date strings: Relative items in date strings. (line 12239) * write: Saving Messages. (line 3972) * Write: Saving Messages. (line 3977) * xit: Quitting the Program. (line 3674) * year in date strings: Relative items in date strings. (line 12239) * yesterday in date strings: Relative items in date strings. (line 12253) * z: Displaying Information. (line 3807) Variable Index ************** * Menu: * append: Mail Variables. (line 4867) * appenddeadletter: Mail Variables. (line 4877) * ARGP_HELP_FMT, environment variable: Usage Vars. (line 12577) * askbcc: Mail Variables. (line 4885) * askcc: Mail Variables. (line 4892) * asksub: Mail Variables. (line 4899) * autoinc: Mail Variables. (line 4906) * autoprint: Mail Variables. (line 4912) * bang: Mail Variables. (line 4919) * charset: Mail Variables. (line 4940) * cmd: Mail Variables. (line 4963) * columns: Mail Variables. (line 4969) * crt: Mail Variables. (line 4976) * crt <1>: Mail Variables. (line 4977) * datefield: Mail Variables. (line 4928) * debug: Mail Variables. (line 4989) * debug <1>: Mail Variables. (line 4990) * decode-fallback: Mail Variables. (line 5002) * doc-opt-col: Usage Vars. (line 12651) * dot: Mail Variables. (line 5021) * dup-args: Usage Vars. (line 12608) * dup-args-note: Usage Vars. (line 12625) * editheaders: Mail Variables. (line 5028) * emptystart: Mail Variables. (line 5035) * escape: Mail Variables. (line 5043) * flipr: Mail Variables. (line 5049) * folder: Mail Variables. (line 5056) * fromfield: Mail Variables. (line 5063) * fullnames: Mail Variables. (line 5073) * header: Mail Variables. (line 5084) * header-col: Usage Vars. (line 12687) * headline: Mail Variables. (line 5091) * hold: Mail Variables. (line 5213) * ignore: Mail Variables. (line 5230) * ignoreeof: Mail Variables. (line 5238) * indentprefix: Mail Variables. (line 5245) * inplacealiases: Mail Variables. (line 5251) * keep: Mail Variables. (line 5260) * keepsave: Mail Variables. (line 5270) * LD_LIBRARY_PATH: Require Statement. (line 10671) * long-opt-col: Usage Vars. (line 12643) * LTDL_LIBRARY_PATH: Require Statement. (line 10671) * mailx: Mail Variables. (line 5284) * metamail: Mail Variables. (line 5313) * metamail <1>: Mail Variables. (line 5314) * metoo: Mail Variables. (line 5357) * mime: Mail Variables. (line 5333) * mimenoask: Mail Variables. (line 5341) * mode: Mail Variables. (line 5365) * MU_DEFAULT_SCHEME: mailbox statement. (line 1556) * nullbody: Mail Variables. (line 5392) * nullbodymsg: Mail Variables. (line 5411) * onehop: Mail Variables. (line 5421) * onehop, mail variable: Mail Variables. (line 5423) * opt-doc-col: Usage Vars. (line 12673) * outfilename: Mail Variables. (line 5428) * outfolder: Mail Variables. (line 5448) * outfolder <1>: Mail Variables. (line 5449) * page: Mail Variables. (line 5466) * PID: Mail Variables. (line 5473) * prompt: Mail Variables. (line 5480) * quiet: Mail Variables. (line 5486) * quit: Mail Variables. (line 5493) * rc: Mail Variables. (line 5499) * readonly: Mail Variables. (line 5506) * record: Mail Variables. (line 5515) * recursivealiases: Mail Variables. (line 5524) * regex: Mail Variables. (line 5530) * replyprefix: Mail Variables. (line 5537) * replyregex: Mail Variables. (line 5544) * return-address: Mail Variables. (line 5561) * rmargin: Usage Vars. (line 12703) * save: Mail Variables. (line 5569) * screen: Mail Variables. (line 5576) * sendmail: Mail Variables. (line 5584) * sendwait: Mail Variables. (line 5599) * short-opt-col: Usage Vars. (line 12635) * showenvelope: Mail Variables. (line 5622) * showto: Mail Variables. (line 5629) * Sign: Mail Variables. (line 5606) * sign: Mail Variables. (line 5614) * string: Profile Variable Diffs. (line 8635) * string <1>: Profile Variable Diffs. (line 8641) * subject: Mail Variables. (line 5637) * toplines: Mail Variables. (line 5644) * TZ: Specifying time zone rules. (line 12339) * usage-indent: Usage Vars. (line 12699) * useragent: Mail Variables. (line 5678) * variable-pretty-print: Mail Variables. (line 5650) * variable-strict: Mail Variables. (line 5659) * varpp: Mail Variables. (line 5651) * varstrict: Mail Variables. (line 5660) * verbose: Mail Variables. (line 5671) * xmailer: Mail Variables. (line 5687) Keyword Index ************* * Menu: * !, mail command: Shell Escapes. (line 4218) * #include, sieve: #include. (line 10572) * #searchpath, sieve: #searchpath. (line 10589) * :all, sieve: Tests. (line 10796) * :comparator, sieve: Tests. (line 10777) * :contains, sieve: Tests. (line 10729) * :count, sieve: Tests. (line 10770) * :domain, sieve: Tests. (line 10802) * :is, sieve: Tests. (line 10722) * :localpart, sieve: Tests. (line 10799) * :matches, sieve: Tests. (line 10736) * :mime: Built-in Tests. (line 10972) * :over: Built-in Tests. (line 10892) * :over <1>: External Tests. (line 11025) * :regex, sieve: Tests. (line 10744) * :under: Built-in Tests. (line 10895) * :under <1>: External Tests. (line 11028) * :value, sieve: Tests. (line 10748) * ~!, mail escape: Executing Shell Commands. (line 4465) * ~-, mail escape: Executing Other Mail Commands. (line 4447) * ~., mail escape: Quitting Compose Mode. (line 4288) * ~:, mail escape: Executing Other Mail Commands. (line 4447) * ~?, mail escape: Getting Help on Compose Escapes. (line 4309) * ~a, mail escape: Signing the Message. (line 4421) * ~A, mail escape: Signing the Message. (line 4421) * ~e, mail escape: Editing the Message. (line 4316) * ~f, mail escape: Printing Another Message. (line 4431) * ~F, mail escape: Printing Another Message. (line 4431) * ~i, mail escape: Inserting Value of a Mail Variable. (line 4441) * ~m, mail escape: Enclosing Another Message. (line 4348) * ~M, mail escape: Enclosing Another Message. (line 4348) * ~p, mail escape: Printing And Saving the Message. (line 4413) * ~v, mail escape: Editing the Message. (line 4316) * ~w, mail escape: Printing And Saving the Message. (line 4413) * ~x, mail escape: Quitting Compose Mode. (line 4288) * ~|, mail escape: Executing Shell Commands. (line 4465) * acl: acl statement. (line 1791) * all, sieve: Tests. (line 10796) * allof: Tests and Conditions. (line 10547) * and, sieve: Tests and Conditions. (line 10547) * any: acl statement. (line 1838) * anyof: Tests and Conditions. (line 10547) * auth: auth statement. (line 2212) * comparator, sieve: Tests. (line 10777) * contains, sieve: Tests. (line 10729) * count, sieve: Tests. (line 10770) * debug: debug statement. (line 1386) * domain: SMTP Mailboxes. (line 556) * domain, sieve: Tests. (line 10802) * echo, mail command: Scripting. (line 4730) * else, mail command: Scripting. (line 4827) * endif, mail command: Scripting. (line 4827) * file, forward: Forwarding. (line 7172) * from: SMTP Mailboxes. (line 560) * GNU-MU-Dir: radius statement. (line 2461) * GNU-MU-GECOS: radius statement. (line 2460) * GNU-MU-GID: radius statement. (line 2459) * GNU-MU-Mailbox: radius statement. (line 2463) * GNU-MU-Quota: radius statement. (line 2464) * GNU-MU-Shell: radius statement. (line 2462) * GNU-MU-UID: radius statement. (line 2458) * GNU-MU-User-Name: radius statement. (line 2456) * gsasl: gsasl statement. (line 2912) * if, mail command: Scripting. (line 4827) * if, sieve: Control Flow. (line 10482) * include: include. (line 1273) * incorporate, mail command: Incorporating New Mail. (line 4211) * is, sieve: Tests. (line 10722) * ldap: ldap statement. (line 2706) * level: debug statement. (line 1400) * line-info: debug statement. (line 1405) * localpart, sieve: Tests. (line 10799) * locking: locking statement. (line 1617) * logging: logging statement. (line 1322) * mailbox: mailbox statement. (line 1412) * mailer: mailer statement. (line 1740) * matches, sieve: Tests. (line 10736) * MBOX, environment variable: Reading Mail. (line 3413) * mime: mime statement. (line 1573) * noauth: SMTP Mailboxes. (line 563) * nosender, mail command: Controlling Sender Fields. (line 4167) * not, sieve: Tests and Conditions. (line 10543) * notls: SMTP Mailboxes. (line 566) * or, sieve: Tests and Conditions. (line 10547) * pam: pam statement. (line 2346) * param: mailbox statement. (line 1515) * program: program statement. (line 1297) * radius: radius statement. (line 2423) * rcpt: Program Mailboxes. (line 624) * regex, sieve: Tests. (line 10744) * require, sieve: Require Statement. (line 10597) * script: Sieve MDA Filters. (line 7074) * script <1>: Scheme MDA Filters. (line 7098) * script <2>: Python MDA Filters. (line 7112) * sender: Program Mailboxes. (line 621) * sender, mail command: Controlling Sender Fields. (line 4167) * server: Server Statement. (line 2085) * set, mail command: Scripting. (line 4741) * shell, mail command: Shell Escapes. (line 4218) * source, mail command: Scripting. (line 4735) * sql: sql statement. (line 2549) * strip-domain: SMTP Mailboxes. (line 574) * tcp-wrappers: tcp-wrappers statement. (line 1924) * text:: Lexical Structure. (line 10343) * tls: tls statement. (line 2811) * tls-file-checks: tls-file-checks statement. (line 2855) * to: SMTP Mailboxes. (line 577) * type: mailbox statement. (line 1510) * unset, mail command: Scripting. (line 4741) * user: mailbox statement. (line 1518) * value, sieve: Tests. (line 10748) * variable, mail command: Scripting. (line 4791) * virtdomain: virtdomain statement. (line 2370) Program Index ************* * Menu: * comsatd: comsatd. (line 8291) * decodemail: decodemail. (line 6132) * dotlock: dotlock. (line 10218) * frm: frm and from. (line 3154) * from: frm and from. (line 3203) * guimb: guimb. (line 6653) * imap4d: imap4d. (line 7913) * lmtpd: lmtpd. (line 7391) * mail: mail. (line 3235) * mailutils: mailutils. (line 8896) * mda: mda. (line 6832) * messages: messages. (line 5711) * mimeview: mimeview. (line 7516) * movemail: movemail. (line 5744) * pop3d: pop3d. (line 7671) * putmail: putmail. (line 7447) * readmsg: readmsg. (line 5990) * sieve: sieve. (line 6324) Concept Index ************* This is a general index of all issues discussed in this manual * Menu: * ~+, mail escape: Attaching a File to the Message. (line 4376) * ~/, mail escape: Attaching a File to the Message. (line 4401) * ~<, mail escape: Adding a File to the Message. (line 4362) * ~b, mail escape: Modifying the Headers. (line 4334) * ~c, mail escape: Modifying the Headers. (line 4334) * ~d, mail escape: Adding a File to the Message. (line 4369) * ~h, mail escape: Modifying the Headers. (line 4341) * ~l, mail escape: Attaching a File to the Message. (line 4391) * ~r, mail escape: Adding a File to the Message. (line 4362) * ~s, mail escape: Modifying the Headers. (line 4337) * ~t, mail escape: Modifying the Headers. (line 4329) * ~^, mail escape: Attaching a File to the Message. (line 4405) * abbreviations for months: Calendar date items. (line 12125) * action, sieve: Actions Described. (line 10467) * authentication: auth statement. (line 2212) * authorization: auth statement. (line 2212) * authors of get_date: Authors of get_date. (line 12383) * beginning of time, for POSIX: Seconds since the Epoch. (line 12318) * Bellovin, Steven M.: Authors of get_date. (line 12383) * Berets, Jim: Authors of get_date. (line 12383) * Bernstein, D. J.: Local Mailboxes. (line 418) * Berry, K.: Authors of get_date. (line 12391) * block statement: Statements. (line 1082) * boolean value: Statements. (line 978) * calendar date item: Calendar date items. (line 12093) * case, ignored in dates: General date syntax. (line 12080) * Comments in a configuration file: Comments. (line 941) * comments, in dates: General date syntax. (line 12080) * comparator, sieve: Comparators. (line 10698) * condition, sieve: Tests and Conditions. (line 10540) * configuration file statements: Statements. (line 959) * configuring servers: Server Settings. (line 1981) * daemon, server mode: General Server Configuration. (line 2025) * date format, ISO 8601: Calendar date items. (line 12117) * date input formats: Date Input Formats. (line 11993) * day of week item: Day of week items. (line 12211) * direct indexing: mailbox statement. (line 1471) * directory indexing: mailbox statement. (line 1456) * displacement of dates: Relative items in date strings. (line 12230) * Eggert, Paul: Authors of get_date. (line 12383) * epoch, for POSIX: Seconds since the Epoch. (line 12318) * escape sequence: Statements. (line 986) * Exim: Exim-mda. (line 6881) * FDL, GNU Free Documentation License: GNU FDL. (line 12709) * file, mailbox type: Local Mailboxes. (line 432) * forward: Forwarding. (line 7155) * general date syntax: General date syntax. (line 12027) * hashed indexing: mailbox statement. (line 1495) * here-document: Statements. (line 1026) * imap, mailbox: Remote Mailboxes. (line 485) * IMAP4 namespace: Namespace. (line 7920) * imaps, mailbox: Remote Mailboxes. (line 510) * include statement, configuration file: include. (line 1273) * indexing, direct: mailbox statement. (line 1471) * indexing, hashed: mailbox statement. (line 1495) * indexing, reverse: mailbox statement. (line 1489) * inetd, server mode: General Server Configuration. (line 2037) * ISO 8601 date format: Calendar date items. (line 12117) * items in date strings: General date syntax. (line 12027) * language, in dates: General date syntax. (line 12056) * language, in dates <1>: General date syntax. (line 12060) * Libraries: Libraries. (line 10274) * list: Statements. (line 1066) * local mailbox: Local Mailboxes. (line 389) * MacKenzie, David: Authors of get_date. (line 12383) * macro variable: Variables. (line 1206) * mailbox URL: Mailbox. (line 371) * mailbox, local: Local Mailboxes. (line 389) * mailbox, mail: Reading Mail. (line 3413) * mailbox, program: Program Mailboxes. (line 596) * mailbox, remote: Remote Mailboxes. (line 441) * mailbox, SMTP: SMTP Mailboxes. (line 525) * maildir: Local Mailboxes. (line 412) * mailman: External Actions. (line 11401) * Mailutils configuration file: configuration. (line 802) * mailutils.conf: configuration. (line 802) * mailutils.dict: radius statement. (line 2467) * mbox: Local Mailboxes. (line 404) * MeTA1: MeTA1-mda. (line 6901) * Meyering, Jim: Authors of get_date. (line 12383) * mh: Local Mailboxes. (line 421) * minutes, time zone correction by: Time of day items. (line 12169) * month names in date strings: Calendar date items. (line 12125) * months, written-out: General date syntax. (line 12052) * movemail, configuration: Movemail Configuration. (line 5770) * multi-line comments: Comments. (line 949) * multiline strings, sieve: Lexical Structure. (line 10343) * namespace: Namespace. (line 7920) * numbers, sieve: Lexical Structure. (line 10328) * numbers, written-out: General date syntax. (line 12042) * ordinal numbers: General date syntax. (line 12042) * personal mailbox, mail: Reading Mail. (line 3413) * Pinard, F.: Authors of get_date. (line 12391) * plus expansion: mailbox statement. (line 1562) * pop, mailbox: Remote Mailboxes. (line 445) * pops, mailbox: Remote Mailboxes. (line 474) * preprocessor, sieve: Preprocessor. (line 10562) * prog, URL: Program Mailboxes. (line 611) * program mailbox: Program Mailboxes. (line 596) * Programs: Programs. (line 631) * pure numbers in date strings: Pure numbers in date strings. (line 12291) * quoted string: Statements. (line 986) * RAND Corporation: Local Mailboxes. (line 428) * relative items in date strings: Relative items in date strings. (line 12230) * remote mailbox: Remote Mailboxes. (line 441) * reverse indexing: mailbox statement. (line 1489) * Salz, Rich: Authors of get_date. (line 12383) * secondary mailbox, mail: Reading Mail. (line 3413) * Sendmail: Sendmail-mda. (line 6851) * sendmail, URL: Program Mailboxes. (line 600) * server configuration, general: General Server Configuration. (line 1997) * server settings, configuration: Server Settings. (line 1981) * server statement: Server Statement. (line 2085) * Sieve Language: Sieve Language. (line 10282) * Sieve preprocessor statements: Preprocessor. (line 10562) * simple statements: Statements. (line 959) * single-line comments: Comments. (line 941) * smtp, mailbox: SMTP Mailboxes. (line 529) * smtps, mailbox: SMTP Mailboxes. (line 580) * statement, block: Statements. (line 1082) * statement, simple: Statements. (line 959) * statements, configuration file: Statements. (line 959) * string list, sieve: Lexical Structure. (line 10409) * string, quoted: Statements. (line 986) * string, unquoted: Statements. (line 982) * strings, sieve: Lexical Structure. (line 10339) * system mailbox, mail: Reading Mail. (line 3413) * test, sieve: Tests and Conditions. (line 10531) * test, sieve <1>: Tests. (line 10715) * time formats, output: Date/time Format String. (line 12398) * time of day item: Time of day items. (line 12146) * time zone correction: Time of day items. (line 12169) * time zone item: General date syntax. (line 12060) * time zone item <1>: Time zone items. (line 12188) * URL, local: Local Mailboxes. (line 389) * URL, mailbox: Mailbox. (line 371) * URL, prog: Program Mailboxes. (line 611) * URL, remote: Remote Mailboxes. (line 441) * URL, sendmail: Program Mailboxes. (line 600) * URL, SMTP: SMTP Mailboxes. (line 525) * variable expansion: Variables. (line 1206)