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
=head1 VERSION
This documentation refers to <Mail::Toaster::Qmail> version 5.00
=head1 SYNOPSIS
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.
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
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
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.
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.
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.
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
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.
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
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); };
If it succeeds in building the file, it will install it. You can optionally 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
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.
/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
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
$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
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.
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://www.tnpi.biz/internet/mail/toaster/patches/
$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.
=head1 DIAGNOSTICS 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
=head1 CONFIGURATION AND ENVIRONMENT 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/
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.