/ 
Mail-Toaster-5.38
River stage zero No dependents
/ Mail::Toaster::Setup

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.