Mailmin Usage

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

@save myfile /bin/sh < myfile

(The @save Mailmin directive is explained below.)]

You can transfer files to and from the remote system and request web content with the @save, @attach and @wattach Mailmin directives respectively, as explained below.

Mailmin directives

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.

If 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:
- no arguments - Mailmin will attempt to save anything that looks like an attached file to the default save directory ($HOME by default).
- one argument - Mailmin will attempt to save any attachments whose recommended external filename matches the argument to the default save directory.
- two arguments - If the second argument matches a directory on the remote system, Mailmin will attempt to save attachments matching the first argument into that directory. If the second argument doesn't match a directory, Mailmin will assume that it is a filename and will attempt to save attachments matching the first argument to that filename.
By default, Mailmin will not overwrite an existing file. Use -f or --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 @wattach directive.

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

Variable Assignment

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 archive_type of 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.

Exit Codes

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

Note that error codes 1 - 4 imply termination before message processing, while error code 5 (or 0, of course) implies that the message has been processed.

Logging and Debug Mode

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.