GNU Mailutils ¶

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. See Configuring Help Summary, 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. See the --set option.

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.

• Comments
• Statements
• Statement Path

# This is a comment
// This too is a comment

standalone yes;
pidfile /var/run/pop3d.pid;

server srv1 {
  host 10.0.0.1;
  community "foo";
}

foo {
  bar {
    baz 45;   # A.
  }
  baz 98;     # B.
}

.foo.bar.baz

.foo.baz

program x {
  bar {
    baz 45;   # A.
  }
}

.program=x.bar.baz

.program="a.out".bar.baz

--set .logging.facility=mail

logging {
    facility mail;
}

program pop3d {
    logging {
       facility mail;
    }
    server 0.0.0.0 {
       transcript no;
    }
}

--set .program=pop3d.logging.facility=local1

--set .program=pop3d.server='0\.0\.0\.0'.transcript=yes

--set /program=pop3d/server="0.0.0.0"/transcript=yes

3.2.2 Configuration Variables ¶

Certain configuration statements allow for the use of variable references in their values. A variable reference has the form ‘$variable’ or ‘${variable}’, where variable is the variable name. It is expanded to the actual value of variable when Mailutils consults the configuration statement in question.

The two forms are entirely equivalent. The form with curly braces is normally used if the variable name is immediately followed by an alphanumeric symbol, which will otherwise be considered part of it. This form also allows for specifying the action to take if the variable is undefined or expands to an empty value.

During variable expansion, the forms below cause Mailutils to test for a variable that is unset or null. Omitting the colon results in a test only for a variable that is unset.

${variable:-word}

Use Default Values. If variable is unset or null, the expansion of word is substituted. Otherwise, the value of variable is substituted.

${variable:=word}

Assign Default Values. If variable is unset or null, the expansion of word is assigned to variable. The value of variable is then substituted.

${variable:?word}

Display Error if Null or Unset. If variable is null or unset, the expansion of word (or a message to that effect if word is not present) is output to the current logging channel. Otherwise, the value of variable is substituted.

${variable:+word}

Use Alternate Value. If variable is null or unset, nothing is substituted, otherwise the expansion of word is substituted.

When a value is subject to variable expansion, it is also subject to command expansion. Commands are invoked in string values using the following format:

$(cmd arg)

where cmd is the command name, and args is a list of arguments separated by whitespace. Arguments can in turn contain variable and command references.

The following commands are defined:

Command: localpart string ¶

Treats string as an email address and returns the part preceding the ‘@’ sign. If there is no ‘@’ sign, returns string.

Command: domainpart string ¶

Treats string as an email address and returns the part following the ‘@’ sign. If there is no ‘@’ sign, returns empty string.

Command: shell cmd args ¶

Runs the shell command cmd with the given arguments. Returns the standard output from the command. The command is invoked using /bin/sh -c and can contain any valid shell constructs.

The subsections below define variable names that are valid for use in each configuration statement.

3.2.3 The include Statement ¶

A special statement is provided that causes inclusion of the named file. It has the following syntax:

include file;

When reading the configuration file, this statement is effectively replaced with the content of file. It is an error if file does not exist.

In site-wide configuration file, file can be a directory name. In this case, Mailutils will search this directory for a file with the same name as the utility being executed. If found, this file will be loaded.

It is a common to end the site-wide configuration file with an include statement, e.g.:

include /etc/mailutils.d;

This allows each particular utility to have its own configuration file. Thus, imap4d will read /etc/mailutils.d/imap4d, etc.

3.2.4 The program statement ¶

Another way to configure program-specific settings is by using the program statement. The syntax is as follows:

program progname {
   ...
}

The program statement is allowed only in the site-wide configuration file. When encountered, its tag (progname) is compared with the name of the program being run. If two strings are the same, the statements between curly braces are stored in a temporary memory, otherwise the statement is ignored. When entire configuration file is loaded, the statements accumulated in the temporary storage are processed.

