NAME

toaster-watcher.conf - Configuration file for toaster_setup.pl and toaster-watcher.pl.

SYNOPSIS

Most settings in this file pertain to toaster_setup.pl and toaster-watcher.pl scripts, both of which are run as root. Other settings needed by scripts that do not run with root privileges are in toaster.conf.

A current copy of toaster-watcher.conf is posted on the Mail::Toaster web site at http://mail-toaster.org/etc/toaster-watcher.conf

DESCRIPTION

toaster-watcher.conf The contents of that file control options relating to:

• where files are kept on your particular server

• settings related to how the toaster is built

• what programs and options are installed

• where programs and run files are installed

• run time parameters used to configure daemons

• how the toaster's logs should be processed.

This document provides details on what all them nifty settings do.

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

cvsup_server_preferred         = fastest     # fastest | hostname
cvsup_server_country           = US

If you select fastest and set your country, toaster_setup will find the fastest FreeBSD cvs server in your country and sync up to it.

cvsup_supfile_ports            = /etc/cvsup-ports
cvsup_supfile_sources          = /etc/cvsup-stable

toaster_setup.pl has two very useful targets: ports, sources. If you have a pre-configured supfile you wisth to use for syncing up your sources with, set it here. Otherwise, a default file will be installed for you.

toaster_pkg_site               = ftp://ftp.freebsd.org
toaster_sf_mirror              = downloads.sourceforge.net/projects
toaster_dl_site                = http://www.tnpi.net   # or a mirror

You can alternately use a mirror to fetch the Mail::Toaster files from. The atl and sea mirrors are updated nightly. All other mirrors are updated only after major releases. If you want the last major update you can refer to a mirror.

toaster_dl_url                 = /internet/mail/toaster

This section contains settings about where the various componenents in the toaster should be downloaded from. In most cases, the only things you're likely to change are your country, and the version of FreeBSD you are using.

The version of FreeBSD should be expressed in the form of a tag name. Possible options are:

4-stable
5-stable
5-current


toaster_http_base              = /usr/local/www

This should be the same value specified in toaster.conf

toaster_http_docs              = /usr/local/www/data

This is your document root, normally the "data" directory inside your web root.

toaster_cgi_bin                = /usr/local/www/cgi-bin

The path to your cgi-bin dir where sqwebmail, qmailadmin, and other cgi apps should be installed.

toaster_tmp_dir                = /tmp
toaster_src_dir                = /usr/local/src

Where will the toaster place temporary files and source files? The default is usually fine.

toaster_debug                  = 0

Many of the perl subroutines used by toaster_setup.pl and toaster_watcher.pl have extensive debugging available, but disabled. This enables all that debugging. If you are having a problem with something, such as toaster-watcher.pl not generating your /service/smtp/run file, then you could enable debugging and run it again. The debugging messages might show you that it timed out when doing DNS queries-- maybe your DNS server could use a little attention.

toaster_hostname               = mail.example.com
system_config_dir              = /usr/local/etc
toaster_admin_email            = postmaster@example.com

A few basic settings-- the hostname of your machine, the location of your config files, and the email address where system-wide admin mail should be sent.

mail_syslog                    = /var/log/maillog

The file that should be used by syslog/splogger for mail logging. Note that settings elsewhere in this file may send portions of your mail logging to other locations. The default is for FreeBSD. Other platforms store messages sent to syslog's MAIL facility elsewhere. Adjust this to suit.

package_install_method         = packages  # packages | ports

This affects toaster_setup.pl. If a program can be installed from either packages or ports, which method is preferred?

preserve_cgifiles             = 0

When you upgrade Mail::Toaster, your CGI files will be overwritten to provide any new web features that have been added to the toaster. If you've customized your CGI scripts, set this to 1 to avoid the automatic overwrite.

######################################
#           Programs
######################################

This section is fairly self-explanatory. Which programs should toaster_setup.pl install, and what versions of those programs should it install?

# You can pass the major number of some programs
# if you with to install a particular version
# 0 = do not install
# 1 = install
# other = install particular version
# port  = install from FreeBSD ports
# Extra options are noted after the # where available

install_squirrelmail           = 1

install_mysql                  = 4   # 0, 1, 2, 3, 40, 41, 5

You can choose from a variety of MySQL version to install. The code meanings are as follows:

0       - none
1       - install latest package
2       - install latest stable release from ports
3, 323  - 3.23   from ports
4, 40   - 4.0.x  from ports
41, 4.1 - 4.1.x  from ports
5, 50   - 5.0.x  from ports

There is more information about using MySQL with the mail toaster here:

http://mail-toaster.org/faq/programs/mysql.shtml

