# HG changeset patch # User meillo@marmaro.de # Date 1278619342 -7200 # Node ID f72de1e00fa52e5cb1935b191e207cf199eed5f7 # Parent 5b621742b2e76530b76f998b03ab048d45beabc7 updated and improved INSTALL diff -r 5b621742b2e7 -r f72de1e00fa5 INSTALL --- a/INSTALL Thu Jul 08 22:01:33 2010 +0200 +++ b/INSTALL Thu Jul 08 22:02:22 2010 +0200 @@ -5,18 +5,26 @@ Installation instructions ------------------------- -To compile masqmail you need glib 1.2 (http://www.gtk.org). +To compile masqmail you need glib (>= 1.2) (http://www.gtk.org). Your +distribution probably provides it. -You need a user and a group for masqmail to run, I suggest user -'mail' and group 'trusted'. Say: +You need a user and a group for masqmail to run. If + + grep '^mail:' /etc/passwd + grep '^trusted:' /etc/group + +shows that the user `mail' and the group `trusted' exist, it's +probably best to use these. If they don't exist, create them: groupadd -g 42 trusted - useradd -u 42 -g 42 -d / -s /bin/sh -c "Mail Transfer Agent" mail + useradd -u 23 -g 42 -d / -s /bin/sh -c "Mail Transfer Agent" mail -If you use other names than 'mail' and 'trusted' use the options -described below for configure. The 42 is just a suggestion, you can -use any number you like, but preferably one < 100. It does not have -to be the same for the user 'mail' and the group 'trusted'. +If you use other names than `mail' and `trusted' use the options +described below for configure. The 23 and 42 are just a suggestion, +you can use any (not yet used) number you like, but preferably one +lower than 100. It does not have to be the same for the user `mail' +and the group `trusted'. + Compliling is a matter of the usual procedure. In the source directory, after unpacking do: @@ -34,77 +42,88 @@ ./configure -h -Here is additional, but maybe obsolete, explanation: +Here is a selection of the options with additional explanations: ---with-user=USER sets the user as which MasqMail will run. Default is -'mail'. USER has to exist before you 'make install'. +--with-user=USER +sets the user as which masqmail will run. Default is 'mail'. USER has +to exist before you 'make install'. ---with-group=GROUP sets the group as which MasqMail will run. Default -is 'trusted'. GROUP has to exist before you 'make install'. +--with-group=GROUP +sets the group as which masqmail will run. Default is 'trusted'. GROUP +has to exist before you 'make install'. ---with-logdir=LOGDIR sets the directory where MasqMail stores its log -files. It will be created if it does not exist. Default is /var/masqmail/. ---with-spooldir=SPOOLDIR sets the directory where MasqMail stores its -spool files. It will be created if it does not exist. Default is -/var/spool/masqmail/. +--with-logdir=LOGDIR +sets the directory where masqmail stores its log files. It will be +created if it does not exist. Default is /var/log/masqmail/. ---with-confdir=CONFDIR sets the default configuration directory to -CONFDIR, in case you prefer another location than /etc/masqmail/. +--with-spooldir=SPOOLDIR +sets the directory where masqmail stores its spool files. It will be +created if it does not exist. Default is /var/spool/masqmail/. ---enable-auth enables ESMTP AUTH support (disabled by default) +--with-confdir=CONFDIR +sets the default configuration directory to CONFDIR, in case you +prefer another location than /etc/masqmail/. ---enable-pop3 enables pop3 support (disabled by default) ---enable-maildir enables qmail style Maildir support (disabled by default) +--enable-auth +enables ESMTP AUTH support (disabled by default) ---enable-ident enable RFC 1413 support. If you have the libident -dynamic library installed, this will be linked, otherwise it will be -statically linked using the sources included in the package. +--enable-maildir +enables qmail style Maildir support (disabled by default) ---disable-resolver disable resolver support. Without the resolver functions, -masqmail uses only gethostbyname() to resolve DNS names, and you cannot send -mail without a smart host. Not recommended. You save 3K at most. +--enable-ident +enable RFC 1413 support. If you have the libident dynamic library +installed, this will be linked, otherwise it will be statically linked +using the sources included in the package. ---disable-smtp-server disable SMTP server support. You may want this if you do -not need masqmail to listen. In this case, you cannot use masqmail as a smart -host for other hosts on your LAN, you cannot use mail clients that send SMTP, -you cannot even use pine. In short, use of this option is discouraged unless -your resources are extremely limited. +--enable-pop3 +enables pop3 support (disabled by default) ---with-libcryto instead of using the md5 and hmac functions within the package, -link dynamically with libcrypto. This applies only if you have pop3 or SMTP -AUTH enabled. Makes only sense if your resources are limited and you have -libcrypto installed. Untested. +--disable-resolver +disable resolver support. Without the resolver functions, masqmail +uses only gethostbyname() to resolve DNS names, and you cannot send +mail without a smart host. Not recommended. ---with-glib-static link with glib statically. This makes the binary larger -by around 30K (i386 architecture), but if masqmail is the only binary using -glib, you save some space in total, because you do not need the shared glib +--disable-smtp-server +disable SMTP server support. You may want this if you do not need +masqmail to listen. In this case, you cannot use masqmail as a smart +host for other hosts on your LAN, you cannot use mail clients that +send SMTP, you cannot even use pine. In short, use of this option is +discouraged unless your resources are extremely limited. + + +--with-libcryto +instead of using the md5 and hmac functions within the package, link +dynamically with libcrypto. This applies only if you have pop3 or SMTP +AUTH enabled. Makes only sense if your resources are limited and you +have libcrypto installed. Untested. + +--with-glib-static +link with glib statically. This makes the binary larger by around 30K +(i386 architecture), but if masqmail is the only binary using glib, +you save some space in total, because you do not need the shared glib library installed. ---disable-debug disable debugging, setting it on by command line or configuration -has no effect. Strongly discouraged, since you miss valuable information if something -goes wrong. You save 6K. -BTW, to get 3K of space, call -strip --remove-section=.comment --remove-section=.note --strip-unneeded src/masqmail +--disable-debug +disable debugging, setting it on by command line or configuration has +no effect. Strongly discouraged, since you miss valuable information +if something goes wrong. -after make install: -------------------- - -You can also use these instructions to omit 'make install' if you do -not want to use it. +Checking the installation +------------------------- Check that 'make install' worked correctly. The following command: - ls -ld /usr/sbin/masqmail /etc/masqmail /var/log/masqmail/ \ + ls -ld /usr/local/sbin/masqmail /etc/masqmail /var/log/masqmail/ \ /var/run/masqmail /var/spool/masqmail/ /var/spool/masqmail/* should give output similar to - -rwsr-xr-x 1 root root 399356 May 10 12:34 /usr/sbin/masqmail + -rwsr-xr-x 1 root root 399356 May 10 12:34 /usr/local/sbin/masqmail drwxr-xr-x 2 root root 4096 May 10 12:34 /etc/masqmail drwxr-xr-x 2 mail trusted 4096 May 10 12:34 /var/log/masqmail drwxr-xr-x 2 mail trusted 4096 May 10 12:34 /var/run/masqmail @@ -113,85 +132,71 @@ drwxr-xr-x 2 mail trusted 4096 May 10 12:34 /var/spool/masqmail/lock drwxr-xr-x 2 mail trusted 4096 May 10 12:34 /var/spool/masqmail/popuidl -(important is the set-user-id bit for /usr/sbin/masqmail and the -ownership of all items). +Important are the set-user-id bit for /usr/local/sbin/masqmail and +the permissions of all files. -Use the example configuration files in examples/ to edit your own. The -main configuration file `masqmail.conf' and the *.route and *.get files -should go into /etc/masqmail. -The default destination for the executable `masqmail' is /usr/sbin. -Check that it has the set-uid bit set. You can set it with: - chmod u+s /usr/sbin/masqmail +Making masqmail the default +--------------------------- -If you want to replace sendmail, move your old sendmail binary to -another name and make a symbolic link: +`sendmail' is the de-facto standard name of the system's MTA, no +matter which MTA actually runs. If you want to make masqmail the +system's MTA (i.e. replace sendmail, postfix, etc), make a symbolic +link: - ln -s /usr/sbin/masqmail /usr/sbin/sendmail + ln -s /usr/local/sbin/masqmail /usr/lib/sendmail -Now every mailer that used to call sendmail will now call masqmail. You -can now kill your old sendmail if it is running and start masqmail. +Now every mailer that used to call sendmail will now call masqmail. +If you already had an MTA installed and running, you can kill it and +start masqmail. Probably with: - /sbin/init.d/sendmail restart + /etc/init.d/sendmail restart -should do that. You can also start masqmail with: +If this doesn't work as expected, you might need to add a special init +script for masqmail. Currently none is distributed with masqmail. +(Hopefully this will change soon.) Please ask on the mailing list for +help. - /usr/sbin/masqmail -bd -q30m +You can also directly start masqmail as daemon with: + /usr/local/sbin/masqmail -bd -q30m -Configuring for online delivery -------------------------------- -(This section covers dial-up internet connections.) +Basic Configuration +------------------- -Now you have to set up the online configuration. The trick is to tell -your ip-up script the connection name. You could use the IP number of -the far side of the ppp link, but this is a pain and may change each -time. But you can give it an additional argument via pppd with ipparam. -Somewhere in your dial up script you have a line similar to: +The only thing you must configure in order to use masqmail is the +hostname. It's the name under which masqmail operates. In most cases +it is the same as the machine's name, but it can be different. - /usr/sbin/pppd /dev/ttyS1 connect "/usr/sbin/chat -t 90 -f $CHATFILE" \ - -d -d -d user user@somewhere file "$OPTIONS" +The script `contrib/guess-hostname' tries to print the hostname of +your machine. The first output line is probably the best choice. -Just add 'ipparam FastNet' in the command line for pppd if your ISP has -the name FastNet. The ip-up script will then get 'FastNet' as a sixth -parameter. In your ip-up script you can then call masqmail with +Create a minimal config with: - /usr/sbin/masqmail -qo "$6" + echo "host_name = HOSTNAME" >/etc/masqmail/masqmail.conf -instead of 'sendmail -q', if you had that in the script before. -Masqmail will then read the route configuration specified for the -connection name 'FastNet' and deliver the mail destined to the internet. -See the configuration manual on how to write a route configuration or -use one of the examples as a template. +(Substitute `HOSTNAME' with the real value, of course.) -I do not know how do configure that for an ISDN adapter, but I am sure -you will find something similar in the man pages. +Such a setup (i.e. the default one) does: +- deliver mail locally +- accept mail from local (via stdin) +- accept mail on localhost:25 (via SMTP) +It does not +- transfer any mail to other machines +- accept mail from outside your machine -If you want mail that is received by masqmail from your local net to be -delivered immediately using the route configuration, you have two -possibilities: -* if you are using the masqdialer system, you just have to set the - variables online_detect to pipe and online_pipe to something like - /usr/bin/mservdetect localhost 224 - if mserver is running on localhost and listens on port 224. See the - man page to mservdetect(1). +For more elaborate setups, have a look at docs/*setup and +docs/INSTALL*. You can also take the example configuration files in +examples/ as basis for your own. Take the man pages masqmail.conf(5) +and masqmail.route(5) for reference. -* otherwise you have to add two commands in your ip-up script: - echo "$6" >/var/run/masqmail/masqmail-route - chmod 644 /var/run/masqmail/masqmail-route - and you have to remove the file /var/run/masqmail/masqmail-route in - your ip-down script: - rm /var/run/masqmail/masqmail-route - Then you have to set online_detect to file and online_file to - /var/run/masqmail/masqmail-route - -See the route documentation for more. +All configuration files should go into /etc/masqmail. Written by oku. -Updated by meillo. +Improved by meillo.