This program is an RFC 2645 On-Demand Mail Relay (ODMR) / Authenticated TURN (ATRN) server for vpopmail/vchkpw mail servers running qmail. $Id: INSTALL,v 1.21 2005/08/30 14:28:28 james Exp $ REQUIREMENTS For this program to work, you require; 1. A working vpopmail/vchkpw + qmail setup 2. Perl 5 with MIME::Base64, Mail::Header, CDB_File, vpopmail and Digest::HMAC_MD5 modules 3. Maildir mailboxes 4. A UCSPI-TCP server (tcpserver is ideal) or inetd / xinetd vpopmail is available from http://www.inter7.com/vpopmail/ tcpserver is available from http://cr.yp.to/ucspi-tcp.html Pick up any modules you need from http://search.cpan.org/ Latest information at http://romana.now.ie/#vodmr ## ## ## Upgraders, be sure to check the CHANGES section of README for ## ## potential problems or incompatible changes between releases ## ## ## INSTALLATION (Steps preceeded by ``%'' should be done as a normal user, those preceeded by ``#'' as root) 1. Download and install the perl modules listed above. If you are to use MySQL, Oracle, LDAP, etc (i.e. not vpasswd.cdb) authentication please consult FAQ entry no. 18 for important information. 2. Determine the uid and gid of your vpopmail user. This is usually ``vpopmail''. % id vpopmail uid=89(vpopmail) gid=89(vchkpw) groups=89(vchkpw) On my machine, the uid is 89 and the gid is 89. Substitute your own values below. 3. Edit the odmrd program and give correct values to $qmail, logging(), $secretfield and $require_flag. Look for ``VERIFY AND/OR MODIFY THESE VALUES!'' around line 50. Check the path to your perl interpreter on line 1. It's set to /usr/bin/perl by default. % vi odmrd 4. Copy the odmrd program to an appropriate directory. This example uses /usr/local/sbin. If you choose another directory substitute that in all cases below. # cp -i odmrd /usr/local/sbin # chown root /usr/local/sbin/odmrd # chmod 755 /usr/local/sbin/odmrd 5. Verify your qmail configuration files, and create ODMR-specific ones if necessary. odmrd uses the following qmail control files and will use the same default values as qmail-1.03 if they are not present. Similarly, ``me'' is _required_. odmrlifetime is the length of time, in seconds, a message may remain undelivered in an ODMR mailbox before being rejected. It defaults to two weeks. Set it to zero for messages to remain forever. See qmail-control(5) for more information. bouncefrom bouncehost doublebouncehost doublebounceto helohost me odmrlifetime smtpgreeting Comments are not permitted in any of these control files. 6. Decide which connection manager you will use; tcpserver, inetd or xinetd. a. tcpserver Start tcpserver on the ODMR port (366) running as the vpopmail user. If tcpserver is not in your $PATH specify its full pathname. # sh -c 'tcpserver -vHPR -u 89 -g 89 0 366 \ /usr/local/sbin/odmrd >>/var/log/odmr.log 2>&1 &' Add the tcpserver invocation to your boot scripts to start odmrd at boot time. See FAQ for how to log stderr using cyclog/multilog and how to apply resource limits to restrict memory usage. b. inetd Add an entry for odmrd to the inetd configuration file, usually /etc/inetd.conf # vi /etc/inetd.conf Add a line similar to odmr stream tcp nowait vpopmail /usr/local/sbin/odmrd This assumes your /etc/services has an entry for ``odmr'' as 366/tcp and vpopmail is the name of your vpopmail user. Then signal inetd to reread its configuration file. # kill -HUP See your inetd.conf(5) man page for local information. inetd will probably discard logs sent to STDERR -- double check that the logging() configuration statement is set appropriately. c. xinetd Add an entry for odmrd to the xinetd configuration file, usually /etc/xinetd.conf # vi /etc/xinetd.conf Add a section similar to service odmr { socket_type = stream protocol = tcp wait = no server = /usr/local/sbin/odmrd user = vpopmail } If your system uses separate files in /etc/xinetd.d, create a new file called /etc/xinetd.d/odmr instead and put the service clause in it. This assumes your /etc/services has an entry for ``odmr'' as 366/tcp and vpopmail is the name of your vpopmail user. Then signal xinetd to reread its configuration file(s). # kill -HUP See your xinetd.conf(5) man page for local information. xinetd will probably discard logs sent to STDERR -- double check that the logging() configuration statement is set appropriately. CONFIGURING ODMR FOR A DOMAIN To setup ODMR for example.org, do 1. Setup example.org under vpopmail, set a postmaster mailbox password and have postmaster@example.org receive all mail for example.org. The password you set here is used for normal vpopmail authentication; qmailadmin, Courier imap/pop, etc. Perform EITHER a. OR b., choosing the appropriate one for your version of vpopmail; a. For users of vpopmail 5.3.20 or later # vadddomain -e postmaster example.org Password b. For users of vpopmail 5.3.19 or earlier # vadddomain example.org Password Edit ~vpopmail/domains/example.org/.qmail-default and replace ``bounce-no-mailbox'' with the path to the postmaster's directory. e.g. | /home/vpopmail/bin/vdelivermail '' /home/vpopmail/domains/example.org/postmaster 2. Set the shared secret for postmaster@example.org in clear text by setting a comment and enable ODMR service for the mailbox by setting the V_USER2 flag (V_USER2 is the default - you can use any of V_USER{0,1,2,3} for this purpose). # vmoduser -2 -c ODMR_Password postmaster@example.org DO NOT, I repeat, DO NOT use a colon in the secret string. EVER. You might want to disable webmail/pop/imap/etc access for this mailbox to ensure its mail is always collected over ODMR. See the vmoduser man page for more information. 3. Tell your customer to configure their ODMR / ATRN client to authenticate with username ``postmaster@example.org'' and the secret you set in step 2. Tell them that if they want to use a POP or IMAP client to use the password you set in step 1. You're done. ADVANCED INSTALLATION TOPICS Access control tcpserver can allow or deny connections based on source IP address. See http://cr.yp.to/ucspi-tcp/tcprules.html for more information and the sample-odmrd.rules file supplied with vodmr. Your inetd or xinetd may offer similar features. I'm afraid you'll have to review your system's documentation to discover the magic incantations. Selective debugging odmrd will print truck loads of debugging if started with a -D flag. This is useful during initial installation but is impractical in a production environment, not least because -D logs shared secrets. If you wish to use debugging to investigate a particular problem you could stop tcpserver and restart it with a -D on the odmrd command line. This has three disadvantages; - you must stop the service, if only briefly - you get debugging output from all sessions - you must stop the service again to remove the -D flag You do, however, have alternatives that may be more suitable. odmrd will enable debugging output if a ``DEBUG'' variable is set in its environment. Using tcpserver's environment control abilities you can enable debugging for a particular IP address (or range of addresses) without any interruption to service. For example, 127.0.0.1:allow,DEBUG="yes" :allow compiled with tcprules will allow connections from anywhere and enable debugging output for connections from loopback only. The SIGUSR1 signal enables debugging and the SIGUSR2 signal disables it. You can send these signals to an active odmrd (not tcpserver!) process to change its debugging status while it's running. $Id: INSTALL,v 1.21 2005/08/30 14:28:28 james Exp $