toaster.conf documentation

[davidcl]

n.b. THESE DOCS ARE NOT UP-TO-DATE.  The information posted here describes toaster-watcher.conf as of Mail::Toaster 3.34.  Since then, some options have been added, some have been removed, and some of the explanations have been clarified.

For the most recent version of this document, see http://www.tnpi.biz/internet/mail/toaster/docs/tconf.shtml" target="_blank">http://www.tnpi.biz/internet/mail/toaster/docs/tconf.shtml

This document is also included with the toaster download, in pod, html, and text format.

The toaster has two main configuration files, toaster.conf and toaster-watcher.conf.  On FreeBSD, both of these files live in /usr/local/etc.

toaster.conf controls options relating to:
- where files are kept on your particular server
- which options should be displayed on the web, and how they should appear
- how the toaster's logs should be processed.

[matt]

The reason for having two config files is security. The toaster-watcher.conf file is used only by programs with root access (toaster-watcher.pl, toaster_setup.pl).  This is because passwords and other security sensitive information is stored in that file and as such, it's installed so that only root users can read it.

The toaster.conf file is for everything else (mailadmin, index.cgi, maillogs)

[davidcl]

#######################################            TOASTER######################################

toaster_http_base              = /usr/local/www

This sets your apache root.  Note that this isn't your document root-- the toaster expects to find directories called "data" and "cgi-bin" inside this directory.  "data" is your document root.  This is the default layout for Apache on FreeBSD; only change this if you use a different web server or a non-standard file layout.

system_config_dir              = /usr/local/etc

This is where the toaster will install its other config files, such as isoqlog.conf, rrdutil.conf, clamav.conf, etc.  The default is correct for FreeBSD systems.

[davidcl]

########################################         Mail::Toaster::CGI          ########################################

This section controls the layout and wording of the toaster's home page, index.cgi.  

web_logo_url                    = /images/logo.jpgweb_logo_alt_text               = example.com logoweb_heading_text                = Mail Centerweb_instructions                = To check your mail, fill in the account info and select a destination.

This first block of options lets you set a few elements that will be included on the toaster's home page.  The web_logo_url allows you to do some easy branding of your login page, although more extensive changes can be made by editing the index.tmpl file in your web document root.

The toaster's home page will display buttons for several programs-- most toasters will include, at minimum, a webmail program and qmailadmin.  You have the option to include two webmail programs and three statistics programs.  Each program has a block of options in the config file.  Since all the blocks are the same, I'll go through only one example in depth.

web_sqwebmail                   = 1

Do you want a button for sqwebmail to appear on your toaster's home page?  If not, set this to 0.  (I set this to 0 on my toaster because I prefer to only support one webmail interface).

web_sqwebmail_host              = 0       # 0 or a valid full qualified host name

Do you require a specific hostname for sqwebmail?  If your toaster answers to many hostnames, but only one of them has an SSL certificate, then you might want to set this option.  Otherwise, the sqwebmail button will just use the hostname through which the homepage is accessed.

web_sqwebmail_url               = /cgi-bin/sqwebmail

The location of sqwebmail within your toaster_http_base directory.

web_sqwebmail_require_ssl       = 1

The default is the best choice-- SSL security provides your users with security for their email, but more importantly for their username and password.

If you don't have an SSL certificate for your toaster, or you want to give your users the option to use SSL or not use it, then turn this off.

web_sqwebmail_name              = Sqwebmail:

What should the name of Sqwebmail be on the toaster's home page?  Perhaps you've decided to call your implementation of Sqwebmail "Funky Fresh Mail" on the theory that "Sqwebmail" is impossible to pronounce.

web_sqwebmail_description       = a fast and capable web mail client

This is the description that appears next to the program name on your toaster's home page.

That's the end of the Sqwebmail configuration.  It's followed by identical blocks for squirrelmail, qmailadmin, rrdutil, isoqlog, and qss.  As more web-based programs are added to the toaster, they'll be added here.

