              Installing the ServiceMail toolkit v2.0

This file contains detailed instructions on installing ServiceMail,
including a full description of all the configuration parameters.

OVERVIEW:
For those who hate reading installation instructions, this should
be enough to get you going, especially if your configuration is
simple.

1) edit 'conf.h' in this directory to reflect your desired
   configuration.
2) type 'make'
3) type 'make install'
4) if you're using the queueing software, start the dispatcher
   by running $(BINDIR)/restart_dequeue. You may want to add
   this to your /etc/rc.local or something.

GENERAL INFORMATION + TOUR:
The core of ServiceMail is the MIME parser and Tcl interpreter,
'mesh'. This version of ServiceMail includes extensive queueing
and traffic control facilities to minimize load on the server in
high traffic situations. If this is your situation, you will want to
install those as well. The queuing facilities are split between
a queuer 'pdinq' which logs and tags incoming messages and
a dispatcher daemon 'dspd' which arranges to execute mesh jobs.

As originally written, ServiceMail was intended to have it's
own user (canonically, services) assigned to it, and it was
arranged that mesh was run from that user's .forward file.
The current version, however, can be installed in any directory,
and aliases can be used instead of a .forward file. By default,
the .forward method is turned on and the aliases method is turned
off, but you can run either or both. (You could even run neither,
but then ServiceMail wouldn't do anything very useful.)
  
1. CONFIGURATION:
Each of the options in 'conf.h' is discussed in some detail below.
Notice that conf.h will eventually be incorporated into a Makefile,
so $(FOO) style macroes are fine, but you should be careful
about tabs and spaces. If you edit conf.h, you will have to remake
everything. To ensure this, you should make clean before you
make if you have made the distribution before.

CC -- set this to the name of the C compiler you are going to want to
  use. Any flags you want to pass should also be on this line.
  e.g. 'CC=/usr/local/bin/gcc -Wall'.
  ServiceMail is written in K&R style C, so pretty much any
  C compiler should work. It compiles fine under Sun cc. 

TOPDIR -- the directory where you wish ServiceMail to think
  of itself as living. Probably the directory in which you
  unpacked the distribution.

TMPDIR -- Where to put temporary files. On almost all systems, this
  is /tmp.

MAILER -- The full pathname (and flags, if necessary) to use for
  the mailer for outgoing mail. If you have installed Nathaniel
  Borenstein's 'metamail' package, you should have 'splitmail'
  installed and that is what ServiceMail uses by default. You can
  use sendmail, but it doesn't know anything about MIME-compliant
  message splitting, so you may have problems with very large
  messages being truncated by gateways and the like.
  
FORWARD -- Set this variable to 'forward' if you want to use
  the .forward file method of getting ServiceMail running.

ALSDIR -- In order to permit aliases to be changed by
  ServiceMail (as opposed to root), aliases should be done
  by having each alias in /etc/aliases include a file from
  some directory which is writable by ServiceMail. You'll
  have to write those lines (in /etc/aliases) as root, though,
  so this is useful mainly for traffic control. (If you're using
  queuing, you can shut down aliases and then restart them.) In
  any case, this is the directory where aliases are kept. By
  default $(TOPDIR)/aliases

SRCDIR -- where the sources live. This is normally in the
  src subdirectory of where you unpacked the distribution, and
  frankly, I don't advise changing this. I don't guarantee that
  things will compile if you do.

SERVSRC -- Where Tcl scripts go. This is nominally in src/services,
  but it can be changed by changing it here. It will get hardwired
  in by compilation, though.

TCLLIBDIR -- Where the Tcl library lives. If you have installed
  Tcl somewhere, this should be the directory where libtcl.a lives.
  If not, it should be src/mesh/tcl. (The Makefile is set up for
  that). If you have already installed Tcl, you will want to
  comment out TCLSRCDIR and TCLBUILD.

TCLSRCDIR -- Where the Tcl src lives. Likely $(SRCDIR)/mesh/tcl.

TCLBUILD -- Set this to libtcl.a

MFLAGS & FACILITY -- ServiceMail can be configured to do logging
  via BSD style syslog(3). If you want to do this, you should
  uncomment these macros, set MFLAGS to '-DUSESYSLOG' and FACILITY
  to the symbolic name of the facility you want to log as. e.g.
  LOG_LOCAL6. For more information, RTFM syslog(3).

If you want to use the queuing stuff, you will want to uncomment and
edit the stuff under 'A.' and comment out the stuff under 'B.'
Otherwise, you will want to just edit the stuff under 'B.'.

A.
SPOOLDIR -- the directory where incoming mail should be spooled
  before processing. Should have enough space to handle your backlog
  and be writable by the uid which you expect the dispatcher to
  have. If it doesn't already exist, the Makefile will try to
  make it when you 'make install', but if, like many people,
  you want to use /usr/spool/foo, it will probably fail.

SVCDIVERTDIR -- The queueing stuff includes scripts to divert
  individual services so that you can, for instance, repair bugs
  in scripts without having the outside world know that one
  of your services is down and without shutting down your entire
  server. Messages diverted in this way will go in this
  directory. (Might as well be under $(SPOOLDIR) and by default it is.)

MBXDIVERTDIR -- just like SVCDIVERTDIR but for diverted aliases.
  The makefile will try to make both of these automagically.

DSPDFLAGS -- the flags to pass when the dispatching daemon is
  started up. You should see dspd(1) for details. I have chosen
  what I think are pseudo reasonable defaults. You may disagree.

TARGETS, FIRSTPROG -- just uncomment these, like it says in 'conf.h'

USEVFORK -- On old BSD systems, fork(2) required a full copy of
  a process's memory space. vfork(2) did no memory copying and
  was therefore much faster. On some new systems (notably SunOS)
  fork() is implemented with copy-on-write and is therefore
  essentially as fast as fork(). If you are not on such a
  system, you will want to uncomment USEVFORK.

USEVFORKH -- many systems have a header file vfork.h which should
  be included when using vfork(). IF you have uncommented USEVFORK,
  and yours is such a system, uncomment this line too.

NOSIGINTERRUPT -- BSD 4.3 derived systems should have automatically
  restarted system calls. (SunOS does). If you don't, you may want to
  uncomment NOSIGINTERRUPT. Since I don't have such a system,
  it's hard to say. If you do, let me know what happens. On
  SunOS or similar BSD-derived systems, you will want
  to leave this line commented.
  
B.
FIRSTPROG, TARGETS -- don't touch these, unless you are using
queuing, in which case, you comment them out.  
  
2. INSTALLATION:

Now that you've edited conf.h, type 'make'. Then go have a cup of
coffee or something. make will recursively descend through the source
tree, (hopefully) making everything on the way, which takes a few
on a Sun 4/110, but may be faster on your machine. It will run
'config' in the Tcl src directory if you are building Tcl. You
may want to look at config first, but there aren't a lot of user
serviceable parts inside.

Once you've made the distribution, type 'make install'. This should
be pretty fast, and will copy the binaries, man pages, etc into
their appropriate places.

3. SETUP:

If you are using queueing, you will want to arrange for the
dispatcher daemon to run. You can start it by running
$(BINDIR)/restart_dequeue. You may want to arrange to have this
run in /etc/rc.local at boot time.

If you are using aliases, you will have to edit them into
the /etc/aliases file yourself. Suppose that aliases were being
written in /usr/foo/aliases, to make a mailbox called 'help', you
would put a line in /etc/aliases that said:
help: :include:/usr/foo/aliases/help

and then create a file '/usr/foo/aliases/help' which consisted
of the line: 
"|/usr/foo/bin/pdinq -d /usr/spool/servicemail"

(or one much like it. RTFM pdinq(1) for more details).

If you have enabled logging, you will want to configure your
/etc/syslog.conf so that log messages go to the right place.
RTFM syslog(3), syslog.conf(5), etc.

Other than that, you should be good to go.








  



  
    



   