Notice the difference between this statement and a per-program configuration file loaded via an include statement. No matter where in the file the program statement is, its content will be processed after the content of the enclosing file. In the contrast, the per-program configuration file loaded via include is processed right where it is encountered.

3.2.5 The logging Statement ¶

Syntax ¶

logging {
  # Send diagnostics to syslog.
  syslog boolean;
  
  # Print message severity levels.
  print-severity boolean;
  
  # Output only messages with a severity equal to or
  # greater than this one.
  severity string;
  
  # Set syslog facility.
  facility name;

  # Log session ID
  session-id boolean;
    
  # Tag syslog messages with this string.
  tag text;
}

Description ¶

The logging block statement configures where the diagnostic output goes and how verbose it is.

Configuration: syslog bool ¶

If ‘syslog’ is set to ‘yes’, the diagnostics will go to syslog. Otherwise, it goes to the standard error.

The default syslog facility is determined at compile time, it can be inspected using the following command (see mailutils info):

$ mailutils info log_facility

Configuration: facility name ¶

Use syslog facility name. Valid argument values are: ‘user’, ‘daemon’, ‘auth’, ‘authpriv’, ‘mail’, ‘cron’, ‘local0’ through ‘local7’ (all names case-insensitive), or a facility number.

Configuration: tag text ¶

Tag syslog messages with text. By default, program name is used as syslog tag.

Configuration: print-severity bool ¶

Print Mailutils severity name before each message.

Configuration: severity name ¶

Output only messages with a severity equal to or greater than this one. Valid arguments are: ‘debug’, ‘info’, ‘notice’, ‘warning’, ‘error’, ‘crit’, ‘alert’, ‘emerg’,

Configuration: session-id bool ¶

Print session ID with each diagnostic message. This is useful for programs that handle multiple user sessions simultaneously, such as pop3d and imap4d.

3.2.6 The debug Statement ¶

Syntax ¶

debug {
  # Set Mailutils debugging level.
  level spec;
  
  # Prefix debug messages with Mailutils source locations.
  line-info bool;
}

Description ¶

The ‘debug’ statement controls the amount of additional debugging information output by Mailutils programs. The ‘level’ statement enables additional debugging information. Its argument (spec) is a Mailutils debugging specification as described in Debugging.

The ‘line-info’ statement, when set to ‘true’ causes debugging messages to be prefixed with locations in Mailutils source files where they appear. Normally, only Mailutils developers need this option.

3.2.7 The mailbox Statement ¶

Syntax ¶

mailbox {
  # Use specified url as a mailspool.
  mail-spool url;
  
  # Create mailbox url using pattern.
  mailbox-pattern pattern;
  
  # Default mailbox type.
  mailbox-type type;
  
  # Default user mail folder.
  folder dir;
}

Description ¶

The mailbox statement configures the location, name and type of user mailboxes.

The mailbox location can be specified using mail-spool or mail-pattern statements.

Configuration: mail-spool path ¶

The mail-spool statement specifies directory that holds user mailboxes. Once this statement is given, the libmailutils library will assume that the mailbox of user login is kept in file path/login.

Historically, path can contain mailbox type prefix, e.g.: ‘maildir:///var/spool/mail’, but such usage is discouraged in favor of mailbox-pattern statement.

Configuration: mailbox-pattern url ¶

The mailbox-pattern statement is a preferred way of configuring mailbox locations. It supersedes mail-spool statement.

The url must be a valid mailbox URL (see Mailbox), which may contain references to the ‘user’ variable (see Configuration Variables). This variable will be expanded to the actual user name.

Optional URL parameters can be used to configure indexed directory structure. Such structure is a special way of storing mailboxes, which allows for faster access in case of very large number of users.

By default, all user mailboxes are stored in a single directory and are named after user login names. To find the mailbox for a given user, the system scans the directory for the corresponding file. This usually implies linear search, so the time needed to locate a mailbox is directly proportional to the ordinal number of the mailbox in the directory.

