Modifications to use the new mmlimitrate(3) API
[mmondor.git] / mmsoftware / mmmail / README
0ba2fea9 1$Id: README,v 1.5 2003/06/19 15:03:29 mmondor Exp $
3MMMAIL(8) NetBSD System Manager's Manual MMMAIL(8)
6 mmmail - SMTP and POP3 suite of daemons
9 mmsmtpd [config_file]
10 mmpop3d [config_file]
13 mmmail consists of a suite of SMTP and POP3 daemons, mmsmtpd(8) and
14 mmpop3d(8) which support bandwidth shaping and a MySQL backend for mes-
15 sage storage. These servers run as an unprivileged user and should
16 therefore be more secure than most MTAs. Additionally, some effort was
17 put in providing various protection methods against Denial of Service at-
18 tacks, and mail bombing. It is also possible to run the daemons into a
19 chroot(2) jail.
21 Currently, relaying is not supported by mmmail but work is in progress to
22 eventually have mmfilterd and mmrelayd written as part of mmmail. There
23 are no official HTTP administration frontends for mmmail yet neither, al-
24 though there exist third party perl and PHP scripts for apache which can
25 be used, there is no guarentee whatsoever on their security. Eventually
26 a small secure ssl-httpd will be written which should serve remote admin-
27 istration needs for the various mm daemons. Some work is also in progress
28 to redesign some parts of the system so that various message storage and
29 authentication methods could be chosen from (MySQL, pgsql, flatfile, db4,
30 etc), and to allow to delegate administration of particular hosts to
31 their administrator, who could manage the users and mailboxes for that
32 host. There also have been some notes written about a possible eventual
33 mailing list manager system.
35 The current design allows to securely receive mail through SMTP for many
36 users on several hosts, and serve back that mail securely via POP3. It is
37 efficient at doing so. It supports multiple mailboxes per user, aliasing,
38 and virtual hosts. Good statistics are kept using the mmstat(3) interface
39 via mmstatd(8) and the SMTP and POP3 daemons may run on different servers
40 via a persistant TCP link to the MySQL server. There also can be several
41 of each on various servers using replicated MySQL servers.
43 Each mail box can have different limits on the maximum number of messages
44 they may hold, as well as the maximum size their mailbox may grow to, in
45 bytes.
47 mmsmtpd and mmpop3d establish one main connection with the MySQL server
48 each, through which it processes all queries. This normally would be an
49 advantage to keep the file descriptors amount smaller, and for remote
50 connections using TCP/IP to the mysql server, which should cause a speed
51 improvement. It also will re-establish that connection whenever it is
52 lost, for whatever reason, which permits to run the SQL server anywhere
53 on the internet (although running the server on a LAN is recommended, un-
54 less under kerberos, ssh or ipsec tunneling).
56 Special note: As the suite supports vitualhosts, and that some mail
57 clients cannot handle '@' in usernames, it by convention replaces the
58 first '.' in the username by '@' internally, to match it with a mailbox.
59 This prevents using '.' in username part of addresses, _ will be used
60 without problem though: eg: for the mailbox, the cor-
61 responding username would be The password will remain
62 the one of the user who owns that mail box.
65 This document assumes that you know how to manage mysql tables using the
66 mysql client, as you will need to create a new mysql user (typically
67 called mmmail), and a new database for it. Only mmmail user should have
68 access to the mmmail database and only root and the dedicated user under
69 which mysqld runs should be able to access the database files (typically
70 /home/databases/mysql/ directory). These are common security administra-
71 tion procedures that mysqld users should know about. The mmmail suite is
72 highly dependant on the mysql database server. This also means that you
73 are responsible for database integrity, that you must provide it using
74 efficient backup systems, UPS, etc, whatever required for general data
75 safety using MySQL. I also assume that you know how to manage unix file
76 permissions, groups, and how to make sure that mysqld does not run as
77 root, that only mysql user can access the mysql data directory, that you
78 also know how to only allow wanted hosts and users to be able to connect
79 to mysqld, etc. Another important thing to note is that as mmmail source
80 tarball does not use autoconf, you may need to edit the Makefile files,
81 if some libraries or include headerfiles cannot be found using the de-
82 fault ones. (LIBDIR and INCDIR variables may need to be modified espe-
83 cially).
85 mmmail requires mmpasswd(8) and mmstatd(8) which are provided with it.
86 Normally, executing the script should compile the distribution,
87 and should install or upgrade all of the necessary components.
88 Note that there are several configurable options which can be set prior
89 to calling script; Use the './ help' command to see
90 a description of the environment variables which you may want to set.
91 The mmlib/ file contains defaults for building commands, li-
92 brary and include paths, and may be modified if compilation issues occur.
93 The building process is no longer dependant on BSD or GNU make, only
94 /bin/sh is required. You may want to look at the mmstatd(8) and
95 mmstatd.conf(5) man pages on how to configure mmstatd. You first should
96 make sure that you have the following libraries:
98 libpth version 1.4.1 or later (GNU Pth)
99 libmysqlclient (usually part of mysql-client package)
101 Upgrading from 0.0.12 or older to 0.0.13 or later: Note that if you pre-
102 viously were using mmmail 0.0.12 or older, and are upgrading to mmmail
103 0.0.13 or later, two new MySQL tables were introduced for aliasing and
104 FROM:<> support (see scripts/tables.sql for more information). If you
105 wish to ease the transition you should execute the
106 scripts/upgrade-0.0.13.sql MySQL script, so that you don't have to re-
107 create the tables. This should also preserve your current data.
109 Upgrading from 0.0.20 or older to 0.0.21 or later: If you are upgrading
110 from mmmail 0.0.20 to 0.0.21 or later, an important change has been per-
111 formed on the way password hashes are stored. Main reasons for this are
112 that frontend scripts would not easily be able to generate these, and
113 that they were not compatible with system ones, making migration process
114 from real users to virtual ones harder. The size of the user_passwd col-
115 umn of the user MySQL table in the mmmail database will need to be modi-
116 fied. Moreover, the password hashes will need to be changed for all
117 users. Unfortunately, it was impossible to provide a utility to convert
118 old password hashes to new ones because of a bug in the previous base64
119 conversion which would loose some of the last bytes of the MD5 hash.
120 Please see mmpasswd(8) man page for more details on the password hash
121 format. To perform the transition you should execute the
122 scripts/upgrade-0.0.21.sql MySQL script. Your current data will be pre-
123 served.
125 To install, first extract the source code tree
127 # tar xzvf mmmail-0.0.21.tgz
128 # cd mmmail-0.0.21/
130 A script has been provided which permits to build and install/upgrade all
131 binaries, preserving old file permissions and old configuration files in
132 /etc/ if those previously existed. Those will install the binaries into
133 /usr/local/sbin/ and the configuration files to /etc/. Moreover, if the
134 daemons are already running, it makes sure to kill them before writing
135 over the files again, and to restart them afterwards. It is very useful
136 to quickly upgrade mmmail. To execute it, simply execute :
138 # ./
139 # ./
141 The man pages and required binaries should now have been installed in
142 /usr/local, but any old existing configuration files in /etc/ will be
143 preserved in the case of an upgrade. It therefore generally consists of a
144 good idea to consult the configuration files man pages after upgrading,
145 in this case mmsmtpd.conf(5) and mmpop3d.conf(5).
147 Let's now configure mmmail
149 As this does not consist of a MySQL manual, I will restrict the examples
150 to the minimum, as if we were to run the mysql server on the same machine
151 the mail daemons are running on (under which case connections are made
152 using UNIX domain sockets rather than TCP/IP also). The MySQL user name
153 is mmmail, it's password is set to mmmailpassword in this example, and
154 the mmmail database named mmmail. We then make sure that only MySQL root
155 and mmmail users can access the mmmail database (using mysql grant per-
156 mission tables, this does not solve the other issues about database secu-
157 rity which were explaned above).
159 There also is a supplied password program which can be used to generate
160 the hash that mmmail requires for a user password, it has to be case-sen-
161 sitive in the user table. It consists of mmpasswd (See the mmpasswd(8)
162 man page for details). There currently is no software provided to manage
163 users and mailboxes, so the administrator has to edit the tables manually
164 using a MySQL client.
166 An important thing to additionally remember consists of the MySQL
167 max_allowed_packet variable which should be set high enough for the
168 /etc/mmsmtpd.conf MAX_DATA_SIZE configuration option. A common way to
169 perform this is passing the command line argument -O
170 max_allowed_packet=5M for instance when starting the MySQL server daemon.
172 Let's create the mmmail database, mmmail user, and permit the user to ac-
173 cess it's database, with proper permissions for mmmail suite:
175 $ mysql -u root -p
176 password: ***********
177 > create database mmmail;
178 > use mysql;
179 > insert into user (Host,User,Password)
180 values('localhost','mmmail',password('mmmailpassword'));
181 > insert into db values('localhost','mmmail','mmmail',
182 'Y','Y','Y','Y','N','N','N','N','Y','N');
183 > flush privileges;
185 Now we need to create the mmmail tables from the .sql file. The reason we
186 are doing this as the mysql root user is that mmmail user does not have
187 rights to alter the mmmail database, for obvious security reasons.
189 $ mysql -u root -p mmmail <tables.sql
190 password: *********
192 Now let's create a mail user, and provide two mailboxes at two virtual
193 hosts for it:
195 $ mmpasswd "someuserpassword"
8a21b7a2 196 $1$UrxLMU$f5Hb/pVGURl7sZ.4sEiYD1
198 > use mmmail;
199 > insert into user (user_name,user_passwd,user_created)
8a21b7a2 200 values('some user','$1$UrxLMU$f5Hb/pVGURl7sZ.4sEiYD1',NOW());
201 > insert into box values('',1,5242880,
202 0,500,0,NOW(),NOW(),NOW());
203 > insert into box values('',1,5242880,
204 0,500,0,NOW(),NOW(),NOW());
206 This sets for both boxes the following limits: 5242880 maximum size in
207 bytes for the whole mailbox contents, and 500 messages maximum capacity.
209 Now let's say we want to have all mail sent to the domain redirected to
210 that mailbox we created, we will create an alias for it. Pattern matching
211 is allowed in the alias_pattern field, using '*' and '?'.
46cf2cd5 213 > insert into alias values('*',''
214 '',1,NOW());
216 This will redirect any mail addressed to anyone to mmon-
217 mailbox. The way aliasing works is as follows: The desti-
218 nation address (RCPT) is first looked up. If it exists it is immediately
219 chosen. If it doesn't, the alias table is scanned for the closest match-
220 ing pattern. If a pattern matches, the supplied address is internally
221 substituted by the address set for the alias pattern, and the new address
222 is again looked up. If either no aliases can map the address, or it
223 mapped it to an unexisting box, the address is rejected. This means that
224 if mmondor and lgodbout existed domain, they of course would
225 take precedence. An alias would be looked for afterwards only.
227 Some systems use an empty MAIL FROM:<> address. If you need some hosts to
228 allow it, you can add patterns to accept into the nofrom table. If
229 RESOLVE_HOSTS is TRUE in /etc/mmsmtpd.conf, matches will be checked
230 against both hostnames and addresses in this table. As such, an entry as
231 "" will still match for "localhost", although a "localhost" en-
232 try by itself would obviously only match if resolving worked for the
233 address. Just like for aliases patterns, '*' and '?' pattern
234 matching is performed.
236 > insert into nofrom values('');
0ba2fea9 237 > insert into nofrom values('*');
239 This would allow clients connecting from localhost (weither resolving is
240 turned on or off) to use empty from address while posting mail. Moreover,
241 it would only allowed properly resolved hosts to also do so.
243 Verify that the configuration files in /etc are right, then you should be
244 able to start the daemons, as the superuser (they will drop privileges):
246 /usr/local/sbin/mmstatd
247 /usr/local/sbin/mmsmtpd
248 /usr/local/sbin/mmpop3d
250 If any problem occur, carefully check the syslog logs in /var/log.
253 The /etc/mmsmtpd.conf and /etc/mmpop3d.conf files should only be readable
254 by the superuser. The cause consists in the MySQL access password being
255 held in them.
257 -rw------- 1 root wheel 2510 Sep 8 2002 /etc/mmpop3d.conf
258 -rw------- 1 root wheel 4504 Sep 8 2002 /etc/mmsmtpd.conf
260 It also is important that the MySQL server runs as an unprivileged user,
261 and has decent root and mmmail users passwords set. It is a good idea
262 where possible to have it not listen on the TCP port for more security.
263 Additionally, The MySQL data directory should only be accessible by root
264 and the MySQL server. It is a good idea to restrict root and mmmail users
265 from localhost as well, in the mysql database, and to restrict the mmmail
266 database to the mmmail user, in the db database. Please read the MySQL
267 manual for more information on using it securely. Here are a few example
268 ideas:
270 $ ps axwwwo user,command | grep mysql | grep -v grep
271 mysql /usr/pkg/libexec/mysqld --basedir=/usr/pkg --datadir=/home/mysql --user=mysql --pid-file=/home/mysql/ -O max_allowed_packet=8M --skip-networking
273 $ grep database /etc/group
274 database:*:1000:
276 $ grep mysql /etc/passwd
277 mysql:*:1001:1000::/home/mysql:/sbin/nologin
279 $ ls -ld /home/mysql
280 drwx------ 9 mysql database 512 Dec 31 1997 /home/mysql
282 $ mysql -u root
283 ERROR 1045: Access denied for user: 'root@localhost' (Using password: NO)
284 $ mysql -u mmmail
285 ERROR 1045: Access denied for user: 'mmmail@localhost' (Using password: NO)
288 /usr/local/sbin/mmstatd The mmstatd(8) daemon, required by mmmail
290 /usr/local/sbin/mmsmtpd The SMTP server, see mmsmtpd(8)
292 /usr/local/sbin/mmpop3d The POP3 server, see mmpop3d(8)
294 /etc/mmsmtpd.conf The configuration file for mmsmtpd (See
295 mmsmtpd.conf(5) for details)
297 /etc/mmpop3d.conf The configuration file for mmpop3d (See
298 mmpop3d.conf(5) for details)
301 mmsmtpd and mmpop3d were designed and written by Matthew Mondor and are
302 Copyright (c) 2001-2003, Matthew Mondor, All rights reserved. They were
303 primarily developped on NetBSD but were also mildly tested on Linux prior
304 to release.
307 mmsmtpd(8), mmpop3d(8), mmsmtpd.conf(5), mmpop3d.conf(5), mmstatd(8),
308 mmpasswd(8), setgroups(2), setuid(2), chroot(2), mysqld(1), mysql(1),
309 mmfd(3).
312 mmmail does not support relaying, IMAP and other popular features. It is
313 currently under a totally new design for v2, and will most likely be
314 written from scratch to support alot of features, including mailing list
315 management, administration delegation for domains, multiple storage meth-
316 ods, etc. If you would like to see the current design drafts and offer
317 suggestions, they can be found at
318 under the mmmail section.
320 Please report any bug to
0ba2fea9 322NetBSD 1.6_STABLE 22 December, 2002 5