install_mysql_ssl              = 1
install_mysql_linuxthreads     = 0
install_mysql_optimized        = 1
install_mysql_dir              = /var/db/mysql

If you are using MySQL replicaton over a WAN, then ssl is a good option to use.

/var/db/mysql is the default location of MySQL on FreeBSD. If you're expecting to have anything other than the toaster use this MySQL database server, there might be arguments for putting MySQL somewhere other than /var, especially if you haven't sized /var appropriately to begin with.

install_courier_imap           = 1.7.0  # 0, ver, port
install_sqwebmail              = 3.5.0  # 0, ver, port
install_qmail                  = 1.03   # ver
install_netqmail               = 1.05   # ver
install_qmailadmin             = 1.2.0  # 0, ver, port
install_vpopmail               = 5.4.0  # ver, port

Feel free to switch any of these to zero to disable installing that component. However, it is strongly recommended that you leave all of these version numbers unchanged from the toaster-watcher.conf distributed with the toaster-- the versions indicated have been tested together and with the toaster, are considered stable, and generally can be installed cleanly on FreeBSD.

In the case of qmail, if netqmail is set (the default), then it's installed. Otherwise, qmail is installed.

install_vqadmin                = 0

vqadmin is a handy web-based tool that administers vpopmail domains. It is not a "recommended" part of the toaster install, because it has significant security implications and requires setup. However, many administrators use it.

install_isoqlog                = 1
install_portupgrade            = 1
install_openldap_client        = 1
install_net_snmpd              = 4

######################################
#           Mail Filtering
######################################

install_mail_filtering         = 1
install_procmail               = 0
install_maildrop               = 1
install_spamassassin           = 1
install_spamassassin_flags     = -a -d -v -x -r /var/run/spamd.pid

There are MANY things you can change about SpamAssassin's behavior by modifying these flags, but they are beyond the scope of this document. See http://www.spamassassin.org/ for details

install_qmailscanner           = 1.21  # 0 | ver
install_qmailscanner_stats     = 2.02  # 0 | ver
install_clamav                 = 1
install_pyzor                  = 0
install_razor                  = 1

Razor needs to be configured before use! Please see the Razor docs: http://razor.sourceforge.net/docs/

From the Razor FAQ:

Q: I have a firewall. What ports do I need to open in order for Razor2 to work?

A: Outgoing TCP port 2703 (Razor2) and TCP port 7 (Echo). Razor2 uses TCP pings to discover what servers are closest to it.

If you allow outgoing tcp connections as I do, then you don't need any additional rules for Razor.

install_bogofilter             = 0
install_dcc                    = 0

These settings relate to mail filtering using ClamAV, SpamAssassin, and Maildrop. There's little reason to change the defaults here on anything other than the SpamAssassin flags. At various points in time, something like dcc might be broken in the ports tree. Setting install_dcc = 0 will get you past that, at the expense of not having that filter installed.

If you install DCC, make sure you configure it. If you use a firewall, DCC requires the following firewall rules to be implemented:

allow udp local gt 1023 to remote 6277
allow udp remote 6277 to local gt 1023

If you use IPFW in FreeBSD (as I do) then this will do the trick for you:

# Allow DCC & Pyzor
${fwcmd} add allow udp from ${oip} to any 6277,24441
${fwcmd} add allow udp from any 6277,24441 to ${oip} 1024-65535

Note that ruleset enables the port for Pyzor (24441) as well.

######################################
#           Qmail Settings
######################################

qmail_dir                      = /var/qmail

The location of qmail. Think twice about changing this, as you'll be creating a very non-standard qmail installation. (This should match admin_qmaildir in toaster.conf).

qmail_supervise                = /var/qmail/supervise
qmail_supervise_smtp           = /var/qmail/supervise/smtp
qmail_supervise_send           = /var/qmail/supervise/send
qmail_supervise_pop3           = /var/qmail/supervise/pop3
qmail_supervise_submit         = /var/qmail/supervise/submit
qmail_service                  = /var/service

These are your supervise and service directories. Only change if you have already created these directories elsewhere. For example Dan Bernstein has convinced some people to create /service instead of /var/service. Life-with-Qmail based servers will have /var/service/qmail-smtpd and /var/service/qmail-send. (qmail_supervise should match the logs_supervise in toaster.conf).

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 this:

pop3 stop
rm /usr/local/etc/rc.d/pop3.sh
ln -s /var/qmail/supervise/pop3 /var/service

After this change, you must manage pop3 with daemontools (svc).

qmail_mfcheck_enable = 1