GNU Mailutils supports three types of indexed directories: ‘direct’, ‘reverse’, and ‘hashed’.

In direct indexed directory structure, path contains 26 subdirectories named with lower-case letters of Latin alphabet. The location of the user mailbox is determined using the following algorithm:

1. Take the first letter of the user name.
2. Map it to a lower-case letter using index mapping table. The result gives the name of a sub-directory where the mailbox is located.
3. Descend into this directory.

For example, using this algorithm, the mailbox of the user ‘smith’ is stored in file path/s/smith.

If each of single-letter subdirectories contains the indexed directory structure, we have second level of indexing. In this case the file name of ‘smith’’s mailbox is path/s/m/smith.

The reverse indexed structure uses the same principles, but the indexing letters are taken from the end of the user name, instead of from the beginning. For example, in the 2nd level reverse indexed structure, the ‘smith’’s mailbox is located in path/h/t/smith.

Finally, the hashed structure consists of 256 subdirectories under path, named by 2-letter hex codes from ‘00’ to ‘FF’. Mailboxes are stored in these subdirectories. The name of the subdirectory is computed by hashing first level letters of the user name. The hashing algorithm is:

1. Take next letter from the user name
2. Add its ASCII value to the hash sum.
3. Continue (1-2) until level letters are processed, or all letters from the file name are used, whichever occurs first.
4. Convert the computed sum modulo 256 to a hex code.

Indexed directory structures are configured using the following arguments:

type=value ¶

Specifies the type of indexing. Valid values are ‘index’, for direct indexed structure, ‘rev-index’ for reverse indexing, and ‘hash’ for hashed structure.

param=number ¶

Specifies indexing level.

user=string ¶

Specifies indexing key. The only meaningful value, as of Mailutils version 3.17 is ‘user=${user}’.

Let’s assume the traditional mail layout, in which incoming mails are stored in a UNIX mailbox named after the recipient user name and located in /var/mail directory. The mailbox-pattern for this case is:

  mailbox-pattern "/var/mail/${user}";

It is entirely equivalent to specifying ‘mail-spool "/var/mail"’.

Now, if the layout is the same, but mailboxes are kept in ‘maildir’ format, then the corresponding statement is:

  mailbox-pattern "maildir:///var/mail/${user}";

Finally, if the mailboxes are stored in a directly-indexed directory with two levels of indexing, the URL is:

  mailbox-pattern "maildir:///var/mail;type=index;param=2;user=${user}";

If neither mailbox-pattern nor mail-spool are given, the mailbox names are determined using the following algorithm:

1. If environment variable FOLDER is set, use its value.
2. Otherwise, if environment variable MAIL is set, use its value.
3. If neither of these is set, construct the mailbox name by concatenating the built-in mail spool directory name, a directory separator, and the user name.

   The built-in mail spool directory name is determined at compile time, using the ‘_PATH_MAILDIR’ define from the include file paths.h. If this value is not defined, /var/mail or /usr/spool/mail is used.

Configuration: mailbox-type type ¶

Specifies the type of mailboxes. By default, ‘mbox’ (UNIX mailbox) is assumed. This can be changed while configuring the package by setting MU_DEFAULT_SCHEME configuration variable. The default value can be verified by running mailutils info scheme.

Configuration: folder dir ¶

Sets user mail folder directory. Its value is used when expanding ‘plus-notation’, i.e. such mailbox names as +inbox. The ‘+’ sign is replaced by dir, followed by a directory separator (‘/’).

The dir argument can contain mailbox type prefix, e.g ‘mh://Mail’.

The default folder name is ‘Mail/’.

3.2.8 The mime Statement ¶

Syntax ¶

mime {
  # Define additional textual mime types.
  text-type PATTERN;
  # or
  text-type ( PATTERN-LIST );
}

Description ¶

The mime compound statement is used by utilities that process MIME messages, in particular mail, readmsg, and decodemail. As of mailutils version 3.17 it contains only one statement:

Configuration: text-type pattern ¶

