Mail::Toaster::Qmail

- NAME
- SYNOPSIS
- DESCRIPTION
- SUBROUTINES/METHODS
- EXAMPLES
- DIAGNOSTICS
- CONFIGURATION AND ENVIRONMENT
- DEPENDENCIES
- BUGS AND LIMITATIONS
- TODO
- SEE ALSO
- AUTHOR
- ACKNOWLEDGEMENTS
- LICENCE AND COPYRIGHT

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