The qmail toaster patches support checking for a valid hostname in the envelope sender of emails being delivered to your server. This enables that option. To disable this option after building qmail, remove the file /var/qmail/control/mfcheck

 qmail_concurrencyremote = 255

This is the total number of outgoing connections your server will make at a time. To change this after building qmail, edit /var/qmail/control/concurrencyremote

qmail_smtpd_auth_0.31 = 0

qmail_queue_extra = 0

Queue extra is a qmail feature for keeping a duplicate copy of messages coming into and out of the server. You can find more info about it on Dan's site: http://cr.yp.to/qmail/faq/admin.html

Leave this zero unless you know better!

qmail_log_base      = /var/log/mail
qmail_log_user      = qmaill
qmail_log_group     = qnofiles
qmail_mysql_include = /usr/local/lib/mysql/libmysqlclient.a
qmail_group         = qmail
qmail_user_alias    = alias
qmail_user_daemon   = qmaild
qmail_user_passwd   = qmailp
qmail_user_queue    = qmailq
qmail_user_remote   = qmailr
qmail_user_send     = qmails


######################################
#           Vpopmail
######################################

If you change any of the vpopmail settings after installing vpopmail, you will need to rebuild vpopmail from source to make them take effect. Fortunately, it's as easy as toaster_setup.pl -s vpopmail. Don't forget to also rebuild the programs which depend on the vpopmail libraries (sqwebmail, courier, qmailadmin).

vpopmail_user                  = vpopmail
vpopmail_group                 = vchkpw
vpopmail_home_dir              = /usr/local/vpopmail
vpopmail_learn_passwords       = 1

The learn password feature allows you to set a user's password to be blank. The password will be set to whatever is used the first time the user logs in. Very helpful for migrating domains from other servers, but please consider the security implications.

vpopmail_default_domain        = 0

If you have just one domain you can set it with this option. The default domain users can authenticate with just their user name, and don't need to use <user>@<virtualdomain>. It is advised to not set this. Should you need to migrate your users to a new mail system in the future, you can bet the new system will support full email address authentications. If not, you'll be going through the pain of getting all your users to adjust their mail settings.

vpopmail_roaming_users         = 1
vpopmail_relay_clear_minutes   = 180

The "roaming users" setting enables POP-before-SMTP and IMAP-before-SMTP authentication. If this is enabled, then relay clear minutes determines how long users can send mail after they've checked mail.

vpopmail_mysql                 = 1

Should Vpopmail use MySQL for authentication? This is highly recommended. Should you ever need to scale your system to more than one CPU, MySQL lets you use replication to split the load among a cluster of servers.

vpopmail_mysql_limits          = 0

Should Vpopmail use MySQL for limits? This is handy, but it is a relatively new feature of vpopmail. If you are upgrading an existing toaster, you'll need to copy all of your existing domains into the MySQL limits table before enabling this feature. As of 5.4.0, you can enable default limits for all domains via ~vpopmail/etc/vlimits.default.

vpopmail_mysql_replication     = 0
vpopmail_mysql_logging         = 0
vpopmail_mysql_repl_master     = db.example.com
vpopmail_mysql_repl_slave      = localhost

Important: If you are not using replication, put in the name of your master database server as BOTH the master and the slave.

vpopmail_mysql_database        = vpopmail
vpopmail_mysql_user            = vpopmail
vpopmail_mysql_pass            = supersecretword

Important: Replace "supersecretword" with the correct password for your database server.

vpopmail_auth_logging          = 1
vpopmail_logging               = 1
vpopmail_logging_verbose       = 1
vpopmail_valias                = 1
vpopmail_qmail_ext             = 1
vpopmail_rebuild_tcpserver_file = 0

By default, vpopmail updates ~vpopmail/etc/tcp.smtp every time a new user is added to the relay table, which is every time a user successfully authenticates. This generates a lot of disk i/o on a busy mail seerver but is necessary for tcpserver to "see" the update. This is not necessary with the Mail::Toaster because we use the MySQL patch to tcpserver to check the SQL table directly.

vpopmail_ip_alias_domains      = 0

If IP alias domains is turned on, and the user does not supply a domain as part of their login, then a reverse IP lookup is done on the server IP address that the client connected to. If the servers IP address resolves to a domain name, then vpopmail uses that name as the domain.

IP w.x.y.z resolves to test.com. User sets their pop server ip to w.x.y.z and connects. Vpopmail gets the connection, checks the IP of the SERVER side of the connection. Does a reverse IP lookup and obtains test.com. User sends joe as their pop user name. Vpopmail uses test.com as the domain.

You can mix and match name and ip based virtual domains. You can also use the vipmap utility to skip the reverse DNS lookup (or if reverse DNS is not set up for the IP address).