web_squirrelmail                = 1web_squirrelmail_host           = 0web_squirrelmail_url            = /squirrelmail/src/redirect.phpweb_squirrelmail_require_ssl    = 1web_squirrelmail_name           = Squirrelmail:web_squirrelmail_description    = attractive, many features, very customizableweb_qmailadmin                  = 1web_qmailadmin_host             = 0web_qmailadmin_url              = /cgi-bin/qmailadminweb_qmailadmin_require_ssl      = 1web_qmailadmin_name             = Qmailadmin:web_qmailadmin_description      = modify your mail settingsweb_rrdutil                     = 1web_rrdutil_host                = 0web_rrdutil_url                 = /cgi-bin/rrdutil.cgiweb_rrdutil_require_ssl         = 0web_rrdutil_name                = RRDutil:web_rrdutil_description         = mail server activityweb_isoqlog                     = 1web_isoqlog_host                = 0web_isoqlog_url                 = /isoqlog/web_isoqlog_require_ssl         = 0web_isoqlog_name                = Isoqlog:web_isoqlog_description         = detailed message statisticsweb_qs_stat                     = 1web_qs_stat_host                = 0web_qs_stat_url                 = /qss/index.phpweb_qs_stat_require_ssl         = 0web_qs_stat_name                = Qmail Scanner Stats:web_qs_stat_description         = Virus blocks

[davidcl]

########################################         Mail::Toaster::Logs         ########################################

This section lets you configure the logfiles for your toaster.  Note that there are also settings which affect logs in toaster-watcher.conf

logs_base         = /var/log/mail         # where qmail logs live (/var/log)

If you store your logs somewhere else, change this.  (I keep mine in /var/log/qmail for historical reasons).

logs_supervise    = /var/qmail/supervise

The location of your supervise directory.  The supervise directory contains control files for all supervised services available on your machine, even if they aren't running.

Although not directly relevant to this entry, Matt gave me a great explanation of the difference between the "supervise" and "service" directories, which I'll include here, at least until I find a better place for it:

Quote:

The supervise directory is where all the control files are created and where they'll live forever and ever, even if they aren't used. The supervise directory can be the same as the service directory, but it shouldn't be. Per Dan & LWQ docs, the service directory should exist elsewhere. On FreeBSD /var/service is the most appropriate location (man hier for details).  In the service directory you create symlinks to the supervised directories you want running. A good example of this is that many toaster run courier-imap's pop3 daemon instead of qmails. Yet, the qmail pop3 daemons supervise directory is still build in /var/qmail/supervise but not symlinked in /var/service and thus not running.  Switching from courier to qmail's is typically as easy as:    pop3 stop    rm /usr/local/etc/rc.d/pop3.sh    ln -s /var/qmail/supervise/pop3 /var/service

logs_user         = qmailllogs_group        = qnofiles

What user and group should own the toaster logfiles?

logs_pop3d        = qpop3d                # choices are courier or qpop3d

The toaster used to use the courier pop3 server; now it uses the qmail pop3 server.  If you have an older toaster that uses courier, make sure you change this.

logs_isoqlog      = 1                     # configure isoqlog first!

Will you process your logs with isoqlog?  Make sure you heed the warning in the comment-- if you don't configure the isoqlog.conf file, but you leave this set to 1, bad things happen.  If you haven't gotten around to configuring isoqlog, change this to 0 until you do.

logs_taifiles     = 1                     # output to multilogs @NNNNNNN files

Today's logfiles will be in filenames timestamped in the tai64n format.  For example, a file called @400000004030ff6b05921044.s was created at 2004-02-16 12:35:29.093458500.  To view these filenames in a human readable format, go to your log directory and enter ls | tai64nlocal.

logs_archive      = 1                     # output to YYYY/MM/DD/xxxxlog files

For example, the SMTP log file for February 14, 2004, is called 2004/02/14/smtplog or 2004/02/14/smtplog.gz, depending on how big it is.  This directory tree lives inside your logs_base directory. If you set this option to 0, old logs are not archived-- they are deleted.  

logs_counters     = counters              # dir for storing counters

