1.1 --- a/INSTALL	Thu Jul 08 22:01:33 2010 +0200
     1.2 +++ b/INSTALL	Thu Jul 08 22:02:22 2010 +0200
     1.3 @@ -5,18 +5,26 @@
     1.4  Installation instructions
     1.5  -------------------------
     1.6  
     1.7 -To compile masqmail you need glib 1.2 (http://www.gtk.org).
     1.8 +To compile masqmail you need glib (>= 1.2) (http://www.gtk.org). Your
     1.9 +distribution probably provides it.
    1.10  
    1.11 -You need a user and a group for masqmail to run, I suggest user
    1.12 -'mail' and group 'trusted'. Say:
    1.13 +You need a user and a group for masqmail to run. If
    1.14 +
    1.15 +	grep '^mail:' /etc/passwd
    1.16 +	grep '^trusted:' /etc/group
    1.17 +
    1.18 +shows that the user `mail' and the group `trusted' exist, it's
    1.19 +probably best to use these. If they don't exist, create them:
    1.20  
    1.21  	groupadd -g 42 trusted
    1.22 -	useradd -u 42 -g 42 -d / -s /bin/sh -c "Mail Transfer Agent" mail
    1.23 +	useradd -u 23 -g 42 -d / -s /bin/sh -c "Mail Transfer Agent" mail
    1.24  
    1.25 -If you use other names than 'mail' and 'trusted' use the options
    1.26 -described below for configure. The 42 is just a suggestion, you can
    1.27 -use any number you like, but preferably one < 100. It does not have
    1.28 -to be the same for the user 'mail' and the group 'trusted'.
    1.29 +If you use other names than `mail' and `trusted' use the options
    1.30 +described below for configure. The 23 and 42 are just a suggestion,
    1.31 +you can use any (not yet used) number you like, but preferably one
    1.32 +lower than 100. It does not have to be the same for the user `mail'
    1.33 +and the group `trusted'.
    1.34 +
    1.35  
    1.36  Compliling is a matter of the usual procedure. In the source directory,
    1.37  after unpacking do:
    1.38 @@ -34,77 +42,88 @@
    1.39  
    1.40  	./configure -h
    1.41  
    1.42 -Here is additional, but maybe obsolete, explanation:
    1.43 +Here is a selection of the options with additional explanations:
    1.44  
    1.45 ---with-user=USER sets the user as which MasqMail will run. Default is
    1.46 -'mail'. USER has to exist before you 'make install'.
    1.47 +--with-user=USER
    1.48 +sets the user as which masqmail will run. Default is 'mail'. USER has
    1.49 +to exist before you 'make install'.
    1.50  
    1.51 ---with-group=GROUP sets the group as which MasqMail will run. Default
    1.52 -is 'trusted'. GROUP has to exist before you 'make install'.
    1.53 +--with-group=GROUP
    1.54 +sets the group as which masqmail will run. Default is 'trusted'. GROUP
    1.55 +has to exist before you 'make install'.
    1.56  
    1.57 ---with-logdir=LOGDIR sets the directory where MasqMail stores its log
    1.58 -files. It will be created if it does not exist. Default is /var/masqmail/.
    1.59  
    1.60 ---with-spooldir=SPOOLDIR sets the directory where MasqMail stores its
    1.61 -spool files. It will be created if it does not exist. Default is
    1.62 -/var/spool/masqmail/.
    1.63 +--with-logdir=LOGDIR
    1.64 +sets the directory where masqmail stores its log files. It will be
    1.65 +created if it does not exist. Default is /var/log/masqmail/.
    1.66  
    1.67 ---with-confdir=CONFDIR sets the default configuration directory to
    1.68 -CONFDIR, in case you prefer another location than /etc/masqmail/.
    1.69 +--with-spooldir=SPOOLDIR
    1.70 +sets the directory where masqmail stores its spool files. It will be
    1.71 +created if it does not exist. Default is /var/spool/masqmail/.
    1.72  
    1.73 ---enable-auth enables ESMTP AUTH support (disabled by default)
    1.74 +--with-confdir=CONFDIR
    1.75 +sets the default configuration directory to CONFDIR, in case you
    1.76 +prefer another location than /etc/masqmail/.
    1.77  
    1.78 ---enable-pop3 enables pop3 support (disabled by default)
    1.79  
    1.80 ---enable-maildir enables qmail style Maildir support (disabled by default)
    1.81 +--enable-auth
    1.82 +enables ESMTP AUTH support (disabled by default)
    1.83  
    1.84 ---enable-ident enable RFC 1413 support. If you have the libident
    1.85 -dynamic library installed, this will be linked, otherwise it will be
    1.86 -statically linked using the sources included in the package.
    1.87 +--enable-maildir
    1.88 +enables qmail style Maildir support (disabled by default)
    1.89  
    1.90 ---disable-resolver disable resolver support. Without the resolver functions,
    1.91 -masqmail uses only gethostbyname() to resolve DNS names, and you cannot send
    1.92 -mail without a smart host. Not recommended. You save 3K at most.
    1.93 +--enable-ident
    1.94 +enable RFC 1413 support. If you have the libident dynamic library
    1.95 +installed, this will be linked, otherwise it will be statically linked
    1.96 +using the sources included in the package.
    1.97  
    1.98 ---disable-smtp-server disable SMTP server support. You may want this if you do
    1.99 -not need masqmail to listen. In this case, you cannot use masqmail as a smart
   1.100 -host for other hosts on your LAN, you cannot use mail clients that send SMTP,
   1.101 -you cannot even use pine. In short, use of this option is discouraged unless
   1.102 -your resources are extremely limited.
   1.103 +--enable-pop3
   1.104 +enables pop3 support (disabled by default)
   1.105  
   1.106 ---with-libcryto instead of using the md5 and hmac functions within the package,
   1.107 -link dynamically with libcrypto. This applies only if you have pop3 or SMTP
   1.108 -AUTH enabled. Makes only sense if your resources are limited and you have
   1.109 -libcrypto installed. Untested.
   1.110 +--disable-resolver
   1.111 +disable resolver support. Without the resolver functions, masqmail
   1.112 +uses only gethostbyname() to resolve DNS names, and you cannot send
   1.113 +mail without a smart host. Not recommended.
   1.114  
   1.115 ---with-glib-static link with glib statically. This makes the binary larger
   1.116 -by around 30K (i386 architecture), but if masqmail is the only binary using
   1.117 -glib, you save some space in total, because you do not need the shared glib
   1.118 +--disable-smtp-server
   1.119 +disable SMTP server support. You may want this if you do not need
   1.120 +masqmail to listen. In this case, you cannot use masqmail as a smart
   1.121 +host for other hosts on your LAN, you cannot use mail clients that
   1.122 +send SMTP, you cannot even use pine. In short, use of this option is
   1.123 +discouraged unless your resources are extremely limited.
   1.124 +
   1.125 +
   1.126 +--with-libcryto
   1.127 +instead of using the md5 and hmac functions within the package, link
   1.128 +dynamically with libcrypto. This applies only if you have pop3 or SMTP
   1.129 +AUTH enabled. Makes only sense if your resources are limited and you
   1.130 +have libcrypto installed. Untested.
   1.131 +
   1.132 +--with-glib-static
   1.133 +link with glib statically. This makes the binary larger by around 30K
   1.134 +(i386 architecture), but if masqmail is the only binary using glib,
   1.135 +you save some space in total, because you do not need the shared glib
   1.136  library installed.
   1.137  
   1.138 ---disable-debug disable debugging, setting it on by command line or configuration
   1.139 -has no effect. Strongly discouraged, since you miss valuable information if something
   1.140 -goes wrong. You save 6K.
   1.141  
   1.142 -BTW, to get 3K of space, call
   1.143 -strip --remove-section=.comment --remove-section=.note --strip-unneeded src/masqmail
   1.144 +--disable-debug
   1.145 +disable debugging, setting it on by command line or configuration has
   1.146 +no effect. Strongly discouraged, since you miss valuable information
   1.147 +if something goes wrong.
   1.148  
   1.149  
   1.150  
   1.151 -after make install:
   1.152 --------------------
   1.153 -
   1.154 -You can also use these instructions to omit 'make install' if you do
   1.155 -not want to use it.
   1.156 +Checking the installation
   1.157 +-------------------------
   1.158  
   1.159  Check that 'make install' worked correctly. The following command:
   1.160  
   1.161 -	ls -ld /usr/sbin/masqmail /etc/masqmail /var/log/masqmail/ \
   1.162 +	ls -ld /usr/local/sbin/masqmail /etc/masqmail /var/log/masqmail/ \
   1.163  	       /var/run/masqmail /var/spool/masqmail/ /var/spool/masqmail/* 
   1.164  
   1.165  should give output similar to
   1.166  
   1.167 -	-rwsr-xr-x 1 root root    399356 May 10 12:34 /usr/sbin/masqmail
   1.168 +	-rwsr-xr-x 1 root root    399356 May 10 12:34 /usr/local/sbin/masqmail
   1.169  	drwxr-xr-x 2 root root      4096 May 10 12:34 /etc/masqmail
   1.170  	drwxr-xr-x 2 mail trusted   4096 May 10 12:34 /var/log/masqmail
   1.171  	drwxr-xr-x 2 mail trusted   4096 May 10 12:34 /var/run/masqmail
   1.172 @@ -113,85 +132,71 @@
   1.173  	drwxr-xr-x 2 mail trusted   4096 May 10 12:34 /var/spool/masqmail/lock
   1.174  	drwxr-xr-x 2 mail trusted   4096 May 10 12:34 /var/spool/masqmail/popuidl
   1.175  
   1.176 -(important is the set-user-id bit for /usr/sbin/masqmail and the
   1.177 -ownership of all items).
   1.178 +Important are the set-user-id bit for /usr/local/sbin/masqmail and
   1.179 +the permissions of all files.
   1.180  
   1.181 -Use the example configuration files in examples/ to edit your own. The
   1.182 -main configuration file `masqmail.conf' and the *.route and *.get files
   1.183 -should go into /etc/masqmail.
   1.184  
   1.185 -The default destination for the executable `masqmail' is /usr/sbin.
   1.186 -Check that it has the set-uid bit set. You can set it with:
   1.187  
   1.188 -	chmod u+s /usr/sbin/masqmail
   1.189 +Making masqmail the default
   1.190 +---------------------------
   1.191  
   1.192 -If you want to replace sendmail, move your old sendmail binary to
   1.193 -another name and make a symbolic link:
   1.194 +`sendmail' is the de-facto standard name of the system's MTA, no
   1.195 +matter which MTA actually runs. If you want to make masqmail the
   1.196 +system's MTA (i.e. replace sendmail, postfix, etc), make a symbolic
   1.197 +link:
   1.198  
   1.199 -	ln -s /usr/sbin/masqmail /usr/sbin/sendmail
   1.200 +	ln -s /usr/local/sbin/masqmail /usr/lib/sendmail
   1.201  
   1.202 -Now every mailer that used to call sendmail will now call masqmail. You
   1.203 -can now kill your old sendmail if it is running and start masqmail.
   1.204 +Now every mailer that used to call sendmail will now call masqmail.
   1.205 +If you already had an MTA installed and running, you can kill it and
   1.206 +start masqmail. Probably with:
   1.207  
   1.208 -	/sbin/init.d/sendmail restart
   1.209 +	/etc/init.d/sendmail restart
   1.210  
   1.211 -should do that. You can also start masqmail with:
   1.212 +If this doesn't work as expected, you might need to add a special init
   1.213 +script for masqmail. Currently none is distributed with masqmail.
   1.214 +(Hopefully this will change soon.) Please ask on the mailing list for
   1.215 +help.
   1.216  
   1.217 -	/usr/sbin/masqmail -bd -q30m
   1.218 +You can also directly start masqmail as daemon with:
   1.219  
   1.220 +	/usr/local/sbin/masqmail -bd -q30m
   1.221  
   1.222  
   1.223 -Configuring for online delivery
   1.224 --------------------------------
   1.225  
   1.226 -(This section covers dial-up internet connections.)
   1.227 +Basic Configuration
   1.228 +-------------------
   1.229  
   1.230 -Now you have to set up the online configuration. The trick is to tell
   1.231 -your ip-up script the connection name. You could use the IP number of
   1.232 -the far side of the ppp link, but this is a pain and may change each
   1.233 -time. But you can give it an additional argument via pppd with ipparam.
   1.234 -Somewhere in your dial up script you have a line similar to:
   1.235 +The only thing you must configure in order to use masqmail is the
   1.236 +hostname. It's the name under which masqmail operates. In most cases
   1.237 +it is the same as the machine's name, but it can be different.
   1.238  
   1.239 -	/usr/sbin/pppd /dev/ttyS1 connect "/usr/sbin/chat -t 90 -f $CHATFILE" \
   1.240 -	-d -d -d user user@somewhere file "$OPTIONS"
   1.241 +The script `contrib/guess-hostname' tries to print the hostname of
   1.242 +your machine. The first output line is probably the best choice.
   1.243  
   1.244 -Just add 'ipparam FastNet' in the command line for pppd if your ISP has
   1.245 -the name FastNet. The ip-up script will then get 'FastNet' as a sixth
   1.246 -parameter. In your ip-up script you can then call masqmail with
   1.247 +Create a minimal config with:
   1.248  
   1.249 -	/usr/sbin/masqmail -qo "$6"
   1.250 +	echo "host_name = HOSTNAME" >/etc/masqmail/masqmail.conf
   1.251  
   1.252 -instead of 'sendmail -q', if you had that in the script before.
   1.253 -Masqmail will then read the route configuration specified for the
   1.254 -connection name 'FastNet' and deliver the mail destined to the internet.
   1.255 -See the configuration manual on how to write a route configuration or
   1.256 -use one of the examples as a template.
   1.257 +(Substitute `HOSTNAME' with the real value, of course.)
   1.258  
   1.259 -I do not know how do configure that for an ISDN adapter, but I am sure
   1.260 -you will find something similar in the man pages.
   1.261 +Such a setup (i.e. the default one) does:
   1.262 +- deliver mail locally
   1.263 +- accept mail from local (via stdin)
   1.264 +- accept mail on localhost:25 (via SMTP)
   1.265 +It does not
   1.266 +- transfer any mail to other machines
   1.267 +- accept mail from outside your machine
   1.268  
   1.269 -If you want mail that is received by masqmail from your local net to be
   1.270 -delivered immediately using the route configuration, you have two
   1.271 -possibilities:
   1.272  
   1.273 -* if you are using the masqdialer system, you just have to set the
   1.274 -  variables online_detect to pipe and online_pipe to something like
   1.275 -	/usr/bin/mservdetect localhost 224
   1.276 -  if mserver is running on localhost and listens on port 224. See the
   1.277 -  man page to mservdetect(1).
   1.278 +For more elaborate setups, have a look at docs/*setup and
   1.279 +docs/INSTALL*. You can also take the example configuration files in
   1.280 +examples/ as basis for your own. Take the man pages masqmail.conf(5)
   1.281 +and masqmail.route(5) for reference.
   1.282  
   1.283 -* otherwise you have to add two commands in your ip-up script:
   1.284 -	echo "$6" >/var/run/masqmail/masqmail-route
   1.285 -	chmod 644 /var/run/masqmail/masqmail-route
   1.286 -  and you have to remove the file /var/run/masqmail/masqmail-route in
   1.287 -  your ip-down script:
   1.288 -	rm /var/run/masqmail/masqmail-route
   1.289 -  Then you have to set online_detect to file and online_file to
   1.290 -  /var/run/masqmail/masqmail-route
   1.291 -
   1.292 -See the route documentation for more.
   1.293 +All configuration files should go into /etc/masqmail.
   1.294  
   1.295  
   1.296  
   1.297  Written by oku.
   1.298 -Updated by meillo.
   1.299 +Improved by meillo.