vpopmail_etc_passwd            = 0

This enables local logins-- accounts which are listed in /etc/passwd-- to receive and check mail.

If you enable this feature, you'll need to add a few lines to /etc/pam.conf to allow courier-imap to work with /etc/passwd accounts. See http://www.inter7.com/courierimap/INSTALL.html for details.

vpopmail_domain_quotas         = 0
vpopmail_default_quota         = 100000000S,10000C

The domain quota feature has been broken on vpopmail almost forever. Even when it worked, it introduced extremely high CPU loads on busy mail systems. It is to be avoided.

The default quota option is deprecated in vpopmail 5.4.0 and higher. See ~vpopmail/etc/vlimits.default to control default limits.

vpopmail_disable_many_domains  = 0

filtering_spamassassin_method  = site   # site | user | domain

Please see the Toaster FAQ for instructions on enabling per-user and per-domain SpamAssassin preferences.

filtering_method  = smtp   # smtp | tcpserver

Mail scanners such as qmail-scanner, qscanc, and simscan are run by setting the QMAILQUEUE environment variable. This can be done either in the SMTP service run file (see the qmail_queue setting), or in the tcp.smtp file. "smtp" chooses the run file and affects ALL connections to the server; "tcpserver" chooses the tcp.smtp file and lets you choose which IP addresses (or blocks) use your scanner.

When set to tcpserver, toaster_watcher.pl ignores: smtpd_qmail_queue, submit_qmail_queue

filtering_maildrop_filter_file     = /usr/local/etc/mail/mailfilter

The maildrop filter file for your site. You should not changes this setting.

filtering_report_spam_spamassassin = 1
filtering_report_spam_pyzor        = 0          # don't enable this with report_spamassassin

You can have your mail server report spam messages via spamassassin -r or to the pyzor servers. Since the spamassassin reporting includes pyzor, if you choose it, disable pyzor reporting.

filtering_debug                    = 1

Enable maildrop debugging to be written to /var/log/mail/maildrop.log

#######################################
#           qmail-send                #
#######################################

send_log_method                = multilog

You have several choices for qmail-send logging:

syslog - logs to syslog (normally /var/log/maillog on FreeBSD). This is generally not recommended, but it may be handy for sendmail refugees.

multilog - logs via multilog to the location specified under "Qmail Settings." - This is required for maillogs & RRDutil, and is the recommended logging method for qmail and the toaster.

debug - enables full debugging, records entire SMTP converation (and also logs via multilog).

stats - only logs stats lines (via multilog).

disabled - silently discards all logs

send_log_maxsize_bytes         = 1000000

It's important to make sure maxsize_bytes is larger than 5 minutes of logging. You can determine this by checking the size of the files in /var/log/mail/send. If any approach this file size, raise it. By default, toaster-watcher will trigger maillogs every 5 minutes, updating your mail message counters.

send_log_isoqlog               = 1

This allows you to choose whether your qmail-send logs will be post-processed by isoqlog. This will trigger isoqlog every 5 minutes at which time it'll update the pretty HTML pages it generates. This is a handy default but if you have a really busy mail server (see if isoqlog takes more than a couple seconds to run) with lots of logs, it's better to disable this and run isoqlog from cron less frequently.

send_mailbox_string            = ./Maildir/

This allows you to change your default delivery location. Most toasters will not change this. For a good explanation of other qmail delivery options, see http://www.lifewithqmail.org/

#######################################
#           qmail-smtpd               #
#######################################

smtpd_listen_on_address         = all     # all, a hostname, or IP
smtpd_listen_on_port            = smtp    # smtp or a port number

On which address and port should the toaster listen for smtp connections?

For the port number, "smtp" means port 25 (as defined by /etc/services).

smtpd_hostname                  = system

Where should the toaster get the hostname to be reported by the SMTP service?

system - will set to the systems hostname (as set in /etc/rc.conf) qmail - will set to contents of qmail/control/me Anything else is considered to be a hostname.

# smtpd_hostname [ system | qmail | mail.example.com ]
#
#  system - will set to the systems hostname
#  qmail  - will set to contents of qmail/control/me
#  other  - anything else is considered to be a hostname
##

smtpd_max_memory_per_connection = 25      # in megabytes
smtpd_max_connections           = 50
smtpd_max_memory                = 256

smptd_max_memory_per_connection sets the maximum amount of RAM for any particular SMTP connection (this is enforced by "softlimit"). If you are running clamav, and SpamAssassin, it's very possible that 25 megabytes per connection may not be enough. This is a VERY important setting, because softlimit/qmail will start deferring (soft-bouncing) mail if the smtpd processes use more memory than allowed in this value.

