|
|
| (46 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 ''mode'' [''options''] ''file'' [''keys'']
| |
| − | | |
| − | where ''mode'' selects the operation mode, ''options'' modify the tool behavior and ''file'' specifies the DBM file to operate upon. Some ''mode''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> (<tt>-c</tt>) mode specifier 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> (<tt>-a</tt>) mode 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> (<tt>-t</tt>) mode 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> (<tt>-d</tt>) mode. 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> (<tt>-l</tt>) mode 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. This output format is suitable for use as input to the <tt>--create</tt> mode. 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).
| |