A directory inside your logs_base directory, which stores the counter files used by isoqlog and rrdutil.

logs_rbl_count    = smtp_rbl.txtlogs_smtp_count   = smtp_auth.txtlogs_send_count   = send.txtlogs_pop3_count   = pop3.txtlogs_imap_count   = imap.txtlogs_spam_count   = spam.txtlogs_virus_count  = virus.txtlogs_web_count    = webmail.txt

The names of the counter files in the logs_counters directory.

[davidcl]

########################################       Mail::Toaster::Admin          ########################################

Many of the options in this section relate to to the mailadmin script, which the toaster installs in /usr/local/sbin.  This script used to be called maildomain.  

admin_update           = /usr/local/sbin/update   # custom Matt script updates clients

This script is used by the update function of the mailadmin script, which is not yet implemented in the toaster.

admin_home             = /usr/home                # where you store home directoriesadmin_quotafs          = /home                    # mount point for quota enabled file system

Where home directories live on your system.  If you don't have a quota-enabled file system, there's no harm in leaving admin_qutoafs at the default setting.

admin_qmailpath        = /var/qmail               # where qmail is installed

The location of qmail.  Think twice about changing this, as you'll be creating a very non-standard qmail installation.  

admin_qmailadminlimits = /var/qmail/control/.qmailadmin-limits

The location of your qmailadminlimits file.  

admin_adminhost        = matt.cadillac.net        # the "master" server in a clusteradmin_fileservers      = matt                     # all file servers in this arrayadmin_mailservers      = mail1 mail2 mail3 mail4 mail5

On a typical toaster, all three of these will contain the same hostname, the name of the toaster.  As you scale your toaster up, you can create a cluster of multiple servers.  

In a cluster, you will have one "admin" server (ie, the place you go to make changes), as many file servers as are necessary to handle the expected disk i/o, and enough front end mail servers to hand the CPU load required to service web/pop3/imap/smtp sessions.

admin_vpopbin          = /usr/local/vpopmail/bin

This is the directory where your vpopmail code is installed.

singleuid           =       #  If all your mail domains will be owned by a single user                            #  (vpopmail) then set to the username of your vpopmail user

In the default configuration of the toaster, this option should be set to "vpopmail", the user that will own the mail domains.  Other configurations are possible; you can have domains be owned by specific system users.

create_sys_user     = 1     #  by default, when in single uid mode this script won't                            #  create a new system user. This flag overrides that. (y/n)

Set this to 1 if you want toaster -s vpopmail to create the user specified in the singleuid parameter.  Set it to 0 if this user has already been created.

homedirtree         = 1     #  Using a homedir tree? (/usr/home/a/ab/abcuser instead of                            #  /usr/home/abcuser)homedir_base        = u     # If using a system user account, where do we put their                            # home dir? IE, is it based on user or domain name (u/d)

On an unmodified FreeBSD system, all home directories are stored in a "flat" structure-- they all live in /usr/home.  If this is the case on your server, homedirtree should be set to 0 and homedir_base should be set to u.  If you've chosen another system for organizing your home directories, set the appropriate options here.

use_passwords       = 0     # Do we want the users to be able to log in via (telnet/ssh)?                            # Put the postmaster password into the system passwd files

If this option is set, the postmaster password for new domains will be placed in the system password file, so the postmaster will have shell access to the mail server.  

show_function       = 1     # A handy utility that lets support staff view the current                            # settings of a mail account.

This enables the "show" function in the mailadmin script.

vauth               = mysql # where vpopmail stores it's auth info (cdb, mysql, ldap)

On most toasters, this should be set to mysql.  If you store user information in cdb files or on an LDAP server, change this setting.

delete_old_archives = 0     # Delete archive files after restoring?

If the mailadmin script is used to archive deleted domains, this setting determines whether the archives should be deleted when the domain is restored to service.

secure_levels       = 1     # Adds multiple levels of security while running this script.

This enables a function in the mailadmin script whereby different users have different levels of access to the script.  Currently the access levels are hard-coded in the script itself, by username.