Modifications to use the new mmlimitrate(3) API
[mmondor.git] / mmsoftware / mmmail / README
CommitLineData
0ba2fea9 1$Id: README,v 1.5 2003/06/19 15:03:29 mmondor Exp $
47071c2b
MM
2
3MMMAIL(8) NetBSD System Manager's Manual MMMAIL(8)
4
5NAME
6 mmmail - SMTP and POP3 suite of daemons
7
8SYNOPSIS
9 mmsmtpd [config_file]
10 mmpop3d [config_file]
11
12DESCRIPTION
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.
20
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.
34
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.
42
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.
46
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).
55
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 mmondor@myhost.net, the cor-
61 responding username would be mmondor.myhost.net. The password will remain
62 the one of the user who owns that mail box.
63
64INSTALLATION
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).
84
85 mmmail requires mmpasswd(8) and mmstatd(8) which are provided with it.
86 Normally, executing the make.sh script should compile the distribution,
87 and install.sh 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 install.sh script; Use the './install.sh help' command to see
90 a description of the environment variables which you may want to set.
91 The mmlib/makedefs.sh 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:
97
98 libpth version 1.4.1 or later (GNU Pth)
47071c2b
MM
99 libmysqlclient (usually part of mysql-client package)
100
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
8a21b7a2
MM
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.
47071c2b
MM
108
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-
8a21b7a2
MM
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
47071c2b
MM
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
8a21b7a2
MM
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
5eb34fba
MM
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.
47071c2b
MM
124
125 To install, first extract the source code tree
126
127 # tar xzvf mmmail-0.0.21.tgz
128 # cd mmmail-0.0.21/
129
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 make.sh :
137
138 # ./make.sh
139 # ./install.sh
140
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).
146
147 Let's now configure mmmail
148
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).
158
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.
165
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.
171
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:
174
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;
184
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.
188
189 $ mysql -u root -p mmmail <tables.sql
190 password: *********
191
192 Now let's create a mail user, and provide two mailboxes at two virtual
193 hosts for it:
194
195 $ mmpasswd "someuserpassword"
8a21b7a2 196 $1$UrxLMU$f5Hb/pVGURl7sZ.4sEiYD1
47071c2b
MM
197
198 > use mmmail;
199 > insert into user (user_name,user_passwd,user_created)
8a21b7a2 200 values('some user','$1$UrxLMU$f5Hb/pVGURl7sZ.4sEiYD1',NOW());
47071c2b
MM
201 > insert into box values('mmondor@myhost.net',1,5242880,
202 0,500,0,NOW(),NOW(),NOW());
203 > insert into box values('mm@anotherhost.net',1,5242880,
204 0,500,0,NOW(),NOW(),NOW());
205
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.
208
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 '?'.
212
46cf2cd5 213 > insert into alias values('*','myhost.net'
47071c2b
MM
214 'mmondor@myhost.net',1,NOW());
215
216 This will redirect any mail addressed to anyone @myhost.net to mmon-
217 dor@myhost.net mailbox. The way aliasing works is as follows: The desti-
218 nation address (RCPT) is first looked up. If it exists it is immediately
46cf2cd5
MM
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 @myhost.net domain, they of course would
225 take precedence. An alias would be looked for afterwards only.
47071c2b
MM
226
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
0ba2fea9
MM
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 "127.0.0.1" will still match for "localhost", although a "localhost" en-
232 try by itself would obviously only match if resolving worked for the
233 127.0.0.1 address. Just like for aliases patterns, '*' and '?' pattern
234 matching is performed.
47071c2b
MM
235
236 > insert into nofrom values('127.0.0.1');
0ba2fea9 237 > insert into nofrom values('*.gobot.ca');
47071c2b
MM
238
239 This would allow clients connecting from localhost (weither resolving is
0ba2fea9
MM
240 turned on or off) to use empty from address while posting mail. Moreover,
241 it would only allowed properly resolved gobot.ca hosts to also do so.
47071c2b
MM
242
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):
245
246 /usr/local/sbin/mmstatd
247 /usr/local/sbin/mmsmtpd
248 /usr/local/sbin/mmpop3d
249
250 If any problem occur, carefully check the syslog logs in /var/log.
251
252SECURITY CONSIDERATIONS
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.
256
257 -rw------- 1 root wheel 2510 Sep 8 2002 /etc/mmpop3d.conf
258 -rw------- 1 root wheel 4504 Sep 8 2002 /etc/mmsmtpd.conf
259
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:
269
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/gobot.pid -O max_allowed_packet=8M --skip-networking
272
273 $ grep database /etc/group
274 database:*:1000:
275
276 $ grep mysql /etc/passwd
277 mysql:*:1001:1000::/home/mysql:/sbin/nologin
278
279 $ ls -ld /home/mysql
280 drwx------ 9 mysql database 512 Dec 31 1997 /home/mysql
281
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)
286
287FILES
288 /usr/local/sbin/mmstatd The mmstatd(8) daemon, required by mmmail
289
290 /usr/local/sbin/mmsmtpd The SMTP server, see mmsmtpd(8)
291
292 /usr/local/sbin/mmpop3d The POP3 server, see mmpop3d(8)
293
294 /etc/mmsmtpd.conf The configuration file for mmsmtpd (See
295 mmsmtpd.conf(5) for details)
296
297 /etc/mmpop3d.conf The configuration file for mmpop3d (See
298 mmpop3d.conf(5) for details)
299
300AUTHOR
301 mmsmtpd and mmpop3d were designed and written by Matthew Mondor and are
5eb34fba
MM
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.
47071c2b
MM
305
306SEE ALSO
307 mmsmtpd(8), mmpop3d(8), mmsmtpd.conf(5), mmpop3d.conf(5), mmstatd(8),
8a21b7a2
MM
308 mmpasswd(8), setgroups(2), setuid(2), chroot(2), mysqld(1), mysql(1),
309 mmfd(3).
47071c2b
MM
310
311BUGS
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 http://mmondor.gobot.ca/software.html
318 under the mmmail section.
319
320 Please report any bug to mmondor@gobot.ca
321
0ba2fea9 322NetBSD 1.6_STABLE 22 December, 2002 5