Runs the following tests: make sure toaster.conf exists make sure qmail_dir exists make sure vpopmail home dir exists make sure qmail_supervise is set and is not a directory
Mail::Toaster:::Qmail - Qmail specific functions
This documentation refers to <Mail::Toaster::Qmail> version 5.00
use Mail::Toaster::Qmail; my $qmail = Mail::Toaster::Qmail->new(); $qmail->install();
Mail::Toaster::Qmail is a module of Mail::Toaster. It contains methods for use with qmail, like starting and stopping the deamons, installing qmail, checking the contents of config files, etc. Nearly all functionality contained herein is accessed via toaster_setup.pl.
See http://mail-toaster.org/ for details.
A full description of the module and its features. May include numerous subsections (i.e. =head2, =head3, etc.)
This module has all sorts of goodies, the most useful of which are the build_????_run modules which build your qmail control files for you. See the METHODS section for more details.
An object of this class represents a means for interacting with qmail. There are functions for starting, stopping, installing, generating run-time config files, building ssl temp keys, testing functionality, monitoring processes, and training your spam filters.
To use any of the methods following, you need to create a qmail object:
use Mail::Toaster::Qmail; my $qmail = Mail::Toaster::Qmail->new();
$qmail->build_pop3_run( conf=>$conf, file=>$file, debug=>$debug) ? print "success" : print "failed";
Generate a supervise run file for qmail-pop3d. $file is the location of the file it's going to generate. $conf is a list of configuration variables pulled from a config file (see $utility->parse_config). I typically use it like this:
my $file = "/tmp/toaster-watcher-pop3-runfile"; if ( $qmail->build_pop3_run( conf=>$conf, file=>$file ) ) { $qmail->install_supervise_run( tmpfile=>$file, prot=>"pop3", conf=>$conf); };
If it succeeds in building the file, it will install it. You should restart the service after installing a new run file.
arguments required: conf - as hashref with the contents of toaster-watcher.conf file - the temp file to construct arguments optional: debug fatal results: 0 - failure 1 - success
$qmail->install_qmail_control_log_files( conf=>$conf );
$conf is a hash of values. See $utility->parse_config or toaster-watcher.conf for config values.
Installs the files that control your supervised processes logging. Typically this consists of qmail-smtpd, qmail-send, and qmail-pop3d. The generated files are:
arguments required: conf arguments optional: prots - an arrayref list of protocols to build run files for. Defaults to [pop3,smtp,send,submit] debug fatal Results: qmail_supervise/pop3/log/run qmail_supervise/smtp/log/run qmail_supervise/send/log/run qmail_supervise/submit/log/run
Installs a new supervise/run file for a supervised service. It first builds a new file, then compares it to the existing one and installs the new file if it has changed. It optionally notifies the admin.
my $file = "/tmp/mtw-smtpd-runfile"; if ( $qmail->build_smtp_run( conf=>$conf, tmpfile=>$file, debug=>$debug ) ) { $qmail->install_supervise_run( tmpfile=>$file, prot=>"smtp", debug=>$debug ); }; arguments required: tmpfile - new file that was created (typically /tmp/something) destination - either set it explicitely, or set prot. arguments optional: conf destination - where the tmpfile gets installed to. Defaults to $service/$prot/run prot - one of (smtp, send, pop3, submit) debug fatal result: 1 - success 0 - error
Builds and installs a pristine netqmail. This is necessary to resolve a chicken and egg problem. You can't apply the toaster patches (specifically chkuser) against netqmail until vpopmail is installed, and you can't install vpopmail without qmail being installed. After installing this, and then vpopmail, you can rebuild netqmail with the toaster patches.
Usage: $qmail->netqmail_virgin( conf=>$conf, debug=>1); arguments required: conf - a hash of values from toaster-watcher.conf arguments optional: package - the name of the programs tarball, defaults to "netqmail-1.05" debug fatal result: qmail installed.
queue_process - Tell qmail to process the queue immediately
$qmail->restart( conf=>$conf )
Use to restart the qmail-send process. It will send qmail-send the TERM signal and then return.
$qmail->send_start( conf=>$conf ) - Start up the qmail-send process.
After starting up qmail-send, we verify that it's running before returning.
$qmail->send_stop( conf=>$conf )
Use send_stop to quit the qmail-send process. It will send qmail-send the TERM signal and then wait until it's shut down before returning. If qmail-send fails to shut down within 100 seconds, then we force kill it, causing it to abort any outbound SMTP sessions that are active. This is safe, as qmail will attempt to deliver them again, and again until it succeeds.
This is necessary because things such as service directories are now in /var/service by default but older versions of my toaster installed them in /service. This will detect and adjust for that.
Example $qmail->service_dir_get( conf=>$conf, prot=>'smtp' ); arguments required: prot is one of these protocols: smtp, pop3, submit, send arguments optional: conf - a hash of values from toaster-watcher.conf debug fatal result: 0 - failure a directory upon success
$qmail->smtpd_restart( conf=>$conf, prot=>"smtp")
Use smtpd_restart to restart the qmail-smtpd process. It will send qmail-smtpd the TERM signal causing it to exit. It will restart immediately because it's supervised.
my $dir = $qmail->supervise_dir_get( conf=>$conf, prot=>"smtp" );
This sub just sets the supervise directory used by the various qmail services (qmail-smtpd, qmail-send, qmail-pop3d, qmail-submit). It sets the values according to your preferences in toaster-watcher.conf. If any settings are missing from the config, it chooses reasonable defaults.
This is used primarily to allow you to set your mail system up in ways that are a different than mine, like a LWQ install.
Gets/sets the qmail hostname for use in supervise/run scripts. It dynamically creates and returns those hostname portion of said run file such as this one based on the settings in $conf.
arguments required: prot - the protocol name (pop3, smtp, submit, send) arguments optional: result: an array representing the hostname setting portion of the shell script */run. Example result: LOCAL=`head -1 /var/qmail/control/me` if [ -z "$LOCAL" ]; then echo ERROR: /var/service/pop3/run tried reading your hostname from /var/qmail/control/me and failed! exit 1 fi
my $available = $qmail->test_each_rbl( rbls=>$selected, debug=>1 );
We get a list of RBL's in an arrayref, run some tests on them to determine if they are working correctly, and pass back the working ones in an arrayref.
arguments required: rbls - an arrayref with a list of RBL zones arguments optional: conf - conf settings from toaster-watcher.conf debug - print status messages result: an arrayref with the list of the correctly functioning RBLs.
$qmail->build_send_run( conf=>$conf, file=>$file) ? print "success";
build_send_run generates a supervise run file for qmail-send. $file is the location of the file it's going to generate. $conf is a list of configuration variables pulled from toaster-watcher.conf. I typically use it like this:
my $file = "/tmp/toaster-watcher-send-runfile"; if ( $qmail->build_send_run( conf=>$conf, file=>$file ) ) { $qmail->install_supervise_run( tmpfile=>$file, prot=>"send", conf=>$conf); $qmail->restart($conf, $debug); };
If it succeeds in building the file, it will install it. You can optionally restart qmail after installing a new run file.
if ( $qmail->build_smtp_run( conf=>$conf, file=>$file) ) { print "success" };
Generate a supervise run file for qmail-smtpd. $file is the location of the file it's going to generate. $conf is a list of configuration variables pulled from a config file (see ParseConfigfile). I typically use it like this:
my $file = "/tmp/toaster-watcher-smtpd-runfile"; if ( $qmail->build_smtp_run( conf=>$conf, file=>$file ) ) { $qmail->install_supervise_run( tmpfile=>$file, prot=>"smtp", conf=>$conf); };
If it succeeds in building the file, it will install it. You can optionally restart the service after installing a new run file.
if ( $qmail->build_submit_run( conf=>$conf, file=>$file ) ) { print "success"};
Generate a supervise run file for qmail-smtpd running on submit. $file is the location of the file it's going to generate. $conf is a list of configuration variables pulled from a config file (see ParseConfigfile). I typically use it like this:
my $file = "/tmp/toaster-watcher-smtpd-runfile"; if ( $qmail->build_submit_run( conf=>$conf, file=>$file ) ) { $qmail->install_supervise_run( tmpfile=>$file, prot=>"submit", conf=>$conf); };
Verify the existence of the qmail control directory (typically /var/qmail/control).
arguments required: dir - the directory whose existence we test for arguments optional: debug fatal results: 0 - failure 1 - success
$qmail->check_rcpthosts($qmaildir);
Checks the control/rcpthosts file and compares its contents to users/assign. Any zones that are in users/assign but not in control/rcpthosts or control/morercpthosts will be presented as a list and you will be expected to add them to morercpthosts.
arguments required: none arguments optional: dir - defaults to /var/qmail result instructions to repair any problem discovered.
Qmail is nice because it is quite easy to configure. Just edit files and put the right values in them. However, many find that a problem because it is not so easy to always know the syntax for what goes in every file, and exactly where that file might be. This sub takes your values from toaster-watcher.conf and puts them where they need to be. It modifies the following files:
/var/qmail/control/concurrencyremote /var/qmail/control/me /var/qmail/control/mfcheck /var/qmail/control/spfbehavior /var/qmail/control/tarpitcount /var/qmail/control/tarpitdelay /var/qmail/control/sql /var/qmail/control/locals /var/qmail/alias/.qmail-postmaster /var/qmail/alias/.qmail-root /var/qmail/alias/.qmail-mailer-daemon FreeBSD specific: /etc/rc.conf /etc/mail/mailer.conf /etc/make.conf
You should not manually edit these files. Instead, make changes in toaster-watcher.conf and allow it to keep them updated.
Usage: $qmail->config( conf=>$conf); arguments required: conf - as hashref with the contents of toaster-watcher.conf arguments optional: debug fatal results: 0 - failure 1 - success
To make managing qmail a bit easier, we install a control script that allows the administrator to interact with the running qmail processes.
Usage: $qmail->control_create(conf=>$conf); Sample Output /usr/local/sbin/qmail {restart|doqueue|flush|reload|stat|pause|cont|cdb|queue|help} # qmail help pause -- temporarily stops mail service (connections accepted, nothing leaves) cont -- continues paused mail service stat -- displays status of mail service cdb -- rebuild the cdb files (tcp.smtp, users, simcontrol) restart -- stops and restarts smtp, sends qmail-send a TERM & restarts it doqueue -- sends qmail-send ALRM, scheduling queued messages for delivery reload -- sends qmail-send HUP, rereading locals and virtualdomains queue -- shows status of queue alrm -- same as doqueue hup -- same as reload arguments required: conf - as hashref with the contents of toaster-watcher.conf arguments optional: debug fatal results: 0 - failure 1 - success
Fetch a list of domains from the qmaildir/users/assign file.
$qmail->get_domains_from_assign( assign=>$assign, debug=>$debug ); arguments required: none arguments optional: assign - the path to the assign file (default: /var/qmail/users/assign) debug match - field to match (dom, uid, dir) value - the pattern to match results: an array
Gets passed a hashref of values and extracts all the RBLs that are enabled in the file. See the toaster-watcher.conf file and the rbl_ settings therein for the format expected. See also the t/Qmail.t for examples of usage.
my $r = $qmail->get_list_of_rbls( conf => $hashref, debug => $debug ); arguments required: conf - a hashref of values, usually the contents of toaster-watcher.conf arguments optional: debug result: an arrayref of values
my $selected = $qmail->get_list_of_rwls( conf=>$conf, debug=>$debug);
Here we collect a list of the RWLs from the configuration file that gets passed to us and return them.
arguments required: conf - a hashref, typically the contents of toaster-watcher.conf arguments optional: debug fatal result: an arrayref with the enabled rwls.
Builds qmail and installs qmail with patches (based on your settings in toaster-watcher.conf), installs the SSL certs, adjusts the permissions of several files that need it.
Usage: $qmail->install_qmail( conf=>$conf, debug=>1); arguments required: conf - a hash of values from toaster-watcher.conf arguments optional: package - the name of the programs tarball, defaults to "qmail-1.03" debug fatal result: one kick a55 mail server.
Patch info is here: http://mail-toaster.org/patches/
When qmail is first installed, it needs some supervised run files to run under tcpserver and daemontools. This sub generates the qmail/supervise/*/run files based on your settings. Perpetual updates are performed by toaster-watcher.pl.
$qmail->install_qmail_control_files( conf=>$conf, debug=>$debug); arguments required: conf - a hash of values from toaster-watcher.conf arguments optional: debug fatal result: qmail_supervise/pop3/run qmail_supervise/smtp/run qmail_supervise/send/run qmail_supervise/submit/run
Working examples of the usage of these methods can be found in t/Qmail.t, toaster-watcher.pl, and toaster_setup.pl.
All functions include debugging output which is enabled by default. You can disable the status/debugging messages by calling the functions with debug=>0. The default behavior is to die upon errors. That too can be overriddent by setting fatal=>0. See the tests in t/Qmail.t for code examples.
#=head1 COMMON USAGE MISTAKES
Nearly all of the configuration options can be manipulated by setting the appropriate values in toaster-watcher.conf. After making changes in toaster-watcher.conf, you can run toaster-watcher.pl and your changes will propagate immediately, or simply wait a few minutes for them to take effect.
A list of all the other modules that this module relies upon, including any restrictions on versions, and an indication whether these required modules are part of the standard Perl distribution, part of the module's distribution, or must be installed separately.
Params::Validate - from CPAN Mail::Toaster - with package Mail::Toaster::Utility - with package Mail::Toaster::Perl - with package
None known. When found, report to author. Patches are welcome.
Mail::Toaster Mail::Toaster::Conf toaster.conf toaster-watcher.conf http://mail-toaster.org/
Matt Simerson (matt@tnpi.net)
Copyright (c) <year> The Network People, Inc. (info@tnpi.net). All rights reserved.
Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met:
Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer.
Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution.
Neither the name of the The Network People, Inc. nor the names of its contributors may be used to endorse or promote products derived from this software without specific prior written permission.
THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
To install Mail::Toaster, copy and paste the appropriate command in to your terminal.
cpanm
cpanm Mail::Toaster
CPAN shell
perl -MCPAN -e shell install Mail::Toaster
For more information on module installation, please visit the detailed CPAN module installation guide.