Configuration: text-type ( pattern-list ) ¶

Defines additional patterns for recognition of textual message parts. The pattern is a shell globbing pattern that will be compared against the ‘Content-Type’ header of a MIME message part in order to determine whether it can be treated as a text part. In second form, pattern-list is a comma-separated list of such patterns.

In both forms, the new patterns are appended to the built-in textual pattern list, which contains:

• text/*
• application/*shell
• application/shellscript
• */x-csrc
• */x-csource
• */x-diff
• */x-patch
• */x-perl
• */x-php
• */x-python
• */x-sh

3.2.9 The locking Statement ¶

Syntax ¶

locking {
  # Default locker flags.
  type default | dotlock | external | kernel | null;
  
  # Set the maximum number of times to retry acquiring the lock.
  retry-count number;
  
  # Set the delay between two successive locking attempts.
  retry-sleep arg;
  
  # Expire locks older than this amount of time.
  expire-timeout number;

  # Check if PID of the lock owner is active, steal the lock if it not. 
  pid-check bool;

  # Use prog as external locker program.
  external-locker prog;
}

Description ¶

This compound statement configures various parameters used when locking UNIX mailboxes in order to prevent simultaneous writes.

It is important to note, that locking applies only to monolithic mailboxes, i.e. mailboxes of ‘mbox’ and ‘dotmail’ types (see mbox). Other mailbox types don’t require locking.

Configuration: type string ¶

Set locking type. Allowed arguments are:

default

Default locking type. As of mailutils version 3.17, this is equivalent to dotlock.

dotlock

A ‘dotlock’-style locking. To lock a mailbox named X a lock file named X.lock is created. If pid-check yes is set, this file will contain the PID of the locking process, so that another process wishing to acquire the lock could verify if the lock is still in use.

external

Run external program to perform locking/unlocking operations. The name of the program is given by the external-locker statement (see below). If it is not given, the built-in default ‘dotlock’ is used.

The locker program is invoked as follows:

# To lock mbox:
locker -fexpire_timeout -rretry_count mbox
# To unlock it:
locker -u -fexpire_timeout -rretry_count mbox

Here, expire_timeout is the value supplied with the expire-timeout configuration statement, and retry_count is the value supplied with the retry-count statement (see below).

To properly interact with mailutils, the external locker program must use the following exit codes:

Exit code	Meaning
0	Success.
1	Failed due to an error.
2	Unlock requested (-u), but file is not locked.
3	Lock requested, but file is already locked.
4	Insufficient permissions.

See dotlock, for the description of the default external locker, shipped with mailutils.

kernel

Use kernel locking mechanism (fcntl(2)).

null

No locking at all. The statements below are silently ignored.

Configuration: retry-count number ¶

Number of locking attempts. The default is 10.

Configuration: retry-sleep seconds ¶

Configuration: retry-timeout seconds ¶

Time interval, in seconds, between two successive locking attempts. The default is 1 second. The retry-timeout statement is deprecated because of its misleading name.

Configuration: expire-timeout seconds ¶

Sets the expiration timeout. The existing lock file will be removed, if it was created more than this number of seconds ago. The default is 600.

Configuration: pid-check bool ¶

This statement can be used if locking type is set to dotlock. If set to true, it instructs the locking algorithm to check if the PID of the lock owner is still running by the time when it tries to acquire the lock. This works as follows. When the lock file is created, the PID of the creating process is written to it. If another process tries to acquire the lock and sees that the lock file already exists, it reads the PID from the file and checks if a process with that PID still exists in the process table. If it does not, the process considers the lock file to be stale, removes it and locks the mailbox.

Configuration: external-locker string ¶

Sets the name of the external locker program to use, instead of the default ‘dotlock’.

This statement is in effect only when used together with type external.

3.2.10 The mailer Statement ¶

Syntax ¶

mailer {
  url url;
}

Description ¶

A mailer is a special logical entity GNU Mailutils uses for sending messages. Its internal representation is discussed in Mailer. The mailer statement configures it.

