Mail::Toaster::Setup

- NAME
- DESCRIPTION
- METHODS
- DEPENDENCIES
- AUTHOR
- BUGS
- TODO
- SEE ALSO
- COPYRIGHT AND LICENSE

# NAME

Mail::Toaster::Setup - methods to configure and build all the components of a modern email server.

# DESCRIPTION

The meat and potatoes of toaster_setup.pl. This is where the majority of the work gets done. Big chunks of the code and logic for getting all the various applications and scripts installed and configured resides in here.

# METHODS

All documented methods in this package (shown below) accept two optional arguments, debug and fatal. Setting debug to zero will supress nearly all informational and debugging output. If you want more output, simply pass along debug=>1 and status messages will print out. Fatal allows you to override the default behaviour of these methods, which is to die upon error. Each sub returns 0 if the action failed and 1 for success.

     arguments required:
       varies (most require conf)

     arguments optional:
       debug - print status messages
       fatal - die on errors (default)

     result:
       0 - failure
       1 - success

     Examples:

       1. $setup->apache( debug=>0, fatal=>0 );
       Try to build apache, do not print status messages and do not die on error(s).

       2. $setup->apache( debug=>1 );
       Try to build apache, print status messages, die on error(s).

       3. if ( $setup->apache( ) { print "yay!\n" };
       Test to see if apache installed correctly.

new

  To use any methods in Mail::Toaster::Setup, you must create a setup object:

        use Mail::Toaster::Setup;
        my $setup = Mail::Toaster::Setup->new;

  From there you can run any of the following methods via $setup->method as documented below.

  Many of the methods require $conf, which is a hashref containing the contents of toaster-watcher.conf.

apache

  Calls $apache->install[1|2] which then builds and installs Apache for you based on how it was called. See Mail::Toaster::Apache for more details.

        $setup->apache( ver=>22 );

  There are many popular Apache compile time options supported. To see what options are available, see toaster-watcher.conf.

       required arguments:
         conf

       optional arguments:
         ver - the version number of Apache to install
         debug
         fatal

autorespond

  Install autorespond. Fetches sources from Inter7 web site and installs. Automatically patches the sources to compile correctly on Darwin.

        $setup->autorespond( );

       required arguments:
         conf

       optional arguments:
         debug
         fatal

clamav

  Install ClamAV, configure the startup and config files, download the latest virus definitions, and start up the daemons.

        $setup->clamav( );

       required arguments:
         conf

       optional arguments:
         debug
         fatal

config - personalize your toaster-watcher.conf settings

  There are a subset of the settings in toaster-watcher.conf which must be personalized for your server. Things like the hostname, where you store your configuration files, html documents, passwords, etc. This function checks to make sure these settings have been changed and prompts for any necessary changes.

       required arguments:
         conf

       optional arguments:
         debug
         fatal

config_tweaks

  Makes changes to the config file, dynamically based on detected circumstances such as a jailed hostname, or OS platform. Platforms like FreeBSD, Darwin, and Debian have package management capabilities. Rather than installing software via sources, we prefer to try using the package manager first. The toaster-watcher.conf file typically includes the latest stable version of each application to install. This subroutine will replace those version numbers with with 'port', 'package', or other platform specific tweaks.

courier

        $setup->courier( );

  Installs courier imap based on your settings in toaster-watcher.conf.

       required arguments:
         conf

       optional arguments:
         debug
         fatal

       result:
         1 - success
         0 - failure

courier_startup

        $setup->courier_startup( );

  Does the post-install configuration of Courier IMAP.

cpan

        $setup->cpan( );

  Installs only the perl modules that are required for 'make test' to succeed. Useful for CPAN testers.

       Date::Parse
       HTML::Template
       Compress::Zlib
       Crypt::PasswdMD5
       Net::DNS
       Quota
       TimeDate

cronolog

  Installs cronolog. If running on FreeBSD or Darwin, it will install from ports. If the port install fails for any reason, or you are on another platform, it will install from sources.

  required arguments: conf

  optional arguments: debug fatal

  result: 1 - success 0 - failure

daemontools

  Fetches sources from DJB's web site and installs daemontools, per his instructions.

       Usage:
        $setup->daemontools( conf->$conf );

       required arguments:
         conf

       optional arguments:
         debug
         fatal

       result:
         1 - success
         0 - failure

dependencies

        $setup->dependencies( );

  Installs a bunch of dependency programs that are needed by other programs we will install later during the build of a Mail::Toaster. You can install these yourself if you would like, this does not do anything special beyond installing them:

  ispell, gdbm, setquota, expect, maildrop, autorespond, qmail, qmailanalog, daemontools, openldap-client, Crypt::OpenSSL-RSA, DBI, DBD::mysql.

  required arguments: conf

  optional arguments: debug fatal

  result: 1 - success 0 - failure

djbdns

  Fetches djbdns, compiles and installs it.

        $setup->djbdns( );

       required arguments:
         conf

       optional arguments:
         debug
         fatal

       result:
         1 - success
         0 - failure

expect

  Expect is a component used by courier-imap and sqwebmail to enable password changing via those tools. Since those do not really work with a Mail::Toaster, we could live just fine without it, but since a number of FreeBSD ports want it installed, we install it without all the extra X11 dependencies.

ezmlm

  Installs Ezmlm-idx. This also tweaks the port Makefile so that it will build against MySQL 4.0 libraries if you don't have MySQL 3 installed. It also copies the sample config files into place so that you have some default settings.

        $setup->ezmlm( );

       required arguments:
         conf

       optional arguments:
         debug
         fatal

       result:
         1 - success
         0 - failure

filtering

  Installs SpamAssassin, ClamAV, simscan, QmailScanner, maildrop, procmail, and programs that support the aforementioned ones. See toaster-watcher.conf for options that allow you to customize which programs are installed and any options available.

        $setup->filtering();

is_newer

  Checks a three place version string like 5.3.24 to see if the current version is newer than some value. Useful when you have various version of a program like vpopmail or mysql and the syntax you need to use for building it is different for differing version of the software.

isoqlog

  Installs isoqlog.

        $setup->isoqlog();

maildrop

  Installs a maildrop filter in $prefix/etc/mail/mailfilter, a script for use with Courier-IMAP in $prefix/sbin/subscribeIMAP.sh, and sets up a filter debugging file in /var/log/mail/maildrop.log.

        $setup->maildrop( );

maildrop_filter

  Creates and installs the maildrop mailfilter file.

        $setup->maildrop_filter();

maillogs

  Installs the maillogs script, creates the logging directories (toaster_log_dir/), creates the qmail supervise dirs, installs maillogs as a log post-processor and then builds the corresponding service/log/run file to use with each post-processor.

        $setup->maillogs();

mattbundle

  Downloads and installs the latest version of MATT::Bundle.

        $setup->mattbundle(debug=>1);

  Don't do it. Matt::Bundle has been deprecated for years now.

mysql

  Installs mysql server for you, based on your settings in toaster-watcher.conf. The actual code that does the work is in Mail::Toaster::Mysql so read the man page for Mail::Toaster::Mysql for more info.

        $setup->mysql( );

phpmyadmin

  Installs PhpMyAdmin for you, based on your settings in toaster-watcher.conf. The actual code that does the work is in Mail::Toaster::Mysql (part of Mail::Toaster::Bundle) so read the man page for Mail::Toaster::Mysql for more info.

        $setup->phpmyadmin($conf);

ports

  Install the ports tree on FreeBSD or Darwin and update it with cvsup.

  On FreeBSD, it optionally uses cvsup_fastest to choose the fastest cvsup server to mirror from. Configure toaster-watch.conf to adjust it's behaviour. It can also install the portupgrade port to use for updating your legacy installed ports. Portupgrade is very useful, but be very careful about using portupgrade -a. I always use portupgrade -ai and skip the toaster related ports such as qmail since we have customized version(s) of them installed.

        $setup->ports();

qmailadmin

  Install qmailadmin based on your settings in toaster-watcher.conf.

        $setup->qmailadmin();

razor

  Install Vipul's Razor2

        $setup->razor( );

ripmime

  Installs ripmime

        $setup->ripmime();

simscan

  Install simscan from Inter7.

        $setup->simscan();

  See toaster-watcher.conf to see how these settings affect the build and operations of simscan.

simscan_conf

  Build the simcontrol and ssattach config files based on toaster-watcher.conf settings.

simscan_test

  Send some test messages to the mail admin using simscan as a message scanner.

          $setup->simscan_test();

socklog

              $setup->socklog( ip=>$ip );

  If you need to use socklog, then you'll appreciate how nicely this configures it. :) $ip is the IP address of the socklog master server.

socklog_qmail_control

              socklog_qmail_control($service, $ip, $user, $supervisedir);

  Builds a service/log/run file for use with socklog.

squirrelmail

              $setup->squirrelmail

  Installs Squirrelmail using FreeBSD ports. Adjusts the FreeBSD port by passing along WITH_APACHE2 if you have Apache2 selected in your toaster-watcher.conf.

sqwebmail

              $setup->sqwebmail();

  install sqwebmail based on your settings in toaster-watcher.conf.

supervise

              $setup->supervise();

  One stop shopping: calls the following subs:

        $qmail->control_create        ();
        $setup->service_dir_create    ();
        $toaster->supervise_dirs_create ();
        $qmail->install_qmail_control_files ();
        $qmail->install_qmail_control_log_files();
        $toaster->service_symlinks    (debug=>$debug);

startup_script

  Sets up the supervised mail services for Mail::Toaster

              $setup->startup_script( );

  If they don't already exist, this sub will create:

              daemontools service directory (default /var/service)
              symlink to the services script

  The services script allows you to run "services stop" or "services start" on your system to control the supervised daemons (qmail-smtpd, qmail-pop3, qmail-send, qmail-submit). It affects the following files:

        $prefix/etc/rc.d/[svscan|services].sh
        $prefix/sbin/services

test

  Run a variety of tests to verify that your Mail::Toaster installation is working correctly.

ucspi_tcp

  Installs ucspi-tcp with my (Matt Simerson) MySQL patch.

              $setup->ucspi_tcp( );

vpopmail

  Vpopmail is great, but it has lots of options and remembering which option you used months or years ago to build a mail server is not always easy. So, store all the settings in toaster-watcher.conf and this sub will install vpopmail for you, honoring all your settings and passing the appropriate configure flags to vpopmail's configure.

              $setup->vpopmail( );

  If you do not have toaster-watcher.conf installed, it will ask you a series of questions and then install based on your answers.

vpopmail_etc

  Builds the ~vpopmail/etc/tcp.smtp file with a mess of sample entries and user specified settings.

              $setup->vpopmail_etc( );

vpopmail_mysql_privs

  Connects to MySQL server, creates the vpopmail table if it doesn't exist, and sets up a vpopmail user and password as set in $conf.

          $setup->vpopmail_mysql_privs($conf);

vqadmin

              $setup->vqadmin($conf, $debug);

  Installs vqadmin from ports on FreeBSD and from sources on other platforms. It honors your cgi-bin and your htdocs directory as configured in toaster-watcher.conf.

# DEPENDENCIES

        IO::Socket::SSL

# AUTHOR

Matt Simerson - matt@tnpi.net

# BUGS

None known. Report to author. Patches welcome (diff -u preferred)

# TODO

Better documentation. It is almost reasonable now.

# SEE ALSO

The following are all man/perldoc pages:

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

     http://mail-toaster.org/

# COPYRIGHT AND LICENSE

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