If smtpd_max_connections is exceeded, further connections are deferred. (For those familiar with "Life With Qmail", this replaces the "concurrencyincoming" file).

smtpd_max_memory should be set to smtpd_max_connections multiplied by smtpd_max_memory_per_connection.

Suppose your machine has 1024MB of RAM. It's primarily a mail exchanger, so you want to allow SMTP processes to use 750MB of your RAM, leaving just a touch over 256MB for other processes. You set your smtpd_max_memory to 750.

To avoid any one particular smtp connection growing out of control, you set smtpd_max_memory_per_connection to 50MB.

You should then set smtpd_max_connections to 15. (15 * 50 = 750).

If you want to accept more than 15 simultaneous connections, you'll either need to raise smtpd_max_memory, or lower smtpd_max_memory_per_connection.

If you set smtpd_max_memory close to (or higher than) the amount of real RAM in your machine, your server can run out of real RAM and start to swap. It's quite likely that your machine will slow to a crawl if this happens.

toaster-watcher will warn you (and lower your smtpd_max_connections value) if your smtpd_max_memory is lower than smtpd_max_connections multiplied by smtpd_max_memory_per_connection.

smtpd_use_mysql_relay_table     = 1

Set this to zero if you are not using the patched version of tcpserver built by the toaster install.

For more information, see http:///mail-toaster.org/patches/tcpserver-mysql.shtml

smtpd_lookup_tcpremotehost      = 0
smtpd_lookup_tcpremoteinfo      = 0
smtpd_dns_paranoia              = 0
smtpd_dns_lookup_timeout        = 26

DNS lookups allow you to be more careful about the mail you accept, but they can also slow down connections to your toaster. If you want to reject mail based on the absence of reverse DNS, as described in the toaster FAQ, you must set smtpd_lookup_tcpremotehost to 1.

smtpd_run_as_user               = vpopmail
smtpd_run_as_group              = vchkpw
smtpd_chkusr_patch              = 1
smtpd_auth_enable               = 1

smtpd_chkusr_patch can be turned on and off from here. (This option only functions if this patch was installed, based on the qmail_chk_usr_patch setting, above). More information about the chkusr patch can be found here: http://www.interazioni.it/qmail/

smtpd_auth_enable lets you choose whether to allow SMTP AUTH, a method of authenticated relaying. This is recommended.

smtpd_checkpasswd_bin      = vpopmail_home_dir/bin/vchkpw
smtpd_relay_database       = vpopmail_home_dir/etc/tcp.smtp.cdb

Locations of a few programs and standard config files.

##
# smtpd_log_method - [ syslog | multilog | debug | stats | disabled ]
#
# - syslog   - logs to $mail_syslog ( /var/log/maillog )
# - multilog - logs via multilog to $qmail_log/smtp
# - debug    - records entire SMTP converation
# - stats    - only logs stats lines
# - disabled - silently discards all logs
##

smtpd_log_method                = multilog
smtpd_log_maxsize_bytes         = 1000000    # must be > 5 minutes of logging

These options are similar to the options for logging in the qmail-send section

rbl_enable                      = 1    # master RBL switch.
rbl_enable_fail_closed          = 1    # default is on
rbl_enable_soft_failure         = 1    # default is on
rbl_timeout                     = 60   # default is 60 seconds
rbl_reverse_dns                 = 1    # block on absence of reverse DNS
rbl_reverse_dns_failure         = soft # soft (451) | hard (553)

See the Toaster FAQ for a great explanation of what blacklists (RBL) are and why you might want to use them to block spam.

Toaster-watcher monitors the RBLs you list here. Only RBLs that are working will be used by your SMTP service.

rbl_enable_soft_failure decides whether an RBL hit results in a deferral or an immediate bounce: 1 produces a deferral; 0 produces an immediate bounce (553 error).

The rbl_reverse_dns paramaters are not fully implemented, but will eventually allow you to bounce messages from servers which do not have Reverse DNS configured. See the FAQ for how to implement that feature now. A soft error returns a 451 error, a hard error is a 553.

You can define a custom error message for each RBL by setting the value rbl_bl.example.org_message to be the error message you want returned when you reject a message.

To enable an RBL, simply set it's value to 1. However, you can optionally control the sort order of RBLs in your smtp/run file by setting values higher than 1, in the order in which you'd like them listed in smtp/run. So, for the RBL you wante listed first, set it's value to 2, the second is 3, etc. When using the custom sort, be careful not to define any number more than once (except 0 and 1). Doing so will cause only one of the duplicated RBLs to be used.

