/ 
Mail-Toaster-5.54
River stage zero No dependents
/ Mail::Toaster::Qmail

NAME

Mail::Toaster:::Qmail - Qmail specific functions

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.

DESCRIPTION

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.

SUBROUTINES/METHODS

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.

new

To use any of the methods following, you need to create a qmail object:

use Mail::Toaster::Qmail;
my $qmail = Mail::Toaster::Qmail->new();
build_pop3_run
$qmail->build_pop3_run() ? print "success" : print "failed";

Generate a supervise run file for qmail-pop3d. $file is the location of the file it's going to generate. I typically use it like this:

$qmail->build_pop3_run()

If it succeeds in building the file, it will install it. You should restart the service after installing a new run file.

arguments required:
   file - the temp file to construct

results:
   0 - failure
   1 - success
install_qmail_control_log_files
$qmail->install_qmail_control_log_files();

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 optional:
   prots - an arrayref list of protocols to build run files for.
          Defaults to [pop3,smtp,send,submit]

Results:
   qmail_supervise/pop3/log/run
   qmail_supervise/smtp/log/run
   qmail_supervise/send/log/run
   qmail_supervise/submit/log/run
install_supervise_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.

 $qmail->build_smtp_run()

arguments required:
arguments optional:
result:
   1 - success
   0 - error
netqmail_virgin

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( verbose=>1);

arguments optional:
   package  - the name of the programs tarball, defaults to "netqmail-1.05"

result:
   qmail installed.
send_start
$qmail->send_start() - Start up the qmail-send process.

After starting up qmail-send, we verify that it's running before returning.

send_stop
$qmail->send_stop()

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.

restart
$qmail->restart( prot=>"smtp")

Use restart to restart a supervised qmail process. It will send the TERM signal causing it to exit. It will restart immediately because it's supervised.

supervised_hostname_qmail

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)

 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
test_each_rbl
my $available = $qmail->test_each_rbl( rbls=>$selected, verbose=>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

result:
  an arrayref with the list of the correctly functioning RBLs.
build_send_run
$qmail->build_send_run() ? 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.

$qmail->build_send_run() and
      $qmail->restart( prot=>'send');

If it succeeds in building the file, it will install it. You can optionally restart qmail after installing a new run file.

arguments required:
  file - the temp file to construct

results:
  0 - failure
  1 - success
build_smtp_run
if ( $qmail->build_smtp_run( file=>$file) ) { print "success" };

Generate a supervise run file for qmail-smtpd. $file is the location of the file it's going to generate.

$qmail->build_smtp_run()

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:
   file - the temp file to construct

results:
   0 - failure
   1 - success
build_submit_run
if ( $qmail->build_submit_run( 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.

$qmail->build_submit_run( file=>$file );

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:
   file - the temp file to construct

results:
   0 - failure
   1 - success
check_service_dir

Verify the existence of the qmail service directory (typically /service/[smtp|send|pop3]).

arguments required:
   dir - the directory whose existence we test for

results:
   0 - failure
   1 - success
check_rcpthosts
$qmail->check_rcpthosts;

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

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();

results:
   0 - failure
   1 - success
control_create

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();

 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

 results:
    0 - failure
    1 - success
get_domains_from_assign

Fetch a list of domains from the qmaildir/users/assign file.

 $qmail->get_domains_from_assign;

arguments required:
   none

arguments optional:
   match - field to match (dom, uid, dir)
   value - the pattern to  match

results:
   an array
get_list_of_rbls

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( verbose => $verbose );

result:
  an arrayref of values
get_list_of_rwls
my $selected = $qmail->get_list_of_rwls( verbose=>$verbose);

Here we collect a list of the RWLs from the configuration file that gets passed to us and return them.

result:
  an arrayref with the enabled rwls.
install_qmail

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( verbose=>1);

arguments optional:
    package  - the name of the programs tarball, defaults to "qmail-1.03"

result:
    one kick a55 mail server.

Patch info is here: http://mail-toaster.org/patches/

install_qmail_control_files

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;

arguments optional:

result:
   qmail_supervise/pop3/run
   qmail_supervise/smtp/run
   qmail_supervise/send/run
   qmail_supervise/submit/run

EXAMPLES

Working examples of the usage of these methods can be found in t/Qmail.t, toaster-watcher.pl, and toaster_setup.pl.

DIAGNOSTICS

All functions include verbose output which is enabled by default. You can disable the status/verbose messages by calling the functions with verbose=>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

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.

DEPENDENCIES

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

BUGS AND LIMITATIONS

None known. When found, report to author. Patches are welcome.

TODO

SEE ALSO

 Mail::Toaster
 Mail::Toaster::Conf
 toaster.conf
 toaster-watcher.conf

http://mail-toaster.org/

AUTHOR

Matt Simerson (matt@tnpi.net)

ACKNOWLEDGEMENTS

LICENCE AND COPYRIGHT

Copyright (c) 2004-2012 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.