[Note: this page assumes that Mailmin is operating in normal mode. See here for an explanation of restricted mode.]
Once Mailmin has been correctly configured, usage is quite simple. Just compose an email containing system commands and Mailmin directives (explained below), address, sign and encrypt it appropriately, and mail it. Mailmin will receive your mail, decrypt it and verify the signature, and execute the commands it contains via the shell.
Mailmin will collect the commands' output, place it into the body of an email message, sign and encrypt it, and send it back to you. [The current implementation sends it to the address of the sender as given in the incoming messages
From: email header.]
[Note that for technical reasons, Mailmin currently invokes a separate shell for each command. To execute multiple commands using the same shell, you can do something like this: place them in a file, attach the file to your message, and in the body of your message include the lines:
/bin/sh < myfile
@save Mailmin directive is explained below.)]
You can transfer files to and from the remote system and request web content with the
@wattach Mailmin directives respectively, as explained below.
Any line of your message whose first (non-whitespace) character is an
'@' will be interpreted as a Mailmin directive; it will be intercepted and processed by Mailmin and not passed on to the shell.
The following directives are currently implemented:
@attach somefile - this instructs Mailmin to attach the file
somefile to its response.
somefile is a directory, it will be recursively placed into a compressed archive (the type of which is determined by the
archive_type configuration variable) which is then attached to the response. Be careful of doing this with a large directory tree!
@save [-f | --force] [filename [destination]]- this instructs Mailmin to save one or more attachments (of the incoming Mailmin message) to the remote filesystem. The behavior depends on the number of arguments provided:
By default, Mailmin will not overwrite an existing file. Use
--force to override.
@wattach [wget options] [url1] [url2] ... - this instructs Mailmin to invoke
wget to retrieve the requested urls (and, by default, their prerequisites), invoke the appropriate utilities to archive and compress the retrieved content, and finally attach the resulting compressed archive to its reply. See the the configuration page and the included sample configuration file for details.
Note that any options specified with the directive will be passed to wget and will override the default options or those given in the Mailmin configuration file or command line. To be precise, Mailmin constructs the wget command by concatenating the variable
wget, the variable
wget_opts and then anything following the
@wattach directive. Several urls can therefore be specified with the same
@end- tells Mailmin to quit processing the message. This is normally unnecessary, since Mailmin will just read until the end of the message and then proceed, but it can be useful if something is appending stuff (e.g advertising, virus scan information or a legal notice) to your email.
Any line of your message whose first (non-whitespace) character is a
'$' will be interpreted as a Mailmin variable assignment; it will be intercepted and processed by Mailmin and not passed on to the shell. DO NOT use quotes around the variable value.
For example, if Mailmin has been configured with an
gzip but you want it to send you some PKZIP style archived web content, you could use the following:
@at = zip @wattach some_url
All (user configurable) Mailmin variables are documented in the sample configuration file.
Mailmin returns 0 on successful execution, and non-zero if an error occurs:
|1||Failure reading specified configuration file, or the file is group or world writeable|
|2||Failure parsing the message|
|3||Failure of the initial GnuPG invocation|
|4||Successful GnuPG invocation, but subsequent rejection of the mail based on a GnuPG key related problem (e.g. an unsigned message, or one signed by an unauthorized key, and Restricted Mode has not been enabled)|
|5||Failure of the final GnuPG invocation|
Beginning with version 0.4, Mailmin supports robust and flexible logging via the Log::Dispatch bundle, now a dependency. Logging is not enabled by default; see the sample configuration file for details on enabling it and selecting a log level.
Mailmin has had a debug option since version 0.3 (see the sample configuration file). With version 0.4, this has been reimplemented to use the Log::Dispatch system. Without debugging set, nothing is printed to standard error unless a terminal error (one of the conditions resulting in a non-zero error code) occurs. With debugging set, all messages that are logged with even the lowest priority ('
debug') are sent to standard error.