rbl_sbl.spamhaus.org            = 1
rbl_sbl.spamhaus.org_message    = You are a known spammer, go away
rbl_bl.ordb.org                 = 1
rbl_list.dsbl.org               = 1
rbl_bl.spamcop.net              = 1
rbl_relays.ordb.org             = 1
rbl_dev.null.dk                 = 1
rbl_rbl-plus.mail-abuse.org     = 0    # Subscription only!
rbl_blackholes.mail-abuse.org   = 0    # Subscription only!
rbl_relays.mail-abuse.org       = 0    # Subscription only!
rbl_dialups.mail-abuse.org      = 0    # Subscription only!
rbl_korea.services.net          = 1    # Block all of Korea
rbl_cn.rbl.cluecentral.net      = 1    # Block all of China
rbl_kr.rbl.cluecentral.net      = 1    # Block all of Korea
rbl_dsn.rfc-ignorant.org        = 1
rbl_whois.rfc-ignorant.org      = 1
rbl_abuse.rfc-ignorant.org      = 1
rbl_postmaster.rfc-ignorant.org = 1
rbl_relays.visi.com             = 1
rbl_opm.blitzed.org             = 1
rbl_dnsbl.sorbs.net             = 1
rbl_relays.osirusoft.com        = 0   # DEAD
rbl_formmail.relays.monkeys.com = 0   # monkeys.com DEAD as of 2003.09.22
rbl_proxies.relays.monkeys.com  = 0   # monkeys.com DEAD as of 2003.09.22
rbl_abuse.easynet.nl            = 0   # DEAD as of 2003.12.11

This set of options lets you choose which RBLs to use. Think carefully about which RBLs you use; you are allowing a third party's opinion to determine what mail your server will accept and reject. This isn't necessarily a bad thing, but you should evaluate each RBL, learn what you can about how it is set up, and make a judgement call about whether (a) you trust the people running it and (b) you agree with their policies on when to blacklist someone.

The author of this documentation, for example, thinks it is WRONG to blacklist IP addresses solely on the basis of their country of origin, and thus he does not use korea.services.net, cn.rbl.cluecentral.net, or kr.rbl.cluecentral.net. Other administrators have observed that 99% of the mail their users receive from these countries is spam, and so feel that they are justified in using these RBLs. It's your mail server; decide on a reasonable policy and choose blacklists accordingly.

If you want to add blacklists to this list, you can just add them. For example, to use the combined SBL-XBL list published by spamhaus, just add "rbl_sbl-xbl.spamhaus.org = 1" and it will be recognized by toaster-watcher.

A list of active RBL's is available here: http://www.spamlinks.net/filter-dnsbl-lists.htm

And a list of dead RBL's is here: http://www.spamlinks.net/filter-dnsbl-dead.htm If you have a RBL in that list being used, it might be wise to disable it.

rwl_enable                      = 0   # master RWL switch.
rwl_list.example.com            = 0   # realtime white list example

Realtime white lists are the opposite of RBLs. To our knowledge, no public RWLs exist. A more common use of this feature would be to run a RWL on a local host, for the purpose of over-riding specific RBL entries.

However, if you only have a few IP addresses you want to override, it's a lot less trouble to just add them to your tcp.smtp file.

If you're interested in using this option, see DJB's docs on rblsmtpd at http://cr.yp.to/ucspi-tcp/rblsmtpd.html. DJB refers to RWLs as anti-RBLs.

#######################################
#              POP3D                  #
#######################################

pop3_daemon                    = qpop3d  #  qpop3d | courier

This block of options controls the POP3 server. As indicated, the toaster supports two different POP3 servers-- qpop3d, distributed with qmail, and courier-pop3, distributed with courier-imap. Currently qpop3d is recommended, and several of the options below will only be effective under qpop3d.

##
# pop3_hostname [ system | qmail | mail.example.com ]
#
#  system - will set to the systems hostname
#  qmail  - will set to contents of qmail/control/me
#  other  - anything else is considered to be a hostname
##

pop3_hostname                  = system
pop3_max_memory_per_connection = 2
pop3_max_connections           = 50
pop3_max_memory                = 256
pop3_lookup_tcpremotehost      = 0
pop3_lookup_tcpremoteinfo      = 0
pop3_dns_paranoia              = 0
pop3_dns_lookup_timeout        = 26
pop3_ip_address_listen_on      = all

The options above are essentially identical to options described in the qmail-smtpd section, so the explanations will not be duplicated here.

However, it's worth noting that POP3 connections require a lot less RAM than SMTP connections.

pop3_checkpasswd_bin           = vpopmail_home_dir/bin/vchkpw

The program listed here will validate usernames and passwords for the POP3 service. Most toasters will not change this setting.

