meillo@59: Additional information may be available in docs/ or on the website.
meillo@174: For installing on GNU/Linux distributions read docs/INSTALL.linux.
meillo@0: 
meillo@59: 
meillo@59: Installation instructions
meillo@59: -------------------------
meillo@59: 
meillo@165: To compile masqmail you need glib (>= 1.2) (http://www.gtk.org). Your
meillo@181: distribution probably provides it. Glib-2.0 works out of the box, for
meillo@181: glib-1.2, you need to adjust configure.ac. See the comment in there.
meillo@0: 
meillo@165: You need a user and a group for masqmail to run. If
meillo@165: 
meillo@165: 	grep '^mail:' /etc/passwd
meillo@165: 	grep '^trusted:' /etc/group
meillo@165: 
meillo@165: shows that the user `mail' and the group `trusted' exist, it's
meillo@165: probably best to use these. If they don't exist, create them:
meillo@0: 
meillo@59: 	groupadd -g 42 trusted
meillo@165: 	useradd -u 23 -g 42 -d / -s /bin/sh -c "Mail Transfer Agent" mail
meillo@0: 
meillo@165: If you use other names than `mail' and `trusted' use the options
meillo@165: described below for configure. The 23 and 42 are just a suggestion,
meillo@165: you can use any (not yet used) number you like, but preferably one
meillo@165: lower than 100. It does not have to be the same for the user `mail'
meillo@165: and the group `trusted'.
meillo@165: 
meillo@0: 
meillo@174: Compiling is a matter of the usual procedure. In the source directory,
meillo@59: after unpacking do:
meillo@0: 
meillo@59: 	./configure
meillo@59: 	make
meillo@59: 	make install
meillo@0: 
meillo@0: 
meillo@0: 
meillo@59: Additional options for configure
meillo@59: --------------------------------
meillo@0: 
meillo@59: See the output of
meillo@0: 
meillo@59: 	./configure -h
meillo@0: 
meillo@165: Here is a selection of the options with additional explanations:
meillo@0: 
meillo@165: --with-user=USER
meillo@165: sets the user as which masqmail will run. Default is 'mail'. USER has
meillo@165: to exist before you 'make install'.
meillo@0: 
meillo@165: --with-group=GROUP
meillo@165: sets the group as which masqmail will run. Default is 'trusted'. GROUP
meillo@165: has to exist before you 'make install'.
meillo@0: 
meillo@0: 
meillo@165: --with-logdir=LOGDIR
meillo@165: sets the directory where masqmail stores its log files. It will be
meillo@165: created if it does not exist. Default is /var/log/masqmail/.
meillo@0: 
meillo@165: --with-spooldir=SPOOLDIR
meillo@165: sets the directory where masqmail stores its spool files. It will be
meillo@165: created if it does not exist. Default is /var/spool/masqmail/.
meillo@0: 
meillo@165: --with-confdir=CONFDIR
meillo@165: sets the default configuration directory to CONFDIR, in case you
meillo@165: prefer another location than /etc/masqmail/.
meillo@0: 
meillo@0: 
meillo@165: --enable-auth
meillo@165: enables ESMTP AUTH support (disabled by default)
meillo@0: 
meillo@165: --enable-maildir
meillo@165: enables qmail style Maildir support (disabled by default)
meillo@0: 
meillo@165: --enable-ident
meillo@175: enables RFC 1413 support. If you have the libident dynamic library
meillo@165: installed, this will be linked, otherwise it will be statically linked
meillo@165: using the sources included in the package.
meillo@0: 
meillo@165: --enable-pop3
meillo@175: enables POP3 support (disabled by default)
meillo@0: 
meillo@165: --disable-resolver
meillo@175: disables resolver support. Without the resolver functions, masqmail
meillo@165: uses only gethostbyname() to resolve DNS names, and you cannot send
meillo@165: mail without a smart host. Not recommended.
meillo@0: 
meillo@165: --disable-smtp-server
meillo@175: disables SMTP server support. You may want this if you do not need
meillo@165: masqmail to listen. In this case, you cannot use masqmail as a smart
meillo@165: host for other hosts on your LAN, you cannot use mail clients that
meillo@165: send SMTP, you cannot even use pine. In short, use of this option is
meillo@165: discouraged unless your resources are extremely limited.
meillo@0: 
meillo@165: 
meillo@165: --with-libcryto
meillo@165: instead of using the md5 and hmac functions within the package, link
meillo@175: dynamically with libcrypto. This applies only if you have POP3 or SMTP
meillo@175: AUTH enabled. Only makes sense if your resources are limited and you
meillo@165: have libcrypto installed. Untested.
meillo@165: 
meillo@165: --with-glib-static
meillo@175: links with glib statically. This makes the binary larger by around 30K
meillo@165: (i386 architecture), but if masqmail is the only binary using glib,
meillo@165: you save some space in total, because you do not need the shared glib
meillo@0: library installed.
meillo@0: 
meillo@0: 
meillo@165: --disable-debug
meillo@175: disables debugging; setting it on the command line or in the
meillo@175: configuration has no effect. Strongly discouraged, since you miss
meillo@175: valuable information if something goes wrong.
meillo@0: 
meillo@59: 
meillo@59: 
meillo@165: Checking the installation
meillo@165: -------------------------
meillo@0: 
meillo@0: Check that 'make install' worked correctly. The following command:
meillo@0: 
meillo@59: 	ls -ld /usr/sbin/masqmail /etc/masqmail /var/log/masqmail/ \
meillo@174: 	       /var/run/masqmail /var/spool/masqmail/ /var/spool/masqmail/*
meillo@0: 
meillo@0: should give output similar to
meillo@0: 
meillo@165: 	-rwsr-xr-x 1 root root    399356 May 10 12:34 /usr/local/sbin/masqmail
meillo@59: 	drwxr-xr-x 2 root root      4096 May 10 12:34 /etc/masqmail
meillo@59: 	drwxr-xr-x 2 mail trusted   4096 May 10 12:34 /var/log/masqmail
meillo@59: 	drwxr-xr-x 2 mail trusted   4096 May 10 12:34 /var/run/masqmail
meillo@59: 	drwxr-xr-x 5 mail trusted   4096 May 10 12:34 /var/spool/masqmail
meillo@59: 	drwxr-xr-x 2 mail trusted   4096 May 10 12:34 /var/spool/masqmail/input
meillo@59: 	drwxr-xr-x 2 mail trusted   4096 May 10 12:34 /var/spool/masqmail/lock
meillo@59: 	drwxr-xr-x 2 mail trusted   4096 May 10 12:34 /var/spool/masqmail/popuidl
meillo@0: 
meillo@165: Important are the set-user-id bit for /usr/local/sbin/masqmail and
meillo@165: the permissions of all files.
meillo@0: 
meillo@0: 
meillo@59: 
meillo@165: Making masqmail the default
meillo@165: ---------------------------
meillo@0: 
meillo@165: `sendmail' is the de-facto standard name of the system's MTA, no
meillo@165: matter which MTA actually runs. If you want to make masqmail the
meillo@165: system's MTA (i.e. replace sendmail, postfix, etc), make a symbolic
meillo@165: link:
meillo@0: 
meillo@165: 	ln -s /usr/local/sbin/masqmail /usr/lib/sendmail
meillo@0: 
meillo@165: Now every mailer that used to call sendmail will now call masqmail.
meillo@165: If you already had an MTA installed and running, you can kill it and
meillo@165: start masqmail. Probably with:
meillo@59: 
meillo@165: 	/etc/init.d/sendmail restart
meillo@59: 
meillo@165: If this doesn't work as expected, you might need to add a special init
meillo@165: script for masqmail. Currently none is distributed with masqmail.
meillo@165: (Hopefully this will change soon.) Please ask on the mailing list for
meillo@165: help.
meillo@59: 
meillo@165: You can also directly start masqmail as daemon with:
meillo@59: 
meillo@165: 	/usr/local/sbin/masqmail -bd -q30m
meillo@59: 
meillo@59: 
meillo@59: 
meillo@165: Basic Configuration
meillo@165: -------------------
meillo@59: 
meillo@165: The only thing you must configure in order to use masqmail is the
meillo@165: hostname. It's the name under which masqmail operates. In most cases
meillo@165: it is the same as the machine's name, but it can be different.
meillo@59: 
meillo@165: The script `contrib/guess-hostname' tries to print the hostname of
meillo@165: your machine. The first output line is probably the best choice.
meillo@59: 
meillo@165: Create a minimal config with:
meillo@59: 
meillo@165: 	echo "host_name = HOSTNAME" >/etc/masqmail/masqmail.conf
meillo@59: 
meillo@165: (Substitute `HOSTNAME' with the real value, of course.)
meillo@59: 
meillo@165: Such a setup (i.e. the default one) does:
meillo@165: - deliver mail locally
meillo@165: - accept mail from local (via stdin)
meillo@165: - accept mail on localhost:25 (via SMTP)
meillo@165: It does not
meillo@165: - transfer any mail to other machines
meillo@165: - accept mail from outside your machine
meillo@59: 
meillo@59: 
meillo@165: For more elaborate setups, have a look at docs/*setup and
meillo@165: docs/INSTALL*. You can also take the example configuration files in
meillo@165: examples/ as basis for your own. Take the man pages masqmail.conf(5)
meillo@165: and masqmail.route(5) for reference.
meillo@92: 
meillo@165: All configuration files should go into /etc/masqmail.
meillo@59: 
meillo@59: 
meillo@59: 
meillo@59: Written by oku.
meillo@165: Improved by meillo.