Difference between revisions of "Mu"

From Mailutils
Jump to navigationJump to search
(Change to a redirect link)
 
(44 intermediate revisions by the same user not shown)
Line 1: Line 1:
{{Note|This article is not yet finished}}
+
#REDIRECT [[Mailutils_(utility)]]
<tt>Mu</tt> 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 ==
 
 
 
<tt>Mu</tt> is a command line tool.  Its invocation syntax is:
 
 
 
<code>
 
mu [''options''] ''command'' [''args'']
 
</code>
 
 
 
where ''options'' are options that affect the behavior of <tt>mu</tt> 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 [http://www.manpagez.com/man/1/ld ld](1) command line for linking a program with Mailutils.
 
;logger
 
:Logs information using Mailutils log facility.
 
;pop
 
:Invokes a POP3 client shell.
 
;query
 
:Queries configuration values.
 
;wicket
 
Scans [[wicket]]s for matching URLs
 
 
 
== help ==
 
The <tt>mu help</tt> command lists all available options and command names along with short descriptions of what each of them does.  It is similar to the <tt>mu --help</tt> option.
 
 
 
A command name can be supplied as an argument to <tt>help</tt>, in which case it will display a help page for that particular command, e.g.:
 
 
 
  mu help ldflags
 
 
 
will output help for the [[#ldflags|ldflags]] command.  It is synonymous to the <tt>--help</tt> option used with that particular command, e.g.: <tt>mu ldflags --help</tt>.
 
 
 
== info ==
 
The <tt>mu info</tt> 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, <tt>IPV6</tt> means that Mailutils was compiled with support for IPv6, whereas <tt>SYSCONFDIR=/etc</tt> means that the default place for configuration files is in <tt>/etc</tt> directory.
 
 
 
Such short output is convenient for using <tt>mu info</tt> in scripts to decide whether it is possible to use a given feature.  To assist human users, the <tt>--verbose</tt> (<tt>-v</tt>) 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 <tt>mu cflags</tt> 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 <tt>mu ldflag</tt> command is a counterpart of <tt>cflags</tt> used for linking.  It constructs a [http://www.manpagez.com/man/1/ld ld](1) command line for linking a program with Mailutils.
 
 
 
When used without arguments, it outputs <tt>ld</tt> 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 <tt>all</tt> 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 [[mailer]]s.
 
;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 [[libmu_cfg|Mailutils configuration library]].
 
;argp
 
:Link in the library for command line parsing.
 
 
 
== query ==
 
The <tt>mu query</tt> command queries values from Mailutils configuration files.  It takes one or more [[configuration path]]s 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:
 
 
 
<source lang="C">
 
  logging {
 
    syslog yes;
 
    facility mail;
 
  };
 
</source>
 
 
 
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 <tt>--value</tt> option instructs the command to output only values:
 
 
 
  $ mu query --value .logging.syslog
 
  yes
 
 
 
The <tt>--path</tt> option instructs it to print full path names for each value:
 
 
 
  $ mu query --path .logging.syslog
 
  logging.syslog: yes
 
 
 
The <tt>--program</tt> option instructs <tt>mu</tt> 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 <tt>server.transcript</tt> statement for <tt>pop3d</tt> utility.
 
 
 
By default, <tt>mu query</tt> operates on the main configuration file.  Another configuration file can be supplied using the <tt>--file</tt> (<tt>-f</tt>) option:
 
 
 
  $ mu query --file /usr/local/etc/file.conf .pidfile
 
 
 
== 2047 ==
 
The <tt>mu 2047</tt> command is a filter for decoding or encoding email message headers formatted in accordance with [http://www.faqs.org/rfcs/rfc2047.html 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 <tt>--decode</tt> (<tt>-d</tt>) option:
 
 
 
  $ mu 2047 --decode '=?ISO-8859-1?Q?Keld_J=F8rn_Simonsen?= <keld@dkuug.dk>'
 
  Keld Jørn Simonsen <keld@dkuug.dk>
 
 
 
The <tt>--charset</tt> (<tt>-c</tt>) 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 <tt>--encoding</tt> (<tt>-E</tt>) option can be used in encode mode to change the output encoding.  Valid arguments for this option are: <tt>quoted-printable</tt> (the default) or <tt>base64</tt>.
 
 
 
The <tt>--newline</tt> (<tt>-n</tt>) 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 [[wicket]]s for matching URLs
 
 
 
== dbm ==
 
The <tt>mu dbm</tt> 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 ''command''s 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 <tt>create</tt> 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 <tt>dbm</tt> tool supports several formats for these data, which are [[#Dump Formats|discussed later]].  In the simplest case (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: <tt>--file</tt> (<tt>-f</tt>).  Thus, the following command is equivalent to the one above:
 
 
 
  mu dbm create --file input.txt file.db
 
 
 
The <tt>--file</tt> 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 <tt>--copy-permissions</tt> (<tt>-P</tt>) option is one that does the job.
 
 
 
There are also other ways to control mode and ownership of the created database, which are [[#options|described below]].
 
 
 
More advanced dump formats (e.g. [[#Format 1.0|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 <tt>users.dump</tt> 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 <tt>add</tt> command adds records to a database.  Records are read from the standard input and must be formatted as described above:
 
 
 
  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 <tt>replace</tt> command instead. 
 
 
 
The same options that affect the behavior of <tt>create</tt> apply to <tt>add</tt> and <tt>replace</tt> as well, e.g.:
 
 
 
  mu dbm replace --file input.txt --copy-permissions file.db
 
 
 
=== Delete Records ===
 
To delete records, use the <tt>delete</tt> 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 <tt>file.db</tt> records with keys <tt>foo</tt> and <tt>bar</tt>. 
 
 
 
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.
 
 
 
<div id="patterns"></div>
 
The <tt>--glob</tt> (<tt>-G</tt>) option instructs the tool to use UNIX globbing pattern matching.  For example, the command below will delete all keys starting with <tt>foo</tt> 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, <tt>--regex</tt> (<tt>-R</tt>) instructs <tt>mu</tt> to treat keys as extended regular expressions:
 
 
 
  mu dbm delete --regex file.db 'foo.*[0-9]{1,3}'
 
 
 
Both options are affected by the <tt>--ignore-case</tt> (<tt>-i</tt>) 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 the Database|list mode]] described below to verify that the patterns match the right keys.
 
 
 
=== List the Database ===
 
The <tt>list</tt> 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|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 <tt>list</tt> command is to be used as a backup or a means of transferring the database to another machines, it is preferable to use format [[#Format 1.0|1.0]] instead.  To do so, use the <tt>--format</tt> (<tt>-H</tt>) option:
 
 
 
  mu dbm list --format 1.0 file.db
 
 
 
Whatever output format is selected, it is suitable for input to the <tt>create</tt> 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 <tt>--glob</tt> and <tt>--regex</tt> options instruct the tool to use UNIX globbing or extended regular expression matching, correspondingly.  These are described in detail [[#patterns|above]].
 
 
 
== logger ==
 
The <tt>mu logger</tt> 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 <tt>--file</tt> 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 <tt>--syslog</tt> command line option. In that case <tt>mu</tt> uses facility <tt>user</tt> and priority <tt>err</tt>.  You can change this by using the <tt>--priority</tt> (<tt>-p</tt>) 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 <tt>auth</tt>, severity <tt>info</tt>:
 
 
 
  mu logger --priority auth.info
 
 
 
The syslog tag can be set using the <tt>--tag</tt> (<tt>-t</tt>) option:
 
 
 
  mu logger --tag myprog
 
 
 
The default tag is <tt>mu-logger</tt>.
 
 
 
The <tt>--severity</tt> (<tt>-s</tt>) option sets the Mailutils severity level.  Its argument can be any of the following strings: <tt>debug</tt>, <tt>info</tt>, <tt>notice</tt>, <tt>warning</tt>, <tt>error</tt>, <tt>crit</tt>, <tt>alert</tt>, <tt>emerg</tt>.
 
 
 
Finally, the <tt>--locus</tt> (<tt>-l</tt>) 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).
 

Latest revision as of 10:37, 11 July 2015