##
# pop3_log_method - [ syslog | multilog | verbose | stats | disabled ]
##

pop3_log_method           = multilog   # multilog required for RRDutil
pop3_log_maxsize_bytes    = 1000000    # make this > 5 minutes of logging

These options are similar to the options for logging in the qmail-send section.

#######################################
#         qmail-smtpd-submit          #
#######################################

submit_enable                  = 1
submit_listen_on_address       = all        # all | IP | hostname
submit_listen_on_port          = submission
submit_hostname                = system

"submission" is confusing to many people, but it should not be. Basically, this creates a second SMTP service, running on a different port number.

If you leave submit_listen_on_port set to "submission" then this will use port 587. The most common use of the submission protocol is for customers whose ISPs block port 25, or route it through their own servers. In many cases they do not block port 587, because the submission service is supposed to be fully authenticated. Another situation where a user might want to use the submission port is when the user's IP address is on a RBL, perhaps because it is a dynamically assigned address. They will not be able to connect to the main smtpd service (running RBLs) unless their IP address is whitelisted, but they will be able to connect to the submit service using SMTP AUTH.

The options for submission should look familiar by now-- they are identical to the options for qmail-smtpd. That's because in fact this is just another copy of qmail-smtpd. The only difference is that you don't set up RBLs for the submission protocol, since you'll only be accepting connections from your authenticated customers.

# smtp-submit_hostname [ system | qmail | mail.example.com ]
#
#  system - will set to the systems hostname
#  qmail  - will set to contents of qmail/control/me
#  other  - anything else is considered to be a hostname
##

submit_max_memory_per_connection = 25            # in megabytes
submit_max_connections         = 50
submit_use_mysql_relay_table   = 0
submit_lookup_tcpremotehost    = 0
submit_lookup_tcpremoteinfo    = 0
submit_dns_paranoia            = 0
submit_dns_lookup_timeout      = 26
submit_run_as_user             = vpopmail
submit_run_as_group            = vchkpw
submit_chkusr_patch            = 1
submit_auth_enable             = 1
submit_checkpasswd_bin         = vpopmail_home_dir/bin/vchkpw
submit_relay_database          = vpopmail_home_dir/etc/tcp.smtp.cdb

##
# submit_log_method - [ syslog | multilog | debug | stats | disabled ]
#
# - syslog   - logs to $mail_syslog
# - multilog - logs via multilog to $logs/smtp
# - debug    - records entire SMTP conversation
# - stats    - only logs stats lines
# - disabled - silently discards all logs
##

submit_log_method                = syslog
submit_log_maxsize_bytes         = 1000000    

It's important to make sure maxsize_bytes is larger than 5 minutes of logging. You can determine this by checking the size of the files in /var/log/mail/submit. If any approach this file size, raise it.

#######################################
#            QMAILADMIN               #
#######################################

qmailadmin_spam_option          = 1
qmailadmin_help_links           = 1.0.8
qmailadmin_install_as_root      = 0
qmailadmin_modify_quotas        = 1
qmailadmin_domain_autofill      = 1
qmailadmin_return_to_mailhome   = 0

