1@(#)@(#)README 2.6 2.6 4/2/91
2
3
4The Post Office Protocol Server: Installation Guide
5
6
7
8Introduction
9
10The Post Office Protocol server runs on a variety of Unix[1] computers
11to manage electronic mail for Macintosh and MS-DOS computers. The
12server was developed at the University of California at Berkeley and
13conforms fully to the specifications in RFC 1081[2] and RFC 1082[3].
14The Berkeley server also has extensions to send electronic mail on
15behalf of a client.
16
17This guide explains how to install the POP server on your Unix
18computer. It assumes that you are not only familiar with Unix but also
19capable of performing Unix system administration.
20
21
22How to Obtain the Server
23
24The POP server is available via anonymous ftp from ftp.CC.Berkeley.EDU
25(128.32.136.9, 128.32.206.12). It is in two files in the pub directory:
26a compressed tar file popper-version.tar.Z and a Macintosh StuffIt archive
27in BinHex format called MacPOP.sit.hqx.
28
29
30Contents of the Distribution
31
32The distribution contains the following:
33
34+ All of the C source necessary to create the server program.
35
36+ A visual representation of how the POP system works.
37
38+ Reprints of RFC 1081 and RFC 1082.
39
40+ A HyperCard stack POP client implementation using MacTCP.
41
42+ A man page for the popper daemon.
43
44+ This guide.
45
46
47Compatibility
48
49The Berkeley POP server has been successfully tested on the following
50Unix operating systems:
51
52+ Berkeley Systems Distribution 4.3
53
54+ Sun Microsystems Operating System versions 3.5 and 4.0
55
56+ Ultrix version 2.3
57
58The following POP clients operate correctly with the Berkeley POP server:
59
60+ The Berkeley HyperMail HyperCard stack for the Apple Macintosh
61 (distributed with the server).
62
63+ The Stanford University Macintosh Internet Protocol MacMH program.
64
65+ The Stanford University Personal Computer Internet Protocol MH
66 program.
67
68+ The mh version 6.0 programs for Unix.
69
70
71Support
72
73The Berkeley POP server is not officially supported and is without any
74warranty, explicit or implied. However, we are interested in your
75experiences using the server. Bugs, comments and suggestions should be
76sent electronically to netinfo@garnet.Berkeley.EDU.
77
78
79Operational Characteristics
80
81The POP Transaction Cycle
82
83The Berkeley POP server is a single program (called popper) that is
84launched by inetd when it gets a service request on the POP TCP port.
85(The official port number specified in RFC 1081 for POP version 3 is
86port 110. However, some POP3 clients attempt to contact the server at
87port 109, the POP version 2 port. Unless you are running both POP2 and
88POP3 servers, you can simply define both ports for use by the POP3
89server. This is explained in the installation instructions later on.)
90The popper program initializes and verifies that the peer IP address is
91registered in the local domain, logging a warning message when a
92connection is made to a client whose IP address does not have a
93canonical name. For systems using BSD 4.3 bind, it also checks to see
94if a cannonical name lookup for the client returns the same peer IP
95address, logging a warning message if it does not. The the server
96enters the authorization state, during which the client must correctly
97identify itself by providing a valid Unix userid and password on the
98server's host machine. No other exchanges are allowed during this
99state (other than a request to quit.) If authentication fails, a
100warning message is logged and the session ends. Once the user is
101identified, popper changes its user and group ids to match that of the
102user and enters the transaction state. The server makes a temporary
103copy of the user's maildrop (ordinarily in /usr/spool/mail) which is
104used for all subsequent transactions. These include the bulk of POP
105commands to retrieve mail, delete mail, undelete mail, and so forth. A
106Berkeley extension also allows the user to submit a mail parcel to the
107server who mails it using the sendmail program (this extension is
108supported in the HyperMail client distributed with the server). When
109the client quits, the server enters the final update state during which
110the network connection is terminated and the user's maildrop is updated
111with the (possibly) modified temporary maildrop.
112
113
114Logging
115
116The POP server uses syslog to keep a record of its activities. On
117systems with BSD 4.3 syslogging, the server logs (by default) to the
118"local0" facility at priority "notice" for all messages except
119debugging which is logged at priority "debug". The default log file is
120/usr/spool/mqueue/POPlog. These can be changed, if desired. On
121systems with 4.2 syslogging all messages are logged to the local log
122file, usually /usr/spool/mqueue/syslog.
123
124Problems
125
126If the filesystem which holds the /usr/spool/mail fills up users will
127experience difficulties. The filesystem must have enough space to hold
128(approximately) two copies of the largest mail box. Popper (v1.81 and
129above) is designed to be robust in the face of this problem, but you may
130end up with a situation where some of the user's mail is in
131
132 /usr/spool/mail/.userid.pop
133
134and some of the mail is in
135
136 /usr/spool/mail/userid
137
138If this happens the System Administrator should clear enough disk space
139so that the filesystem has at least as much free disk as both mailboxes
140hold and probably a little more. Then the user should initiate a POP
141session, and do nothing but quit. If the POP session ends without an
142error the user can then use POP or another mail program to clean up his/her
143mailbox.
144
145Alternatively, the System Administrator can combine the two files (but
146popper will do this for you if there is enough disk space).
147
148
149Debugging
150
151The popper program will log debugging information when the -d parameter
152is specified after its invocation in the inetd.conf file. Care should
153be exercised in using this option since it generates considerable
154output in the syslog file. Alternatively, the "-t <file-name>" option
155will place debugging information into file "<file-name>" using fprintf
156instead of syslog. (To enable debugging, you must edit the Makefile
157to add -DDEBUG to the compiler options.)
158
159For SunOS version 3.5, the popper program is launched by inetd from
160/etc/servers. This file does not allow you to specify command line
161arguments. Therefore, if you want to enable debugging, you can specify
162a shell script in /etc/servers to be launched instead of popper and in
163this script call popper with the desired arguments.
164
165
166Installation
167
1681. Examine this file for the latest information, warnings, etc.
169
1702. Check the Makefile for conformity with your system.
171
1723. Issue the make command in the directory containing the popper
173 source.
174
1754. Issue the make install command in the directory containing the
176 popper source to copy the program to /usr/etc.
177
1785. Enable syslogging:
179
180 + For systems with 4.3 syslogging:
181
182 Add the following line to the /etc/syslog.conf file:
183
184 local0.notice;local0.debug /usr/spool/mqueue/POPlog
185
186 Create the empty file /usr/spool/mqueue/POPlog.
187
188 Kill and restart the syslogd daemon.
189
190 + For systems with 4.2 syslogging:
191
192 Be sure that you are logging messages of priority 7 and higher.
193 For example:
194
195 7/usr/spool/mqueue/syslog
196 9/dev/null
197
1986. Update /etc/services:
199
200 Add the following line to the /etc/services file:
201
202 pop 110/tcp
203
204 Note: This is the official port number for version 3 of the
205 Post Office Protocol as defined in RFC 1081. However, some
206 POP3 clients use port 109, the port number for the previous
207 version (2) of POP. Therefore you may also want to add the
208 following line to the /etc/services file:
209
210 pop2 109/tcp
211
212 For Sun systems running yp, also do the following:
213
214 + Change to the /var/yp directory.
215
216 + Issue the make services command.
217
2187. Update the inetd daemon configuration. Include the second line ONLY if you
219 are running the server at both ports.
220
221 + On BSD 4.3 and SunOS 4.0 systems, add the following line to the
222 /etc/inetd.conf file:
223
224 pop stream tcp nowait root /usr/etc/popper popper
225 pop2 stream tcp nowait root /usr/etc/popper popper
226
227 + On Ultrix systems, add the following line to the
228 /etc/inetd.conf file:
229
230 pop stream tcp nowait /usr/etc/popper popper
231 pop2 stream tcp nowait /usr/etc/popper popper
232
233 + On SunOS 3.5 systems, add the following line to the
234 /etc/servers file:
235
236 pop tcp /usr/etc/popper
237 pop2 tcp /usr/etc/popper
238
239 Kill and restart the inetd daemon.
240
241You can confirm that the POP server is running on Unix by telneting to
242port 110 (or 109 if you set it up that way). For example:
243
244%telnet myhost 110
245Trying...
246Connected to myhost.berkeley.edu.
247Escape character is '^]'.
248+OK UCB Pop server (version 1.6) at myhost starting.
249quit
250Connection closed by foreign host.
251
252
253Release Notes
254
2551.83 Make sure that everything we do as root is non-destructive.
256
2571.82 Make the /usr/spool/mail/.userid.pop file owned by the user rather
258 than owned by root.
259
2601.81 There were two versions of 1.7 floating around, 1.7b4 and 1.7b5.
261 The difference is that 1.7b5 attempted to save disk space on
262 /usr/spool/mail by deleting the users permanent maildrop after
263 making the temporary copy. Unfortunately, if compiled with
264 -DDEBUG, this version could easily wipe out a users' mail file.
265 This is now fixed.
266
267 This version also fixes a security hole for systems that have
268 /usr/spool/mail writeable by all users.
269
270 With this version we go to all new SCCS IDs for all files. This
271 is unfortunate, and we hope it is not too much of a problem.
272
273 Thanks to Steve Dorner of UIUC for pointing out the major problem.
274
2751.7 Extensive re-write of the maildrop processing code contributed by
276 Viktor Dukhovni <viktor@math.princeton.edu> that greatly reduces the
277 possibility that the maildrop can be corrupted as the result of
278 simultaneous access by two or more processes.
279
280 Added "pop_dropcopy" module to create a temporary maildrop from
281 the existing, standard maildrop as root before the setuid and
282 setgid for the user is done. This allows the temporary maildrop
283 to be created in a mail spool area that is not world read-writable.
284
285 This version does *not* send the sendmail "From " delimiter line
286 in response to a TOP or RETR command.
287
288 Encased all debugging code in #ifdef DEBUG constructs. This code can
289 be included by specifying the DEGUG compiler flag. Note: You still
290 need to use the -d or -t option to obtain debugging output.
291
2921.6 Corrects a bug that causes the server to crash on SunOS
293 4.0 systems.
294
295 Uses varargs and vsprintf (if available) in pop_log and
296 pop_msg. This is enabled by the "HAVE_VSPRINTF"
297 compiler flag.
298
299 For systems with BSD 4.3 bind, performs a cannonical
300 name lookup and searches the returned address(es) for
301 the client's address, logging a warning message if it
302 is not located. This is enabled by the "BIND43"
303 comiler flag.
304
305 Removed all the includes from popper.h and distributed
306 them throughout the porgrams files, as needed.
307
308 Reformatted the source to convert tabs to spaces and
309 shorten lines for display on 80-column terminals.
310
3111.5 Creates the temporary maildrop with mode "600" and
312 immediately unlinks it.
313
314 Uses client's IP address in lieu of a canonical name if
315 the latter cannot be obtained.
316
317 Added "-t <file-name>" option. The presence of this
318 option causes debugging output to be placed in the file
319 "file-name" using fprintf instead of the system log
320 file using syslog.
321
322 Corrected maildrop parsing problem.
323
3241.4 Copies user's mail into a temporary maildrop on which
325 all subsequent activity is performed.
326
327 Added "pop_log" function and replaced "syslog" calls
328 throughout the code with it.
329
3301.3 Corrected updating of Status: header line.
331
332 Added strncasecmp for systems that do not have one.
333 Used strncasecmp in all appropriate places. This is
334 enabled by the STRNCASECMP compiler flag.
335
3361.2 Support for version 4.2 syslogging added. This is
337 enabled by the SYSLOG42 compiler flag.
338
3391.1 Several bugs fixed.
340
3411.0 Original version.
342
343
344Limitations
345
346+ The POP server copies the user's entire maildrop to /tmp and
347 then operates on that copy. If the maildrop is particularly
348 large, or inadequate space is available in /tmp, then the
349 server will refuse to continue and terminate the connection.
350
351+ Simultaneous modification of a single maildrop can result in
352 confusing results. For example, manipulating messages in a
353 maildrop using the Unix /usr/ucb/mail command while a copy of
354 it is being processed by the POP server can cause the changes
355 made by one program to be lost when the other terminates. This
356 problem is being worked on and will be fixed in a later
357 release.
358
359
360Credits
361
362The POP server was written by Edward Moy and Austin Shelton with
363contributions from Robert Campbell (U.C. Berkeley) and Viktor Dukhovni
364(Princeton University). Edward Moy wrote the HyperMail stack and drew
365the POP operation diagram. This installation guide was written by
366Austin Shelton.
367
368
369Footnotes
370
371[1] Copyright (c) 1990 Regents of the University of California.
372 All rights reserved. The Berkeley software License Agreement
373 specifies the terms and conditions for redistribution. Unix is
374 a registered trademark of AT&T corporation. HyperCard and
375 Macintosh are registered trademarks of Apple Corporation.
376
377[2] M. Rose, Post Office Protocol - Version 3. RFC 1081, NIC,
378 November 1988.
379
380[3] M. Rose, Post Office Protocol - Version 3 Extended Service
381 Offerings. RFC 1082, NIC, November 1988.
382