The mailer statement contains a single sub-statement:

Configuration: url str ¶

Set the mailer URL.

GNU Mailutils supports three types of mailer URLs, described in the table below:

smtp://[user[:pass][;auth=mech,...]@]host[:port][;params]

smtps://[user[:pass][;auth=mech,...]@]host[:port][;params]

Send messages using SMTP protocol. See SMTP Mailboxes, for a detailed description of the URL and its parts.

sendmail[://progname]

Use sendmail-compatible program progname. Sendmail-compatible means that the program must support following command line options:

-oi

Do not treat ‘.’ as message terminator.

-f addr

Use addr as the sender address.

-t

Get recipient addresses from the message.

See sendmail, for details.

prog://progname?query

A prog mailer. This is a generalization of ‘sendmail’ mailer that allows to use arbitrary external programs as mailers.

It is described in detain in prog.

3.2.11 The acl Statement ¶

Syntax ¶

acl {
  # Allow connections from this IP address.
  allow [from] ip;
  
  # Deny connections from this IP address.
  deny [from] ip;
  
  # Log connections from this IP address.
  log [from] ip [string];
  
  /* Execute supplied program if a connection from this
     IP address is requested. */
  exec [from] ip program;
  
  /* Use program to decide whether to allow connection
     from ip. */
  ifexec [from] ip program;
}

Description ¶

The ACL statement defines an Access Control List, a special structure that controls who can access the given Mailutils resource.

The acl block contains a list of access controls. Each control can be regarded as a function that returns a tree-state value: ‘True’, ‘False’ and ‘Don't know’. When a remote party connects to the server, each of controls is tried in turn. If a control returns ‘False’, access is denied. If it returns ‘True’, access is allowed. If it returns ‘Don't know’, then the next control is tried. It is unclear whether to allow access if the last control in list returned ‘Don't know’. GNU Mailutils 3.17 issues a warning message and allows access. This default may change in future versions. Users are advised to write their ACLs so that the last control returns a definite answer (either True or False).

In the discussion below, wherever cidr appears as an argument, it can be replaced by any of:

• An IPv4 address in dotted-quad notation.
• An IPv6 address in numeric notation
• A CIDR in the form ‘ip/mask’, where ip is an IP address (either IPv4 or IPv6), and mask is the network mask.
• A symbolic host name.
• A word ‘any’, which matches any IP address.

The following controls are understood:

Configuration: allow [from] cidr ¶

Allow connections from IP addresses matching this cidr block.

Configuration: deny [from] cidr ¶

Deny connections from IP addresses matching this cidr block.

Configuration: ifexec [from] cidr program ¶

When a connection from the cidr block is requested, execute the program program. If its exit code is ‘0’, then allow connection. Otherwise, deny it.

The program argument undergoes variable expansion and word splitting. The following variables are defined:

aclno

Ordinal number of the control in the ACL. Numbers begin from ‘1’.

family

Connection family. Mailutils version 3.17 supports the following families: ‘AF_INET’, ‘AF_INET6’ and ‘AF_UNIX’.

address

Remote IP address (for ‘AF_INET’ and ‘AF_INET6’) or socket name (for ‘AF_UNIX’). Notice that most Unixes return empty string instead of the ‘AF_UNIX’ socket name, so do not rely on it.

port

Remote port number (for ‘AF_INET’ and ‘AF_INET6’).

Configuration: exec [from] cidr program ¶

If a connection from the cidr block is requested, execute the given program. Do not wait for it to terminate, and ignore its exit code. The program is subject for variable expansion as in ‘ifexec’.

The following two controls are provided for logging purposes and as a means of extensions. They always return a ‘Don't know’ answer, and therefore should not be used at the end of an ACL:

Configuration: log [from] cidr [string] ¶

Log connections from addresses in this cidr. The MU_DIAG_INFO channel is used. If the logging goes to syslog, it is translated to the LOG_INFO priority.

If string is not given, the format of the log entry depends on the connection family, as described in the table below:

{AF_INET ip:port}

For inet IPv4 connections. The variables ip and port are replaced by the remote IP address and port number, correspondingly.

{AF_UNIX}

For connections over UNIX sockets. The socket name, if available, may be printed before the closing curly brace.

If string is supplied, it undergoes variable expansions as described for the ‘ifexec’.

For example, the following ACL makes a Mailutils server log every incoming connection:

  acl {
     log from any "Connect from ${address}";
     ...
  }

This was the default behavior for the versions of Mailutils up to ‘1.2’, so if you got used to its logs you might wish to add the above in your configuration files.

Configuration: exec [from] cidr program ¶

If a connection from the cidr block is requested, execute the given program. Do not wait for it to terminate, and ignore its exit code.

3.2.12 The tcp-wrappers Statement ¶

Syntax ¶

tcp-wrappers {
  # Enable TCP wrapper access control.
  enable bool;
  
  # Set daemon name for TCP wrapper lookups.
  daemon name;
  
  # Use file for positive client address access control.
  allow-table file;
  
  # Use file for negative client address access control.
  deny-table file;
}

Description ¶

The tcp-wrappers statements provides an alternative way to control accesses to the resources served by GNU Mailutils. This statement is enabled if Mailutils is compiled with TCP wrappers library libwrap.

Access control using TCP wrappers is based on two files, called tables, containing access rules. There are two tables: the allow table, usually stored in file /etc/hosts.allow, and the deny table, kept in file /etc/hosts.deny. The rules in each table begin with an identifier called daemon name. A utility that wishes to verify a connection, selects the entries having its daemon name from the allow table. A connection is allowed if it matches any of these entries. Otherwise, the utility retrieves all entries with its daemon name from the deny table. If any of these matches the connection, then it is refused. Otherwise, if neither table contains matching entries, the connection is allowed.

The description of a TCP wrapper table format lies outside the scope of this document. Please, see ACCESS CONTROL FILES in hosts_access(5) man page, for details.

Configuration: enable bool ¶

Enable access control using TCP wrappers. It is on by default.

Configuration: daemon name ¶

Set daemon name for TCP wrapper lookups. By default, the name of the utility is used. E.g. imap4d uses ‘imap4d’ as the daemon name.

Configuration: allow-table file ¶

Use file as allow table. By default, /etc/hosts.allow is used.

Configuration: deny-table file ¶

Use file as negative table. By default, /etc/hosts.deny is used.

3.2.13 Server Settings ¶

GNU Mailutils offers several server applications: pop3d, imap4d, comsatd, to name a few. Being quite different in their purpose, they are very similar in some aspects of their architecture. First of all, they all support two operating modes: daemon, where a program disconnects from the controlling terminal and works in background, and inetd, where it remains in foreground and communicates with the remote party via standard input and output streams. Secondly, when operating as daemons, they listen to a preconfigured set of IP addresses and ports, reacting to requests that arrive.

To configure these aspects of functionality, GNU Mailutils provides Server Configuration Settings, which is describes in this subsection.

• General Server Configuration
• The server Statement

# Set daemon mode.
mode ‘inetd|daemon’;

# Run in foreground.
foreground bool;

# Maximum number of children processes to run simultaneously.
max-children number;

# Store PID of the master process in file.
pidfile file;

# Default port number.
port portspec;

# Set idle timeout.
timeout time;

server ipaddr[:port] {
  # Run this server as a single process.
  single-process bool;
  
  # Log the session transcript.
  transcript bool;

  # Set idle timeout.
  timeout time;

  # Size of the queue of pending connections
  backlog <number: callback>;

  # 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 { /* See ACL Statement. */ };
}

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 (see The sql Statement).

virtdomain

User credentials are retrieved from a “virtual domain” user database. Virtual domains are configured using virtdomain statement (see The virtdomain Statement).

radius

User credentials are retrieved using RADIUS. See The radius Statement, for a detailed description on how to configure it.

ldap

User credentials are retrieved from an LDAP database. See The 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 (see getpass).

pam

The user is authenticated via pluggable authentication module (PAM). The PAM service name to be used is configured in pam statement (see PAM Statement).

radius

The user is authenticated on a remote RADIUS server. See The radius Statement.

ldap

The user is authenticated using LDAP. See The 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 (see The 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 (see password file in passwd(5) man page), with encrypted passwords stored in it (as of GNU Mailutils version 3.17, 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 (see Client Configuration in GNU Radius Reference Manual). 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:

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 (see RADIUS Attributes in GNU Radius Reference Manual) to send to the server. The left-hand side of the assignment is a symbolic attribute name, as defined in one of Radius dictionaries (see Dictionary of Attributes in GNU Radius Reference Manual). 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 (see Configuration 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 (see Access-Accept in GNU Radius Reference Manual). 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 (see URL). If GNU-MU-Mailbox is not present, Mailutils constructs the mailbox name using the settings from the mailbox configuration statement (see 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 (http://www.mysql.org).

odbc

Use ODBC interface. See http://www.unixodbc.org, for a detailed description of ODBC configuration.

postgres

Interface with a PostgreSQL server (http://www.postgres.org).

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 (see crypt in crypt(3) man page).

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 (see Configuration 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 (see 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 (see Configuration 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 (see Configuration 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 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¹. 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))

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 ¶

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

<debug-spec> ::= <level-spec> | <debug-level-list>
<debug-level-list> ::= <debug-level> |
                       <debug-level-list> ";" <debug-level>
<debug-level> ::= <category> | "!" <category> |
                  <category> "." <level-list>
<level-list> ::= <level-spec> | <level-list> "," <level-spec>
<level-spec> ::=  <level> | <negate-level>
<negate-level> ::= "!" <level>
<level> ::= <level-number> | "=" <level-number> |
            <level-number> "-" <level-number>
<level-number> ::= "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.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 (see Personal and System-wide 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. See 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. See Personal and System-wide 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. See 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 (see Options That are Common for All Utilities..

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 (see The 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 Personal and System-wide 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 (see the quit command) or when switching to another mailbox (see 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 (see How to Alter the Behavior of mail). 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’.

• Syntax of mail internal commands
• Quitting the Program
• Obtaining Online Help
• Moving Within a Mailbox
• Changing Mailbox/Directory
• Controlling Header Display
• Displaying Information
• Displaying Messages
• Marking Messages
• Disposing of Messages
• Saving Messages
• Editing Messages
• Aliasing
• Replying
• Controlling Sender Fields
• Incorporating New Mail
• Shell Escapes

command [msglist] [argument ...]

write 4.1

write 4.1.2

 U  1 block@helsingor.org  Fri Jun 30 18:30  8/245    Re: The Sa
? Print 1
From: Antonius Block <block@helsingor.org>
To: Smeden Plog <plog@helsingor.org>
Date: Tue, 27 Apr 2004 13:23:41 +0300
Reply-To: <root@helsingor.org>
Subject: News

Hi

? sender mail-followup-to reply-to from
? reply
To: <root@helsingor.org>
Subject: Re: News

# Clear the sender list
? nosender
# Set new sender list
? sender From

? reply
To: Antonius Block <block@helsingor.org>
Subject: Re: News

? 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

? sender
mail-followup-to
reply-to
from
? nosender reply-to
? sender
mail-followup-to
from

? nosender
Sender address is obtained from the envelope

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

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 (see How to Alter the Behavior of mail).

• Quitting Compose Mode
• Getting Help on Compose Escapes: ~?
• Editing the Message: ~e and ~v
• Modifying the Headers: ~h, ~t, ~c, ~b, ~s
• Enclosing Another Message: ~m and ~M
• Adding a File to the Message: ~r and ~d
• Attaching a File to the Message
• Printing And Saving the Message
• Signing the Message: ~a and ~A
• Printing Another Message: ~f and ~F
• Inserting Value of a Mail Variable: ~i
• Executing Other Mail Commands: ~: and ~-
• Executing Shell Commands: ~! and ~|

~t name1@domain.net name2

~s "Re: your message"

~r filename

~< filename

~r dead.letter

~+ myfile.txt

~+ myfile.html text/html base64

~l
multipart/mixed
   1 myfile.html text/html base64

~^ 1

~: from :t

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 (see Setting and Unsetting the Variables), MIME will create MIME messages by default. The variable can be set in the global or user configuration file (see Personal and System-wide 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 </dev/null

Assume that archive.tar is not empty.

This will create a MIME message of two parts: the first part having ‘text/html’ type and empty body, and the second part of type ‘application/octet-stream’, with the content copied from the file archive.tar.

Now, if you do:

$ mail --attach=archive.tar --skip-empty-attachments </dev/null

then the created MIME message will contain only one part: that containing archive.tar.

If the file archive.tar has zero length, the resulting archive will still contain the ‘application/octet-stream’ part of zero length. However, if you place the --skip-empty-attachments option before --attach, then the produced message will be empty.

The following Perl program serves as an example of using mail from a script to construct a MIME message on the fly. It scans all mounted file systems for executable files that have setuid or setgid bits set and reports the names of those files in separate attachments. Each attachment is named after the mountpoint it describes.

The script begins with the usual prologue stating the modules that will be used:

#!/usr/bin/perl

use strict;
use autodie;

Then global variables are declared. The ‘@rcpt’ array contains the email addresses of the recipients:

my @rcpt= 'root@example.com';

The ‘@cmd’ variable holds the mail command line. It will be augmented for each file system. The initial value is set as follows:

my @cmd = ('mail',
           '-E set nonullbodymsg',
           '--content-type=text/plain');

The find utility will be used to locate the files. The script will start as many instances as there are mountpoints. Those instances will be run in parallel and their standard output streams will be connected to file descriptors passed to mail invocation in --attach-fd options.

The descriptors will be held in ‘@fds’ array. This will prevent them from being wiped out by the garbage collector. Furthermore, care should be taken to ensure that the O_CLOEXEC flag be not set for these descriptors. This sample script takes a simplistic approach: it instructs Perl not to close first 255 descriptors when executing another programs:

my @fds;
$^F = 255;

The following code obtains the list of mount points:

open(my $in, '-|', 'mount -t nonfs,noproc,nosysfs,notmpfs');
while (<$in>) {
    chomp;
    if (/^\S+ on (?<mpoint>.+) type (?<fstype>.+) /) {

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.

See Executing Shell Commands: ~! and ~|, 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.

See 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. See 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 (‘<trace7’) on mailbox and its underlying objects.

mail: string decode-fallback ¶

Default: ‘none’

This variable controls the way to represent characters that cannot be rendered using current character set. It can have three values:

‘none’

Such characters are not printed at all. The conversion process stops at the first character that cannot be rendered.

‘copy-pass’

The characters are displayed ‘as is’. Notice, that depending on your setup, this may screw-up your terminal settings.

‘copy-octal’

Unprintable characters are represented by their octal codes. Printable ones are printed ‘as is’.

mail: boolean dot ¶

Default: False

If set, causes mail to interpret a period alone on a line as the terminator of a message you are sending.

mail: boolean editheaders ¶

Default: False

When set, mail will include message headers in the text to be the ~e and ~v escapes, thus allowing you to customize the headers.

mail: boolean emptystart ¶

Default: False

If the mailbox is empty, mail normally prints ‘No mail for user’ and exits immediately. If this option is set, mail will start no matter is the mailbox empty or not.

mail: string escape ¶

Default: ‘~’

Current value of the command escape character.

mail: boolean flipr ¶

Default: Unset

If set, the variable flipr swaps the meanings of reply and Reply commands (see Replying).

mail: string folder ¶

Default: Unset

The name of the directory to use for storing folders of messages. If unset, $HOME is assumed.