The return to mailhome function alters the qmailadmin login page to redirect the web browser from the qmailadmin login page to the mail toaster home (https://mail.yourdomain.com/) as configured in toaster_hostname. It also does this for sqwebmail if this option is set.

qmailadmin_spam_command         =
   | /usr/local/bin/maildrop /usr/local/etc/mail/mailfilter

If qmailadmin_spam_option is set, each user's mail settings will contain a checkbox for spam filtering. When this is checked, that user's mail will be sent through the program set under qmailadmin_spam_command.

Leave this unchanged if you want to use the maildrop script supplied with the toaster. If you have some other filtering method, set it here.

qmailadmin_cgi_bin_dir          = 0  # override toaster_cgi_bin
qmailadmin_http_docroot         = 0  # override toaster_http_docs
qmailadmin_http_images          = /usr/local/www/data/images

If you change these qmailadmin options, you must re-run toaster_setup.pl -s qmailadmin before they will take effect.

#######################################
#            phpMyAdmin               #
#######################################

phpMyAdmin_controluser          = pma
phpMyAdmin_controlpassword      = pmapass
phpMyAdmin_auth_type            = cookie  ( cookie | http )

If you chose to install phpMyAdmin, these options control how you log into that program. The pma user and password is the account that phpMyAdmin uses to log into MySQL and determine if the username and password you are using is a valid MySQL login.

#######################################
#               Simscan               #
#######################################
  
simscan_user                   = clamav  

This is the system user that simscan runs as. If you are using ClamAV, then clamd must be able to read the files in simscans working directly. The easist solution is run them as the same user. You can use another non-root user bot you'll have to to put simscan in the clamav group and set the permissions up appropriately.

simscan_trophie                = 0       # use trophie?
simscan_clamav                 = 1       # use ClamAV?
simscan_ripmime                = 1       # use ripmime?
simscan_quarantine             = 0       # 0, or directory for spam/viral messages

These four options relate to virus handling. Mail::Toaster uses ClamAV by default. If you want to use Trophie, you'll need to install it yourself. With ClamAV, you can have ripmime tear the emails apart, or ClamAV has it's own ScanMail function which does approximately the same thing. This is a topic of great debate on the simscan mailing list, and some folks think one or the other is better. I just enable both.

Finally, if you want simscan to leave the infected or spammy message behind for you to examine, enable the quarantine feature.

simscan_spamassassin           = 1

Simscan can also pass incoming emails through SpamAssassin. This is recommended.

simscan_spam_hits_reject       = 20      

If you want SpamAssassin to reject messages with high spam scores, jest set this to be the score above with emails get rejected.

simscan_spamc_args             = 0       # 0, list of options to pass to spamc
simscan_block_attachments      = 1       # block attachments in /var/qmail/control/ssattach
simscan_block_types            = mp3,exe,com,vbs,lnk,scr,wsh,hta,pif
simscan_per_domain             = 0       # use /var/qmail/control/simcontrol

This is now disabled by default, because it overrides many of the previous settings and confuses new users. Per domain is a very powerful feature that allows each destination domain (and even mailbox) have custom spam, attachment, and virus block settings. If you enable this, you'll want to read the simscan README which documents that rapidly evolving format of the sscontrol file.

http://www.inter7.com/simscan/README

simscan_received               = 1       

adds the Received: by simscan header

If your toaster ever accepts mail from other trusted mail servers, and you enable the block virus senders feature, you may want to specifically include overrides (RBLSMTPD="") for those server IPs in tcp.smtp.

#######################################
#      Maildir Old Message Cleanup    #
#######################################

maildir_clean_interval         = 7  # The # of days between cleanup runs
                                    #  This is the "master" switch for all the
                                    #  following cleanup options. If this is
                                    #  set to zero, nothing below matters.

maildir clean is a function of toaster-watcher. If you turn it on (by setting maildir_clean_interval to something other than zero), then toaster-watcher will create /var/log/mail/clean.log.

maildir_clean_Read             = 0    # remove read messages
maildir_clean_Unread           = 0    # remove unread messages (days)
maildir_clean_Sent             = 90   # sent messages over x days are removed
maildir_clean_Trash            = 14   # trashed messages > x days are removed
maildir_clean_Spam             = 14   # spam messages > x days are removed

For each user on the system, messages matching the criteria above will be deleted. For example, with the default settings, any messages over 14 days old in any user's Spam or Trash folders will be deleted.

maildir_clean_Spam_learn       = 1    # feed spam through sa-learn
maildir_clean_Read_learn       = 1    # feed ham through sa-learn
maildir_clean_Read_learn_days  = 0    # only learn from messages > x days

In addition to deleting messages, the messages can be sent through sa-learn to improve SpamAssassin's Bayesian filtering. Bayesian filtering uses the content of previous spam messages and non-spam (ham) messages to guess which future messages are spam. The more mail sent through sa-learn for each user, the better the Bayesian filtering gets.

For each user of each domain on the system, their read messages are assumed to be "ham" if they are older than maildir_clean_Read_learn_days. If you only want messages older than a few days to be learned as ham (giving users a chance to move any missed spam from their read box to Spam) then increase this setting.

You should know that using the learn features will cause your mail server to spend a lot of time passing messages through sa-learn. If you have a lot of mail on your system, expect this process to take a LONG time. On my personal mail server, with 13 domains and 150 mail accounts the process takes over an hour. My server is an aged dual PIII 550Mhz. Your mileage will vary.

Messages in the spam folder are assumed to be "spam" if they are older than maildir_clean_Spam days. It's similarly a good idea to give users some time to make sure there are no false positives in this folder-- that is, legitimate messages which SpamAssassin has mistakenly tagged.

AUTHOR

David Chaplin-Loebell <david@klatha.com>
Matt Simerson <matt@tnpi.net>

David undertook the writing of this documentation for which I (Matt) and the toaster community are VERY grateful. Thank you David, and may the source always be with you.

SEE ALSO

Mail::Toaster::Conf
toaster.conf

COPYRIGHT AND LICENSE

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

cpanm Mail::Toaster

perl -MCPAN -e shell
install Mail::Toaster