Mail::Toaster::Setup - methods to configure and build all the components of a modern email server.
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.
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.
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.
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
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
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
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
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.
$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
$setup->courier_startup( );
Does the post-install configuration of Courier IMAP.
$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
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
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
$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.
Fetches djbdns, compiles and installs it.
$setup->djbdns( ); required arguments: conf optional arguments: debug fatal result: 1 - success 0 - failure
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.
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
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();
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.
Installs isoqlog.
$setup->isoqlog();
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( );
Creates and installs the maildrop mailfilter file.
$setup->maildrop_filter();
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();
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.
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( );
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);
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();
Install qmailadmin based on your settings in toaster-watcher.conf.
$setup->qmailadmin();
Install Vipul's Razor2
$setup->razor( );
Installs ripmime
$setup->ripmime();
Install simscan from Inter7.
$setup->simscan();
See toaster-watcher.conf to see how these settings affect the build and operations of simscan.
Build the simcontrol and ssattach config files based on toaster-watcher.conf settings.
Send some test messages to the mail admin using simscan as a message scanner.
$setup->simscan_test();
$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($service, $ip, $user, $supervisedir);
Builds a service/log/run file for use with socklog.
$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.
$setup->sqwebmail();
install sqwebmail based on your settings in toaster-watcher.conf.
$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);
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
Run a variety of tests to verify that your Mail::Toaster installation is working correctly.
Installs ucspi-tcp with my (Matt Simerson) MySQL patch.
$setup->ucspi_tcp( );
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.
Builds the ~vpopmail/etc/tcp.smtp file with a mess of sample entries and user specified settings.
$setup->vpopmail_etc( );
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);
$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.
IO::Socket::SSL
Matt Simerson - matt@tnpi.net
None known. Report to author. Patches welcome (diff -u preferred)
Better documentation. It is almost reasonable now.
The following are all man/perldoc pages:
Mail::Toaster Mail::Toaster::Conf toaster.conf toaster-watcher.conf http://mail-toaster.org/
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.
To install Mail::Toaster, copy and paste the appropriate command in to your terminal.
cpanm
cpanm Mail::Toaster
CPAN shell
perl -MCPAN -e shell install Mail::Toaster
For more information on module installation, please visit the detailed CPAN module installation guide.