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