Microbrew Message Center Version 0.1.2 Alpha Multi-server Mailer Suite http://www.microbrew.org/products/mmc/ by Bulent Yilmaz and James Brown LICENSING ========= Microbrew Message Center is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation; either version 2 of the License, or (at your option) any later version. Microbrew Message Center is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details. You should have received a copy of the GNU General Public License along with MicroSieve; if not, write to the Free Software Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA A full copy of the GNU General Public License can be found at: http://www.gnu.org/licenses/gpl.txt This distribution includes the software package popa3d. The modifications made to this code for use in Microbrew Message Center are also covered under the GNU General Public License. All other code in the package is covered under the original license of popa3d. CAVEAT EMPTOR ============= This software is in early alpha development. We're not really sure that it will work for you, nor do we think it will work well at this time. There are numerous bugs, inefficient code segments, and possibly a few security vulnerabilities. DO NOT USE THIS IN A PRODUCTION ENVIRONMENT! This release is preview only release being destributed in an effort to solicit comments and suggestions. PLATFORMS ========= Supported Platforms: - Linux 2.4.x Proposed Platform Support: - Solaris 7 & 8 Any patches to make it work on any platform or news server are welcome. Please report any successful compiles/uses on other platforms and news servers to the author so it can be included in this list. ARCHITECTURE ============ Please read this section for a better understanding of how to install Microbrew Message Center. Microbrew Message Center consists of four distinct sections: 1. Web Server - for user configuratoin. 2. Database Server - for configuration storage and accessibility. 3. Mail Server - for actual receipt and delivery of mail. 4. Name Server - for name service configuration for multiple mail servers. There are many ways to configure these sections. Here are a few recommended ways (numbers are projected): 1. Simple one machine configuration: This configuration is ideal for small configurations (up to 5,000 users). All four sections should be installed on one server and should have virtually no interaction problems. Follow the directions below for all four sections on one machine. 2. Medium configuration: This configuration consists of two or more servers (up to 100,000 users). The Web Server, Database Server, and Name server sections should be installed on one server by themselves. These three sections should have low enough demand on processor power as to be able to run together without competing too much for the processor. However, this will be the limiting point for number of users the system can handle. The other server or servers will be set up only to handle mail. The configuration of Microbrew Message Center will allow for an unlimited number of mail servers, so as one mail server becomes congested more can be added to expand the capacity of the system. It should be possible to expand until the web/database/name server becomes congested. 3. Large configuration: This configurations consists of at least four servers (up to 500,000 users). In this configuration, each of the four sections mentioned would get its own server. This will allow for the database server and web server to keep from choking each other out and would allow the name server to supply more queries to the mail servers and do so quicker. As with the last one, there would be mulitple mail servers configured to do the mail. With the load on the web and database servers alleviated, more mail servers should be able to be added than with the Medium Configuration. 4. Massive configuration: While this option is not yet possible with the way we have things written, this will become a design goal once we get the rudimentary systems working the way we want them to. This should be able to support an unlimited number of users. The proposed solution is to allow for many front end web servers which are linked to multiple synchronized databases. If necessary this would support multiple name servers and as is currently supported an unlimited number of mail servers. INSTALLATION ============ After you've decided which configuration you want, you need to install the appropriate sections of Microbrew Message Center on the corresponding machines. The following goes into detail of how to install each section. 1. Web Server Machine: The web server machine must first have the following software packages installed. A brief description of how to install these packages in a sane fashion can be found in the docs: a. Apache 1.3.x - See INSTALL.apache b. PHP 4.1.x - See INSTALL.php c. MySQL 3.23.x client libraries. To complete the install on this server, you can either copy the 'vhosts' directory to a desired directory, or you can do the following (especially if the mail server is running on the same machine): a. ./configure b. make c. make install d. make conf You will also have to modify the apache configuration file to accomodate two virtual domains. A good set up can be found in the 'apache.vhosts' file in the 'contrib' directory: a. Modify the apache 'httpd.conf' for two vhosts. These correspond to the 'admin' and 'config' directories in the 'vhosts' directory. More information about the '.htaccess' files can be found in the sample configuration. b. Make sure to add the entries for these vhosts on your nameserver. c. Create the '.htaccess' file for the user 'root' in the 'vhosts/admin/htdocs/superuser' directory using the 'htpasswd' utility that comes with apache. If you don't want to use the username 'root' you must configure apache as to allow login for that user. d. You may also have to chown the '.htaccess.db' to the user that your web server runs as in the following directories in the vhosts hierarchy: i. admin/htdocs ii. config/htdocs iii. config/htdocs/user 2. Database Server Machine: The database server machine must first have the following software packages installed. A brief description of how to install these packages in a sane fashion can be found in the docs: a. MySQL 3.23.x - See INSTALL.mysql To complete the install on this server, you must add the base databases and tables. The actual commands to run in mysql can be found in the 'mysql.db file in the 'contrib' directory. a. Create two databases. One called 'mmcadmin' and the other one called 'mmccust'. b. In the 'mmcadmin' database create the 'admins', 'mailservers', and 'customers' tables. Specifications for these tables can be found in the 'mysql.db' file in the 'contrib' directory. 3. Mail Server Machine(s): Each of the mail server machines must first have the following software packages installed. a. Sendmail 8.12.x - Perform a default install. To create the sendmail.cf make the following changes first. - Copy the file 'mmclda.m4' from the 'contrib' directory to the 'cf/mailer' directory in sendmail. - Copy the file 'proto.m4' from the 'contrib' directory to the 'cf/m4' directory in sendmail. This is a patched version of the default sendmail proto.m4 file to get it to work with MMC. - Copy the file 'mmc-linux.mc' from the 'contrib' directory to the 'cf/cf' directory in sendmail for a basis generating the sendmail.cf file. Edit this file to suit your needs. To complete the install on this server, you need to compile the source in the 'src' directory: a. ./configure b. make c. make install d. make conf This will install the two required packages the 'bin' directory. Now you should edit the configuration files in the 'etc' directory. The 'make conf' command should have created a good set up if you answered the questions well. As of this release the configuration files MUST have only one tab separating the field and the value. Now you need to add a cron job to run 'contrib/makevirt.sh'. This will generate the virtusertable for sendmail as well as create the directories for the mailboxes in order to accept new entries into the user list. This should be run fairly regularly, about every hour or so: 5 * * * * /usr/local/mmc/contrib/makevirt.sh Also add a cron job to run 'bin/reaper'. This will delete any mailboxes that have been deleted. This really needs to be run once a day or so, and probably should be run at an off-peak time: 30 4 * * * /usr/local/mmc/bin/reaper Now you should run the two programs 'oneuser' and 'popb4relayd'. The program 'oneuser' is a daemon that listens on port 4000 that will update the virtusertable and user passwords when a change is made. The program 'popb4relayd' is a pop before relay controller daemon to keep the mail server from becoming an open relay. 4. Name Server Machine: The name server machine must first have the following software packages installed. a. BIND 8.3.x or later - Default install To complete the install on this server, you need to compile the source (if this is the same machine as the mail server, this should be done): a. ./configure b. make c. make install d. make conf This will install the required package 'genzone' in the 'bin' directory. Now you should configure the 'db.conf' and 'ns.conf' files in the 'etc' directory. The files have the following required fields: db.conf: DBSERVER - Defines which host to connect to when talking to the database. USERNAME - Database username to use when connecting to the database. PASSWORD - Password for the user when connecting to the database. ns.conf: TTL - Defines the authoritative TTL of the zone in seconds. PRINS - The name of the primary name server for this zone. HOSTMASTER - Email address for the hostmaster for this (sub)domain. REFRESH - Refresh time in seconds for the zone. RETRY - Retry time in seconds for the zone. EXPIRE - Expire time in seconds for the zone. MINIMUM - Minimum time in seconds for the zone. STUBFILE - Filename for additional zone information to be put into the zone. As of this release the configuration files MUST have only one tab separating the field and the value. Now you should configure the name server to be authoritative for the subdomain you are going to be using. The zone file that the server should point to should be 'master/mmczone' as the 'makezone.sh' script will copy the zone to this file: zone "" { type master; file "master/mmczone"; }; Now run the program 'genzone' in the 'bin' directory and examine the output in 'ns.zone' in the 'etc' directory. Examine the generated contents and add additional zone info such as NS and MX records for the zone in the file you specified for in the 'ns.conf' file for the entry 'STUBFILE'. These have to be in proper zone file format as it is included verbatim into the generated zone. After that configuration is finished, you need to add a cron job to run '/usr/local/mmc/bin/makezone.sh'. This will generate the zone file, copy it to the '/var/named/master/mmczone', and reload the zone into the nameserver. This should be run reasonably regularly, about every hour or so: 7 * * * * /usr/local/mmc/bin/makevirt.sh RUNNING ======= To get the system running, a few things have to be done first. 1. Login to "http://admin./superuser" Use the username 'root' (or the user you set) and password you set up when you installed the web server portion. a. Click on "Database Options" and define the server, username, and password used to log into the database. These will most likely be the same ones you defined in db.conf for the mail and name servers. b. Go back to the super user administration interface and click on "Administrator Accounts" and then click on "Add User". Enter one or more users who will add mail service customers. c. Go back to the super user administration interface and click on "Mail Server Options" and then on "Add Server". Enter the hostname and IP address of the mail server(s) you set up. Although it does nothing at this time, you may also choose to make this server a backup MX server for all the other servers. Feel free to explore the rest of the interface at this time. 2. Now login to "http://admin./" Use the username and password you defined in the above section. a. Click on "Add Customer" and enter the information for a customer, or at least the (sub)domain that you are using for this setup. The customer is keyed off of the primary domain, so this has to be unique, but there shouldn't be too much of a problem with that. b. Now set up the domain information to point its MX record at the server you defined for the domain. Change the all '.' characters in the domain to '-' and follow it by your domain. For example ( is mail.microbrew.org): example.com IN MX 10 example-com.mail.microbrew.org The scripts on the name server machine will create the A record for this entry. Feel free to explore the rest of the interface at this time. 3. Now log into "http://config./" Use the primary domain for the customer as the username and the password defined while creating the user. a. Click on "User Management" and then click on "Add User". As before, add the information for the user. The username must be unique for each user. This will be the username that the user will be when they receive email. b. Optionally, log into "http://config./user" and make sure that the user addition was successful. You will need to log in as "username@domain" and use the password you entered. c. Wait for the nameserver and mailserver scripts to run (or run them manually for testing). At this point you should be able to send a test message to the mail server to the user that you set up. ADDITIONAL HELP =============== If you get stuck on a portion of this setup, you can get additional help by posting a message to the Microbrew Message Center forums which can be found at "http://www.microbrew.org/forums/mmc/".