Mail::Toaster::Qmail

- NAME
- SYNOPSIS
- DESCRIPTION
- METHODS

- new
- netqmail_virgin
- set_supervise_dir
- netqmail
- install_qmail
- get_list_of_rwls
- test_each_rbl
- get_list_of_rbls
- build_send_run
- build_pop3_run
- test_smtpd_config_values
- set_service_dir
- build_smtp_run
- build_submit_run
- install_qmail_service_run
- smtpd_restart
- restart
- send_stop
- send_start
- queue_process
- check_rcpthosts
- config
- configure_qmail_control
- install_supervise_run
- install_supervise_log_run
- get_domains_from_assign

- AUTHOR
- BUGS
- TODO
- SEE ALSO
- COPYRIGHT

# NAME

Mail::Toaster:::Qmail - Common Qmail functions

# SYNOPSIS

Mail::Toaster::Qmail is frequently used functions I've written for perl use with Qmail.

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

# METHODS

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

## netqmail_virgin

Builds and installs a pristine net-qmail. 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.

            $qmail->netqmail_virgin($conf, $package);

$conf is a hash of values from toaster-watcher.conf used to determine how to configure qmail.

$package is the name of the program. It defaults to ``qmail-1.03''

## set_supervise_dir

            my $dir = $qmail->set_supervise_dir($conf, "smtp", $debug);

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.

## netqmail

Builds net-qmail with patches (based on your settings in toaster-watcher.conf), installs the SSL certs, adjusts the permissions of several files that need it.

            $qmail->netqmail($conf, $package);

$conf is a hash of values from toaster-watcher.conf

$package is the name of the program. It defaults to ``qmail-1.03''

Patch info is here: http://www.tnpi.biz/internet/mail/toaster/patches/

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

            $qmail->install_qmail($conf, $package);

$conf is a hash of values from toaster-watcher.conf

$package is the name of the program. It defaults to ``qmail-1.03''

Patch info is here: http://www.tnpi.biz/internet/mail/toaster/patches/

## get_list_of_rwls

            my $selected = $qmail->get_list_of_rwls($conf, $debug);

Here we collect a list of the RWLs from the configuration file that get's passed to us.

returns an arrayref with a list of the enabled list from your config file.

## test_each_rbl

            my $available = $qmail->test_each_rbl($selected, $debug);

We get a list of RBL's in an arrayref and we run some tests on them to determine if they are working correctly.

returns a list of the correctly functioning RBLs.

## get_list_of_rbls

            my $selected = $qmail->get_list_of_rbls($arrayref, $debug);

We get passed a configuration file (toaster-watcher.conf) and from it we extract all the RBL's the user has selected.

returns an array ref.

## build_send_run

            $qmail->build_send_run($conf, $file, $debug) ? 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, $file ) )
            {
                    $qmail->install_qmail_service_run( {file=>$file, service=>"send"}, $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.

## build_pop3_run

            $qmail->build_pop3_run($conf, $file, $debug) ? print "success";

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 ParseConfigfile). I typically use it like this:

            my $file = "/tmp/toaster-watcher-pop3-runfile";
            if ( $qmail->build_pop3_run($conf, $file ) )
            {
                    $qmail->install_qmail_service_run( {file=>$file, service=>"pop3"}, $conf);
            };

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

## test_smtpd_config_values

Runs the following tests:

      make sure qmail_dir exists
      make sure vpopmail home dir exists
      make sure qmail_supervise is not a directory

## set_service_dir

This is necessary because things such as service directories are now in /var by default but older versions of my toaster installed them in /. This will detect and adjust for that.

      $qmail->set_service_dir($conf, $prot);

$prot is the protocol (smtp, pop3, submit, send).

returned is the directory

## build_smtp_run

            if ( $qmail->build_smtp_run($conf, $file, $debug) ) { 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, $file ) )
            {
                    $qmail->install_qmail_service_run( {file=>$file, service=>"smtp"}, $conf);
            };

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

## build_submit_run

            if ( $qmail->build_submit_run($conf, $file, $debug) ) { 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, $file ) )
            {
                    $qmail->install_qmail_service_run( {file=>$file, service=>"submit"}, $conf);
            };

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

## install_qmail_service_run

Installs a new supervise/run file for a supervised service.

            my $file = "/tmp/toaster-watcher-smtpd-runfile";

            if ( $qmail->build_smtp_run($conf, $file, $debug ) )
            {
                    $qmail->install_qmail_service_run( {file=>$file, service=>"smtp"}, $debug);
            };

Input is a hashref with these values:

      file    - new file that was created (typically /tmp/something)
      service - one of (smtp, send, pop3, submit)

returns 1 on success, 0 on error

## smtpd_restart

            $qmail->smtpd_restart($conf, "smtp", $debug)

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.

## restart

            $qmail->restart()

Use to restart the qmail-send process. It will send qmail-send the TERM signal and then return.

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

## send_start

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

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

## queue_process

    queue_process - Tell qmail to process the queue immediately

## check_rcpthosts

            $qmail->check_rcpthosts($qmaildir);

Checks the rcpthosts file and compare it 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'll be expected to add them to morercpthosts.

## config

            $qmail->config($conf);

Qmail is fantastic because it's so easy to configure. Just edit files and put the right values in them. However, many find that a problem because it's not so easy to always know the sytax 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/tarpitcount
       /var/qmail/control/tarpitdelay
       /var/qmail/control/sql
       /var/qmail/alias/.qmail-postmaster
       /var/qmail/alias/.qmail-root
       /var/qmail/alias/.qmail-mailer-daemon

If you don't have toaster-watcher installed, it prompts you for each value.

## configure_qmail_control

            $qmail->configure_qmail_control($conf);

Installs the qmail control script as well as the startup (services.sh) script.

## install_supervise_run

            $qmail->install_supervise_run($conf);

$conf is a hashref of values pulled from toaster-watcher.conf.

Generates the qmail/supervise/*/run files based on your settings.

## install_supervise_log_run

            $qmail->install_supervise_log_run($conf);

$conf is a hash of values. See $utility->parse_config or toaster-watcher.conf for config values.

Installs the files the control your supervised processes logging. Typically this consists of qmail-smtpd, qmail-send, and qmail-pop3d. The generated files are:

     qmail_supervise/pop3/log/run
     qmail_supervise/smtp/log/run
     qmail_supervise/send/log/run
     qmail_supervise/submit/log/run

## get_domains_from_assign

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

            $qmail->get_domains_from_assign($assign, $debug, $match, $value);

     $assign is the path to the assign file.
     $debug is optional
     $match is an optional field to match (dom, uid, dir)
     $value is the pattern to  match

returns an array

# AUTHOR

Matt Simerson <matt@tnpi.biz>

# BUGS

None known. Report any to author.

# TODO

# SEE ALSO

     http://www.tnpi.biz/computing/
     http://www.tnpi.biz/internet/mail/toaster/

Mail::Toaster::CGI, Mail::Toaster::DNS, Mail::Toaster::Logs, Mail::Toaster::Qmail, Mail::Toaster::Setup

# COPYRIGHT

Copyright (c) 2004, The Network People, Inc. 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.