Mu
Mu 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.
Syntax
Mu is a command line tool. Its invocation syntax is:
mu [options] command [args]
where options are options that affect the behavior of mu 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 wickets for matching URLs
help
The mu help command lists all available options and command names along with short descriptions of what each of them does. It is similar to the mu --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.:
mu help ldflags
will output help for the ldflags command. It is synonymous to the --help option used with that particular command, e.g.: mu ldflags --help.
info
The mu info command displays information about Mailutils compile-time configuration. In normal form its output lists a single configuration flag per line, e.g.:
$ mu 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 mu 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:
$ mu 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 ...
cflags
The mu 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 `mu cflags`
ldflags
The mu ldflag command is a counterpart of cflags used for linking. It constructs a ld(1) 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:
$ mu 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:
$ mu 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.
- nntp
- Link in the NNTP 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).
- compat
- Provide a compatibility layer for Mailutils 2.x.
- auth
- Link in the Mailutils authentication library.
- guile
- Provide Guile language bindings.
- python
- Provide Python language bindings.
- cfg
- Link in the Mailutils configuration library.
- argp
- Link in the library for command line parsing.
query
The mu query command queries values from Mailutils configuration files. It takes one or more configuration 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:
$ mu query .logging.syslog
syslog yes;
$ mu query .logging.syslog .logging.facility
syslog yes;
facility mail;
$ mu 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:
$ mu query --value .logging.syslog yes
The --path option instructs it to print full path names for each value:
$ mu query --path .logging.syslog logging.syslog: yes
The --program option instructs mu to behave as if it was called under another program name. For example, the following command:
$ mu query --program=pop3d .server.transcript
will return the value of the server.transcript statement for pop3d utility.
By default, mu query operates on the main configuration file. Another configuration file can be supplied using the --file (-f) option:
$ mu query --file /usr/local/etc/file.conf .pidfile
2047
The mu 2047 command is a filter for decoding or encoding email message headers formatted in accordance with RFC 2047. 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 examle:
$ mu 2047 'Keld Jørn Simonsen <keld@dkuug.dk>' =?ISO-8859-1?Q?Keld_J=F8rn_Simonsen?= <keld@dkuug.dk>
The decode mode can be requested via the --decode (-d) option:
$ mu 2047 --decode '=?ISO-8859-1?Q?Keld_J=F8rn_Simonsen?= <keld@dkuug.dk>' Keld Jørn Simonsen <keld@dkuug.dk>
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:
$ mu 2047 --charset=utf-8 'Keld Jørn Simonsen <keld@dkuug.dk>' =?utf-8?Q?Keld J=C3=B8rn Simonsen <keld@dkuug.dk>?=
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.
filter
Applies a chain of filters to the input.
acl
Tests Mailutils access control lists;
wicket
Scans wickets for matching URLs
dbm
The mu dbm tool manages DBM files using libmu_dbm. The invocation syntax is:
mu dbm command [options] file [keys]
or
mu dbm [options] command file [keys]
where command 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.
Create a Database
The create command instructs the tool to create a new database:
mu 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 dbm tool 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:
mu 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:
mu 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:
mu dbm create --file input.txt --copy-permissions file.db
The --copy-permissions (-P) option is 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. 1.0) 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:
mu dbm create --file users.dump
Add Records to a Database
The add command adds records to a database. Records are read from the standard input and must be formatted as for create command.
mu 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 command instead.
The same options that affect the behavior of create apply to add and replace as well, e.g.:
mu dbm replace --file input.txt --copy-permissions file.db
Delete Records
To delete records, use the delete command. It reads a list of keys to delete to be specified as arguments in the command line:
mu 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:
mu dbm delete file.db 'foo*[0-9]'
(note the quoting necessary to prevent shell from interpreting the metacharacters itself).
Another option, --regex (-R) instructs mu to treat keys as extended regular expressions:
mu 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.
List the Database
The list command lists the content of the database:
mu dbm list file.db
By default, entire content is listed on the standard output in format 0.0. This format is selected as default because it is human readable: each output line represents a single record, with key and value parts separated by a single TAB character. If the database contains some binary data, or if the file produced by list command is to be used as a backup or a means of transferring the database to another machines, it is preferable to use format 1.0 instead. To do so, use the --format (-H) option:
mu dbm list --format 1.0 file.db
Whatever output format is selected, it is suitable for input to the create command. Among other uses, this provides for an easy way to convert databases between various formats supported by Mailutils. For example the example below converts the database file file.db to the GDBM database new.db:
mu dbm list file.db | mu dbm create gdbm://new.db
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:
$ mu 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 are described in detail above.
logger
The mu logger tool logs information using Mailutils log facility.
Syntax:
mu 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 $ mu logger I am here # Log each line from file.txt $ mu logger --file file.txt # Read stdin and log it: $ mu logger
The default logging channel is bound to standard error. To bind it to syslog, use the --syslog command line option. In that case mu 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. Thus, the following invocation will use facility auth, severity info:
mu logger --priority auth.info
The syslog tag can be set using the --tag (-t) option:
mu 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 strings: 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:
mu logger --locus mailutils.rc:34 Suspicious statement
will send the following to the log:
mu-logger: mailutils.rc:34: Suspicious statement
pop
Invokes a POP3 client shell.
imap
Invokes an IMAP4 client shell (in development).
