
                                 Installation

     * Upgrading from an earlier version
     * Overview
     * IMAP and Unicode
     * Spell checking
     * Authentication modules
     * Confirming selected authentication options
     * Password changes
     * Runtime configuration
     * Domain-based templates
     * Shared folders
     * LDAP address books
     * Mail Filtering
     * Calendaring
     * Encryption
     * FAQ: Unable to compile an authentication module
     * FAQ: Authentication module compiles, but code doesn't run
     * FAQ:  Problems with downloading attachments with Internet Explorer
       versions 4 and 5

Upgrading from an earlier version

   Follow  the  general  installation  instructions,  below,  in order to
   upgrade  an existing installation. You just need to make sure that the
   options  to  the  configure  script  are  the same as for the previous
   version.  You  may specify additional options as well, that are new to
   this release.

  Upgrading from versions prior to 3.0

   THIS IS A MAJOR UPGRADE

   All mail passwords must be reset when upgrading from versions prior to
   3.0.  Prior  to  3.0 SqWebMail maintained a separate password file for
   webmail  logins.  It  was  automatically  initialized  with the system
   password,  but then maintained separately. "System password" refers to
   whatever    password   authentication   was   installed:   traditional
   /etc/passwd file, or MySQL, LDAP, or several other methods.

   The separate webmail password file was needed because SqWebmail lacked
   a  convenient  way  to  update  the  system password. Starting in 3.0,
   additional  code  and  scripts  were  added  that  update  the  "real"
   password, and SqWebMail's separate password files are removed. Here is
   a suggested migration plan:

   Note:  if you were using the authvchkpw module then you're pretty much
   off  the hook. All except very old versions of SqWebMail had a special
   authvchkpw  module  that  kept SqWebMail's and vpopmail's passwords in
   sync.  Although  you're  mostly  off the hook, you should still follow
   these instructions in order to insure a smooth transition.
     * Add    the    following   options   to   the   configure   script:
       --prefix=/usr/local/share/sqwebmail3
       --with-cachedir=/var/cache/sqwebmail3  --enable-imageurl=/webmail3
       --enable-imagedir=/var/www/htdocs/webmail3
       --enable-cgibindir=/var/www/cgi-bin/sqwebmail3
       The  effect  of  these  options  is  to  install  SqWebMail3  into
       different  directories than the previous version of sqwebmail (you
       may need to use a different --enable-imagedir option that reflects
       your  web  document  root).  The  default  configuration  installs
       SqWebMail        in        /usr/local/share/sqwebmail       (using
       /var/cache/sqwebmail as the login cache, and /webmail for images).
       By  carefully  picking the options, SqWebMail 3.0 can coexist with
       an earlier version. Earlier versions of SqWebMail also installed a
       couple  of  files  in  /usr/local/libexec, SqWebMail 3.0 no longer
       does that.
     * Specify  the  same  options  to  the  configure  script  that were
       specified for the existing SqWebMail install.
     * After  compiling,  run  the  following command as a non-root user:
       make install DESTDIR=/tmp/sqwebmail3 (as always, use gmake instead
       of make on xBSD, this command is implemented by GNU make only).
     * This  essentially  installs all files in /tmp/sqwebmail3, which is
       like  a  virtual  chroot  jail: /usr/local/share/sqwebmail becomes
       /tmp/sqwebmail3/usr/local/share/sqwebmail,   etc...   Examine  the
       contents  of  the  /tmp/sqwebmail3  tree.  This  will allow you to
       confirm  that  the real make install is not going to scribble over
       any  part  of  the  existing  installation.  Examine all files and
       directories  underneath  /tmp/sqwebmail3  and verify that they are
       different from the existing install.
     * Run  make  install  for  real. Reenter all configuration data into
       version 3's configuration files, to match the existing sqwebmail's
       configuration.  Don't  forget  to start a separate copy of version
       3's  authdaemond  process,  and to set up version 3's cleanup cron
       job.  For a short period of time there will be two copies of each.
       Some careful attention will be needed to keep everything in order.
     * If  you  are  using  the authuserdb authentication module, run the
       makeuserdb  script  from  sqwebmail  3.0  to  rebuild  the  userdb
       database.
     * Create  a  test mail account (if none already exist). Log into the
       mail  account  using  the  previous  version of SqWebMail's (which
       should still be installed) password, password A.
     * Start  the  new  authdaemond process (and install version 3's cron
       job).  Reset  the test mail account's password to password B. Load
       the  URL  for  version  3's sqwebmail binary in a browser. The URL
       will  probably  be http://domain/cgi-bin/sqwebmail3/sqwebmail. Log
       into   the  test  mail  account  with  password  B.  Go  into  the
       preferences  and  change password B to password C. Log out and log
       in  using  password  C.  Now,  go  back to the existing version of
       SqWebMail  (probably http://domain/cgi-bin/sqwebmail), and observe
       that  you  will  still use password A with the existing version of
       SqWebMail, which maintains a separate password file.
     * Convince yourself that everything Is Working Right[tm].
     * Make  arrangements  to  reset  all  mail account passwords. That's
       mostly an administrative function.
     * Go  into  the  cgi-bin  directory.  Rename  the existing sqwebmail
       binary  to  sqwebmail.old, then move the new sqwebmail binary from
       the  sqwebmail3  subdirectory. Take care to preserve the ownership
       and permission settings on the binary.
     * After  everything has been running smoothly for a couple of weeks,
       blow   away   the  old  version  of  SqWebMail.  Decommission  its
       authdaemond  process, and delete its cron job. You'll have to make
       yourself  a  mental  note  to  always use the extra options to the
       configure script in order to be able to upgrade future versions of
       SqWebMail  into the same non-default installation location. That's
       not the end of the world, and if you feel comfortable knowing what
       you're  doing,  you  can  always  rerun  configure,  and reinstall
       version  3  into  the default installation location. This is up to
       you.

   NOTE:  the  default configuration settings have been changed to always
   build the authdaemon module, and build all real authentication modules
   inside  authdaemond.  This  is  true  even with the authvchkpw module.
   authdaemond  is  needed  to  support  the  new password authentication
   framework.

  Upgrading from versions prior to 1.1

   Prior  to  SqWebMail  1.1,  each  version  installed  a default set of
   configuration  files.  If some custom changes were made to an existing
   configuration, after installation those changes had to be reapplied.

   Beginning  with version 1.1 this process is mostly automated. Starting
   with  version 1.1, the configuration files contain additional metadata
   that  allow  them  to be upgraded automatically. For this to work both
   the old and the new configuration files must contain this metadata.

   Therefore,  when upgrading to version 1.1, proceed as follows. Back up
   the  existing  configuration,  then  follow  the  procedures  below to
   install  this  version. Because the existing configuration files carry
   no  auto-update  metadata,  the  installation  script will rename each
   configuration  file  "filename" to "filename.bak", and write a default
   "filename"  in  its  place.  Afterward,  edit  "filename"  and manully
   reenter   all   custom  changes.  Do  NOT  simply  copy  the  previous
   configuration   file  and  overwrite  the  new  version,  because  the
   autoupdate metadata will be lost.

   Note:  not all configuration files can be upgraded automatically. Only
   those configuration files that carry multiple settings ( authdaemonrc,
   authldaprc,  authmysqlrc,  and  ldapaddressbook)  can be automatically
   upgraded.

Overview

   The requirements to install SqWebMail are:
     * A  C++  compiler.  SqWebMail  is  written  in C but there are some
       auxiliary programs that are written in C++. gcc is recommended.
     * GNU ma ke. Th is is  th e de fault ma ke on  Linux. xBSD and other
       systems   usually   install  GNU  make  as  "gmake".  Replace  all
       references to "make" in this document to "gmake".
     * The "expect". expect is usually included with most systems. Expect
       can   be  downloaded  from  http://expect.nist.gov/  if  it's  not
       installed  on  your  system. This utility is used to change system
       login  passwords,  by  scripting the passwd command. If you do not
       have  expect installed you will not be able to change system login
       passwords  through SqWebMail. However you can still use non-system
       authentication modules (see below).
     * A  web  server.  Apache will do nicely, but so will any web server
       that fully implements the Common Gateway Interface. SqWebMail is a
       straight CGI app, and does not need any other support from the web
       server.  However,  the  web  server  must  implement  the full CGI
       interface,  since SqWebMail makes the use of pretty much every CGI
       variable in existence.
     * If   you  want  to  implement  LDAP,  PostgreSQL,  or  MySQL-based
       authentication  you  will  need  OpenLDAP,  PostgreSQL  and  MySQL
       development libraries.

   The  typical  sequence of commands to compile and install SqWebMail is
   as follows:

  ./configure [options - see below]
  make configure-check
  make
  make check
  make install-strip       # Do a make install if this doesn't work
  make install-configure   # Install configuration files.

  # Create post-install cron jobs, and modify system startup script

  # Tweak your web server for MSIE

   GNU make is required to compile and install SqWebMail. On xBSD systems
   GNU   make   is  installed  as  the  "gmake"  command.  Anywhere  this
   documentation mentions the make command, substitute gmake for make. If
   you  do  not  have  gmake on your system, install it before installing
   SqWwebMail.

   The options to the configure program are as follows:
     * --without-module  -  explicitly  disable  an authentication module
       named  "module".  Example:  --without-authpam.  See below for more
       details.
     * --disable-changepass   -  disable  the  ability  to  change  login
       passwords.   Use   this   if   you   don't  want  to  install  the
       authdaemon.passwd  suid  utility  that  is  used  to  change login
       passwords for system accounts.
     * --disable-utf7-folder-encoding  -  do  not  use  modified-UTF7  to
       encode  8-bit  characters  in  names  of  folders.  See  "IMAP and
       Unicode", below, for more information.
     * --enable-unicode=chset,chset,...  -  include the specified Unicode
       charset   mappings.  See  "IMAP  and  Unicode",  below,  for  more
       information.
     * --with-cachedir=dir,  --with-cacheowner=userid  - SqWebMail uses a
       cache  of  currently  active  logins.  SqWebMail runs for each and
       every  HTTP  request,  and  after starting, it needs to locate the
       account's  maildir.  Because hitting the authentication module can
       be  expensive  (think  MySQL/PostgreSQL/LDAP  query for every HTTP
       request!)  SqWebMail  caches  the  login  information, in order to
       avoid having your authentication server brought down to its knees.
       By     default,     the    directory    /var/cache/sqwebmail    or
       /var/run/sqwebmail  will  be  used,  owned  by the bin user. These
       options  can  be  used  to  specify  a  different location for the
       sqwebmail login cache directory.
       You  MUST  add a periodic cron job to run the cleancache.pl script
       in  order  to delete stale cache records from the cache directory.
       make  install  will display the message containing the text of the
       cron job.
     * --without-gzip  -  do  not  use gzip compression. By default, some
       pages  will be compressed with gzip before being sent by sqwebmail
       (to  browsers  that  support gzip compression). Note that this may
       result in additional load on your server, so --without-gzip can be
       used  to  turn  it  off, if necessary. The gzip program must be in
       your  default path at the time you run configure in order for gzip
       compression  to  be enabled (the absolute pathname is computed and
       used at runtime).
     * --with-db=db  -  Either  the GDBM or the DB library is required by
       SqWebMail.  The  configuration  script will check for either one's
       availability. If both are found, GDBM is selected. Use this option
       to  select the DB library instead (if you only have the DB library
       installed, this option is not required).
     * --enable-https  -  have  SqWebMail  generate https:// URLs for all
       accesses, instead of http://.
     * --enable-https=login  -  generate  a  single  https:// URL for the
       login function only. The idea is to use SSL just to send the login
       and  the  password.  In  order for this option to work the URL for
       both http:// and https:// path to SqWebMail must be identical!
     * --enable-https=auto  -  this  is now the default option. SqWebMail
       will  detect  whether  the  client  connects  via SSL, or not, and
       generate either http:// or https:// URLs, appropriately.
     * --enable-hardtimeout=seconds  -  hard session timeout interval, in
       seconds.  After  the  interval  expires, the user is automatically
       logged out.
     * --enable-softtimeout=seconds  -  soft session timeout interval, in
       seconds.  If  no  account  accesses come within the indicated time
       period, the user is automatically logged out.
     * --enable-autopurge=days   -  messages  in  the  Trash  folder  are
       automatically deleted after this time interval.
     * --enable-maxpurge=days  -  allow  users  to  specify "days" as the
       maximum interval for preserving messages in the trash.
     * --with-defaultlang=en - reserved for future use. Selects which set
       of  HTML  template files SqWebMail uses by default. Currently only
       English HTML templates are supplied.
     * --enable-cgibindir=directory  -  where  to  install  the sqwebmail
       executable  program.  This  should be your /cgi-bin directory. The
       configure script will look for a cgi-bin directory in some popular
       locations;  this  option  can  be  used to tell configure where to
       look.
     * --enable-imagedir=directory  -  where  to  install  the  icons and
       graphic  images.  This  should  be  somewhere in your web server's
       document  hierarchy.  The  configure  script searches for your web
       server's  document  directory in the usual places, this option can
       be used to tell configure where to look.
     * --enable-imageurl=URL - the URL to the directory containing images
       and icons.
     * --enable-mimetypes=filelist  -  a  colon-separated  list  of  your
       mime.types   files.   When   an   attachment   is   uploaded,  the
       corresponding  MIME  type  is  derived by searching for the file's
       extension in the mime.types file. A mime.types file normally comes
       with  Pine  or  Apache. If this option is not specified, configure
       looks  in  some  places  where  mime.types  is usually found. If a
       mime.types  file  is  found  in  any directory, it is added to the
       list.  This  is  a list of multiple files separated by a colon. If
       the  MIME type is not found in the first file, SqWebMail will look
       in the next file.
     * --enable-mimecharset=charset  - default charset= tag to stick into
       the Content-Type: header. the default is iso-8859-1.
     * --enable-lang=lang  - reserved for future. Default language of web
       pages to serve.
     * --enable-bannerprog=program  -  full  path  to  a  banner program.
       sqwebmail  replaces  the character sequence [#B#] in HTML template
       files  with  the  output  generated  by  this  program.  The first
       argument  to  the  program  will be the name of the HTML file. The
       banner program can use that to customize banner output.
       It  is  also  possible for a site to stick multiple @B tags in the
       same  HTML  page.  To  distinguish each instance follow the @B tag
       with  up  to  30  letters  or  digits,  surrounded  by braces. For
       example:  [#B#]{TOP}  and  [#B#]{BOTTOM}.  "TOP",  or "BOTTOM" (or
       anything else) will be the second argument to the banner program.
     * --with-maxargsize  =n - set maximum size of an HTTP post SqWebMail
       will  accept.  This  is, essentially, the maximum length of a text
       message (excluding any attachments) that SqWebMail will accept.
     * --with-maxformargsize=n  -  like the above, but applies to an HTTP
       multipart/formdata   post.   This  is  approximately  the  largest
       attachment that can be uploaded SqWebMail.
     * --with-maxmsgsize=n   -   maximum   size  of  messages  (including
       attachments.  Defaults  to  2097152  (two  megabytes).  Note  that
       attachments  are  base64-encoded,  which adds 25% overhead, so the
       maximum size of all attachments is really about 1.5 megabytes.
     * --with-ispell=pathname  - if configure finds ispell in the default
       path, or if you specify the full name to ispell using this option,
       users will be able to spell check their documents.
     * --without-ispell - disable spell checking.
     * --with-fcgi - enable fastcgi support (see http://www.fastcgi.com).
       Assumes  libfcgi.a  and  headers  are  in  search  path or in main
       sqwebmail  build  directory. --enable-bannerprog doesn't work with
       fcgi.
     * --with-calendarpurge=N  - if calendaring is enabled, purge expired
       calendar events after N days (default: 30).

   After  running  configure,  run  make  configure-check  to  verify the
   directories  where the CGI and the image files will be installed. make
   configure-check  prints  the directories that the configuration script
   thinks   your  web  server  is  installed.  Rerun  configure  and  use
   --enable-cgibindir and --enable-imagedir if SqWebMail guessed wrong.

   Run  make  to compile SqWebMail, and make install-strip to install the
   files.  As  mentioned  before,  use make install if make install-strip
   doesn't work.

   WARNING:  set  your  umask  to 022 before running make install or make
   install-strip.

   Before   running  make  install-strip,  verify  the  contents  of  the
   sendit.sh  script,  and  make  sure  that  your mail transfer agent is
   corrently invoked.

  Install the cleancache.pl cron job

   After installing, add a cron job that runs the cleancache.pl script at
   regular  intervals  (once an hour is fine). cleancache.pl is installed
   in  /usr/local/share/sqwebmail.  make  install  will  print additional
   information on installing the cleancache.pl script.

  Install configuration files

   Run  make install-configure to initialize certain configuration files.
   Some  SqWebMail's  configuration  files  carry  multiple configuration
   settings,  such  as  authdaemonrc,  ldapaddressbook,  and  others (see
   elsewhere  in  INSTALL  for  additional  information  regarding  these
   configuration settings).

   For each such configuration file, make install installs filename.dist.
   make  install-configure takes each filename.dist and creates filename.
   If   the  previous  filename  existed,  and  it  contained  autoupdate
   information  (SqWebMail  1.1  or  later),  the  existing configuration
   settings  will  be  preserved,  wherever possible. Older configuration
   files, that are not auto-updatable, will be renamed to filename.bak.

   During  an  autoupdate  make  install-configure  will  report  on  the
   disposition  of  each  configuration  setting. A configuration setting
   will  be  preserved as long as it is still valid in the new version of
   SqWebMail.  Obsolete configuration settings are automatically removed.
   If  a configuration setting may not be valid, it is not preserved, but
   will   revert  to  its  default  setting  from  filename.dist.  It  is
   recommended  that  the output of make install-configure be saved (make
   install-configure >upgrade.log), so that its report can be examined to
   identify any configuration settings that are flagged for manual action

  Post-install configuration

   Be  sure to read the notes below if you intend to use LDAP or vpopmail
   authentication.

   The default configuration script installs the authdaemond process that
   handles  authentication.  Add  the  following  command  to your system
   startup  scripts  so  that  the authentication process gets started at
   system boot:
/usr/local/share/sqwebmail/libexec/authlib/authdaemond start

   authdaemond  stop  should  also be executed at system shutdown, but is
   not strictly necessary.

  Tweak the web server for MSIE

   The  MSIE browser has a number of bugs in its HTTP/1.1 implementation,
   at least as of MSIE 4.x and 5.x. You must configure your web server to
   use  HTTP/1.0  when  talking  to any MSIE browser (at least until MSIE
   gets  fixed).  The  problem  has  to  do with downloading attachments.
   Apparently,  MSIE  forgets  how MIME works, when it uses HTTP/1.1. For
   the Apache server, insert the following directive in httpd.conf:
BrowserMatch "MSIE" nokeepalive downgrade-1.0 force-response-1.0

   Recent  versions  of  Apache  already  have  a similar directive for a
   specific  version  of  MSIE,  MSIE  4.0b2.  Just  replace  it  with  a
   browsermatch for any MSIE version.

  Load the login screen

   Specify the URL to the sqwebmail binary to display the login page. Try
   to  log  in  to  a test account. Review the rest of this configuration
   file in order to enable optional features that you want to use.

IMAP and Unicode

   The  option  --disable-utf7-folder-encoding  removes  some  code  from
   SqWebMail  that's  not  needed if the mail accounts are not accessible
   via  IMAP.  IMAP  encodes  names  of  folders  that  contain non-ASCII
   characters  using a scheme called "modified-UTF7". Currently, the only
   known IMAP server compatible with SqWebMail is Courier-IMAP.

   Modified-UTF7  support  involves  some overhead, so this option can be
   used  to  disable  modified-UTF7.  If there isn't going to be any IMAP
   access  to the same mail accounts, there's no need to include all this
   baggage.

   There  are  a few IMAP clients that do not use modified UTF7 to encode
   folder names. --disable-utf7-folder-encoding should be used if that is
   the  case.  It  is  currently  not  possible  to support both UTF7 and
   non-UTF7 clients at the same time.

   The  additional  overhead  in SqWebMail consists of translation tables
   that map the local character set to Unicode (from which modified UTF-7
   is derived). This is what happens unless the
   --disable-utf7-folder-encoding  option  is  used. The configure script
   takes  the  character  set  used for the HTML templates, and loads the
   Unicode mappings just for that character set. By default, SqWebMail is
   distributed  with  a  single  set  of  HTML  templates  that  use  the
   iso-8859-1  character set. If you are installing a modified derivative
   that  includes  additional  templates,  the configure will pick up any
   additional character sets used by those templates. The list of all the
   available    character    sets    can    be    found   in   the   file
   unicode/charsetlist.txt.

   You  may  observe  that  all  the  available  character  sets  will be
   compiled.  Rest  assured that only the required character sets will be
   included in the final SqWebMail executable.

   IMPORTANT: for UTF7 encoding to work correctly, it is necessary to set
   the  same  identical  character  set in all applications involved: the
   IMAP  client,  and SqWebMail. For SqWebMail, it means that the CHARSET
   file  in  the  HTML  template directory must be initialized to set the
   correct character set.

   The  option  --enable-unicode  can be used to explicitly specify which
   character  set  tables  to include, overriding the default selected by
   the  configure.  Sometimes  this  is useful when there are alternative
   encodings for the same base character set, like KOI8-R and IBM866. The
   option   "--enable-unicode=koi8-r,ibm866"   -   when  used  with  HTML
   templates  for  the koi8-r character set - allows SqWebMail to display
   ibm866-encoded E-mail using the koi8-r character set (and vice versa).
   Note,  for  this to work you will need to install a set of KOI8-R HTML
   templates. In a pinch, you can simply edit sqwebmail/html/en/CHARSET.

   NOTE:  the  utf-8  character  set MUST be specified if GnuPG 1.0.5 (or
   later)  is  used.  The  configure  script defaults to enabling unicode
   support  and adding the utf-8 character set if the script detects that
   GnuPG 1.0.5 (or later) is installed.

Spell checking

   SqWebMail  can  use  either the ispell or the aspell package for spell
   checking   messages.   Install  ispell  or  aspell  before  installing
   SqWebMail.

   NOTE:  SqWebMail  assumes that the spell checking dictionary is called
   "english".  Some  systems  use  a different name for the default spell
   checking  dictionary.  To  change  the  name  of  the  spell  checking
   dictionary  used by SqWebMail, put the name of the dictionary into the
   file /usr/local/share/sqwebmail/html/en-us/ISPELLDICT.

Authentication modules

   Authentication  modules  are responsible for taking the entered userid
   and  password, validating them, then opening the corresponding Maildir
   for the account.

   There    are    several   authentication   modules   available.   Each
   authentication  module  implements  a  separate  way of authenticating
   logins,  and  not  all  authentication  modules  can  be used on every
   system.  Some  authentication modules can be used only on systems that
   have certain libraries or software installed.

   The configure script checks the system configuration and automatically
   prepares  a  default set of authentication modules which will be used.
   The option --without-module, where "module" represents the name of the
   module,  can  be  used  to  selectively  disable  the module. However,
   there's  usually  no reason to do that. Modules can be easily disabled
   at  runtime,  by  removing  them from the authmodulelist configuration
   file,  or from the authdaemonrc file if the authdaemon module is going
   to be installed.

   Here's a brief list of the available authentication modules:
     * authpwd - authenticate against the system passwd file.
     * authshadow - use instead of authpwd on systems that use the shadow
       password file.
     * authpam  - use the PAM library for authentication. authpam MUST be
       used  instead  of  authpwd  or  authshadow on systems that use PAM
       authentication.
     * authuserdb  -  authenticate from a GDBM/DB database, maintained by
       some simple Perl script that are included with SqWebMail.
     * authmysql  -  authenticate  from an account file stored in a MySQL
       database.
     * authpgsql  -  authenticate  from  an  account  file  stored  in  a
       PostgreSQL database.
     * authldap  -  authenticate  from  an account file stored in an LDAP
       directory.
     * authvchkpw - use the vpopmail library for authenticating.
     * authdaemon - use the authdaemond authentication proxy process (see
       below).

   Most   of   these   authentication   modules   have   a  corresponding
   configuration  file  that  define various parameters (server location,
   field  names,  etc).  After  installation  you will need to open their
   configuration  files, and follow the instructions in the configuration
   file.

   Starting  with version 3.0, SqWebMail's's default configuration builds
   the   authdaemon  module,  and  puts  the  remaining  modules  in  the
   authdaemond  background daemon. authdaemond is a persistent background
   process,  that receives authentication requests from SqWebMail via the
   authdaemon module.

   Starting  with  version  3.0,  the  authdaemon  module  will always be
   installed,  unless  explicitly  disabled by the configure script. This
   greatly  simplifies  these  installation  instructions.  Additionally,
   authdaemon  is  required  in  order  to be able to change passwords in
   SqWebMail.  If  authdaemon is not installed, SqWebMail may not be able
   to  change  the  account  password,  because  that  procedure  usually
   requires  elevated  privileges  (and  SqWebMail  drops root privileges
   right away, while authdaemon retains them, in the background).

   Note  that  all  available  authentication  modules  will be compiled.
   Although it is possible to disable unwanted authentication modules via
   the  configure  script,  it  is better to disable them at runtime. The
   list   of   all   active  authentication  modules  is  read  from  the
   /usr/local/share/sqwebmail/authdaemonrc  configuration  file. Removing
   an authentication module from this configuration file disables it.

  Alternative authdaemond modules

   The  authdaemond  start is actually a script. Depending on your system
   configuration, there may be one or more different authdaemond binaries
   installed, and here's why.

   authdaemond.plain  will  include  all available authentication modules
   except for certain "heavy" authentication modules. The current list of
   "heavy" authentication modules is authldap, authpgsql and authmysql.

   If support for a "heavy" authentication module is selected, there will
   be   an   additional  binary  installed,  such  as  authdaemond.mysql,
   authdaemond.pgsql  or  authdaemond.ldap.  The authdaemond start script
   checks  if any "heavy" authentication daemon is installed, and, if so,
   runs that. Otherwise, the default authdaemond.plain binary goes in.

   This  allows an easy way to create binary SqWebMail distributions with
   and  without  LDAP, PostgreSQL or MySQL support. The distributor would
   simply   build  SqWebMail  on  a  machine  that  contains  both  LDAP,
   PostgreSQL  and  MySQL development libraries, then take everything but
   authdaemond.mysql,  authdaemond.pgsql and authdaemond.ldap and roll it
   into  the  base SqWebMail package. authdaemond.mysql authdaemond.pgsql
   and  authdaemond.ldap are rolled into separate sub-packages. Loading a
   base  package  installs  basic  system authentication services. Adding
   LDAP,  PostgreSQL,  or  MySQL  support  is  as  simple  as loading the
   corresponding sub-package.

  authpam

   This  module should be used on systems that have the PAM library. With
   this  module,  SqWebMail will use whatever PAM modules are defined for
   authenticating  the "webmail" PAM service. Essentially, authpam allows
   any PAM module to be used for authenticating SqWebMail's logins. NOTE:
   in   addition  to  including  this  module,  you  will  have  to  take
   additional,  site-specific,  steps  in  order  to  configure  your PAM
   library  for the "webmail" PAM service. The specific details regarding
   your  PAM  configuration differs from system to system, and you should
   consult  your  own  documentation.  It might be tempting to throw in a
   towel  and  use  authshadow or authpwd if you cannot figure out how to
   install  PAM  support,  however  that  is  not advisable. It is highly
   recommended to use authpam wherever the PAM library is available.

   Although  the  exact procedure to configure PAM authentication differs
   from  system  to  system,  if  you  have  the directory /etc/pam.d try
   creating the file /etc/pam.d/webmail, containing the following text:
#%PAM-1.0
auth    required  /lib/security/pam_pwdb.so shadow nullok
account required  /lib/security/pam_pwdb.so

   Your system may use the pam_unix.so module instead of pam_pwdb.so, and
   your modules may be located in a different directory.

   If  instead  of /etc/pam.d you have a global file named /etc/pam.conf,
   try appending the following lines to the end of this file:
webmail auth    required pam_pwdb.so shadow nullok
webmail account required pam_pwdb.so shadow nullok

   Again, you may have to use pam_unix.so or specify the full pathname to
   the PAM module.

   Also:  try to look at how other PAM services are set up, and duplicate
   their  configuration for the webmail service. A good example to follow
   would be the ppp service, if it exists.

  authuserdb

   This  module  uses  GDBM or DB database files, usually /etc/userdb.dat
   and  /etc/userdbshadow.dat  to  look  up  userids and passwords. These
   files  are  GDBM  or  DB database files that are loosely equivalent in
   function  to  /etc/passwd  and  /etc/shadow.  These database files are
   maintained indirectly by several Perl scripts (which are included with
   SqWebMail),  which  build these database files from a plain text file,
   usually called /etc/userdb that can be modified using any text editor,
   or  via  command  line with the aid of these Perl scripts. /etc/userdb
   may  also  be  a  subdirectory  with  multiple  text files of the same
   format,  which  are  concatenated.  This  allows creating virtual mail
   accounts  that  do  not  have a corresponding login account -- virtual
   mail  accounts  that  can  share  the  same,  reserved, system userid.
   /etc/userdb can also be used to completely supercede /etc/passwd. With
   many accounts it can be quite a drain to have to continuously linearly
   scan  /etc/passwd  in  order  to  look  up an account. Instead, a fast
   database  lookup  can  retrieve the same information from the database
   file. Read the included manual pages, starting with userdb(8) for more
   information.

   The  userdb  database  is  also supported by the maildrop mail filter,
   although  you MUST upgrade to maildrop 1.3.4 or later, in order to use
   maildrop with SqWebMail.

  authmysql

   Edit  the authmysqlrc configuration file to configure this module. For
   more information, see the file authlib/README.authmysql.html.

  authpgsql

   Edit  the  authpgsqlrc  configuration  file  to configure this module.
   PostgreSQL configuration is nearly identical to MySQL information, and
   authlib/README.authmysql.html  will  also  have additional information
   you can use.

  authdaemon

   After running make install, edit your system's startup script and have
   it run authdaemond start at system boot.

Confirming selected authentication options

   You  can  find out what authentication modules were actually used, but
   after  running  the  configure script you must also at least run make,
   and  have it succesfully complete. Running make, compiles the authinfo
   program in the authlib subdirectory. Run this program to tell you what
   authentication modules were compiled in.

   To change the list of enabled authentication modules, simply rerun the
   configurescript.

Password changes

   After installing SqWebMail be sure to test that the login password can
   be  changed through SqWebMail (ignore this if --disable-changepass was
   specified).  Be sure to change the password a couple of times, logging
   out and back in each time.

   For  the  virtual  domain  modules (authldap, authmysql, authpgsql and
   friends)  changing  the login is a no-brainer. The tricky situation is
   when   SqWebMail  uses  system  passwords  to  log  in  (the  authpwd,
   authshadow,  or  authpam authentication module). Different systems use
   different   ways  to  keep  login  passwords.  Many  systems  use  the
   traditional  /etc/passwd  and  /etc/shadow  files. Other systems use a
   binary  database;  other  systems  use  NIS.  And  on some systems the
   password  file  lookup  library  is  a  wrapper  that  goes against an
   external  LDAP  directory,  or  a database. For maximum compatibility,
   SqWebMail  changes login passwords by running the passwd command. This
   is the traditinal *nix command that changes login passwords. passwd is
   an  interactive  command. It's normally run from a terminal. SqWebMail
   uses  an  expect  script  -  as  mentioned  in  Overview  -  to answer
   interactive  prompts  from  passwd. The expect script expects to get a
   plain, garden-variety, passwd command, which acts something like this:
     # passwd
     Changing password for luser
     (current) UNIX password:         (old password typed here)
     New UNIX password:               (new password typed here)
     Retype new UNIX password:        (new password retyped here)
     passwd: all authentication tokens updated successfully
     #

   Systems that use a passwd command with very different prompts may find
   that  the  default  expect  script will fail. In which case it will be
   necessary  to  tweak  the  expect script to match the prompts from the
   system's passwd command.

   Modern  systems  use  a  passwd command that rejects "bad" passwords -
   passwords  that  are  based on dictionary words, are too short, or are
   obvious  for other reasons. When testing SqWebMail's ability to change
   system  passwords  be sure to use randomly-generated gibberish for the
   test  passwords. Otherwise, the default expect script will actually be
   working,  but you won't be the wiser. For security reasons, the actual
   messages passwd will not be shown by SqWebMail.

Runtime configuration

   There's  some  limited  amount of configuration that can be done after
   installation.  The  following  presumes that SqWebMail's configuration
   files are installed in /usr/local/share/sqwebmail (the default).

   /usr/local/share/sqwebmail/hostname - when SqWebMail is installed with
   a  basic  configuration for a single domain, SqWebMail sets the domain
   in  the  return  address  for  outgoing messages to the defined system
   hostname.  If  this file exists it will be used instead of the defined
   system hostname.

   /usr/local/share/sqwebmail/autoresponsesquota  -  the systemwide quota
   on  autoreplies,  if  autoreplies and mail filtering are enabled. This
   file contains one line: "Cnnn" or "Snnn" (or both strings, on the same
   line).  Cnnn:  allow up to #nnn autoreplies to be created. Snnn: allow
   up  to  #nnn  bytes as the total size of all autoreplies, combined. If
   both Cnnn and Snnn are specified, both quotas apply. If this file does
   not  exist,  there  is  no  limit  on  autoreplies. This quota setting
   applies  systemwide.  To  override  the quota setting for a particular
   Maildir,  create  the  autoresponsesquota  file in that Maildir (which
   takes precedence).

   /usr/local/share/sqwebmail/sendit.sh  is  a shell script that's called
   to  actually mail a message. It can be customized to do something like
   rewriting  some  of  the headers, or adding the client's IP address to
   the headers (sqwebmail does not do that by default).

   /usr/local/share/sqwebmail/nochangingfrom  -  if  this file exists (it
   can  be  a  0-length  dummy  file), SqWebMail will not allow the From:
   header to be changed, it will always have its default value.

   /usr/local/share/sqwebmail/usexsender - if this file exists (it can be
   a  0-length  dummy file), SqWebMail will attach an X-Sender: header to
   all outgoing messages. This can be used in the event you would like to
   be  able  to  modify  the From: header, yet also be able to track sent
   mail to the original account. Although your mail server should records
   the  id  of the sending user in the headers of outgoing messages, this
   is  not  possible  when  you have many virtual accounts that share the
   same system userid.

   /usr/local/share/sqwebmail/noimages  -  if  this  file  exists then no
   images  or  icons  will  be  used.  The  generated interface will be a
   text-only interface.

   /usr/local/share/sqwebmail/logindomainlist  - if this file exists then
   the login screens will include a drop-down list whose contents will be
   read  from  this  file.  This  file  should  contain  a list of E-mail
   domains,  one  per  line. It should be created if SqWebMail is used to
   provide   mail   access   for  multiple  domains.  Instead  of  typing
   "user@domain"  to  log  in, it will only be necessary to enter "user",
   and select the domain from the drop-down list.

   /usr/local/share/sqwebmail/html/LANG/footer - if this file exists, its
   contents  will  be  appended to the end of every sent message. LANG is
   the  language  code here, there can be a separate footer per installed
   language.

   /usr/local/share/sqwebmail/html/LANG/TIMEZONELIST    -   a   list   of
   alternative timezones. By default all dates and times are shown in the
   server's  default  timezone, and the dropdown list on the login screen
   can  be used to select an alternative timezone. SqWebMail comes with a
   default  alternative  timezone  list that lists only a small number of
   timezones.  Additional  timezones  can be entered into this file to be
   shown on the login screen.

Adjusting session timeouts

   A  login  session  is automatically logged out after certain period of
   inactivity.  The  timeout period defaults to 20 minutes, and is set by
   the  --enable-softtimeout  option  to the configure script. It is also
   possible  to  adjust  this  value by setting the SQWEBMAIL_TIMEOUTSOFT
   environment   variable.  For  example,  with  Apache,  by  adding  the
   following to httpd.conf:
SetEnv SQWEBMAIL_TIMEOUTSOFT 3600

   There is also a hard timeout, which logs out a session no matter what.
   The  default  of  two  hours  is changed with the --enable-hardtimeout
   option   to   the  configure  script,  and  the  SQWEBMAIL_TIMEOUTHARD
   environment variable.

   WARNING:

   The  hard timeout interval is used to calculate the maintenance of the
   login  cache  (if that option is selected). This factor is used in the
   cleancache.pl  cleanup  script,  and  changes  to  this  value must be
   coordinated  appropriately.  It  is not possible to use different hard
   timeout  values  with  the  same  login  cache  (in  different virtual
   domains,  as  described in the next session). Leisurely tinkering with
   this  environment  variable is STRONGLY DISCOURAGED, it's very easy to
   screw up the whole system. You've been warned.

   If  you  adjust  the hard timeout, you must simultaneously delete your
   current   login  cache  directory,  and  adjust  $timeouthard  in  the
   installed cleancache.pl script.

Domain-based templates

   The  default  set  of  templates for the dynamically generated HTML is
   installed  in /usr/local/share/sqwebmail/html. When the same server is
   used  to provide webmail access for multiple domains it is possible to
   specify a different set of HTML templates for each domain.

   This  functionality  is  not directly implemented in SqWebMail, simply
   because  there  is  no  standard way to specify this. Instead, this is
   something that will need some minor work set up.

   Domain-based  templates  are  implemented by making the web server set
   the  environment  variables SQWEBMAIL_TEMPLATEDIR prior to running the
   sqwebmail  binary.  The contents of this environment variable override
   the default location of /usr/local/share/sqwebmail/html. By having the
   web  server  initialize  this  variable based on the domain name it is
   possible  to  present  different  templates,  based on the domain name
   used.

   To   do   this,   make   copies   of   the  HTML  template  directory,
   /usr/local/share/sqwebmail/html.  Then,  configure  the  web server to
   initialize  SQWEBMAIL_TEMPLATEDIR  appropriately.  For  example,  with
   Apache:
  <VirtualHost a.b.c.d>
    ServerName webmail.example.com
    [...]
    SetEnv SQWEBMAIL_TEMPLATEDIR /usr/local/share/webmail/webmail.example.com
    [...]
  </VirtualHost>

   The possibilities are endless.

Shared folders

   SqWebMail supports shared folders. The SqWebMail distribution includes
   an enhanced maildirmake command that created shared folders.

   The maildirmake command will be installed in
   /usr/local/libexec/sqwebmail  by  default, and the manual page will be
   installed in /usr/local/share/sqwebmail/man by default.

   See  the  manual  page  for  more  information on how to set up shared
   folders.

LDAP address books

   SqWebMail  can  import E-mail addresses from public LDAP address books
   into  an  individual  address  book.  A  default  systemwide  list  of
   accessible LDAP address books is defined for everyone, and individuals
   can configure additional LDAP address books for themselves.

   OpenLDAP  runtime  libraries and tools are required to be installed in
   order  to  search  LDAP  address  books.  It  is not necessary to have
   OpenLDAP  development  libraries  installed. SqWebMail simply runs the
   ldapsearch tool to query LDAP address books, and parses the results.

   The  file  /usr/local/share/sqwebmail/ldapaddressbook should contain a
   default  systemwide  list  of  accessible address book. A default file
   will  be  installed,  listing some common Internet address books. Each
   line in this file contains the following information:
name<tab>host<tab>port<tab>suffix<tab>binddn<tab>bindpw

   <tab> is a single ASCII TAB character.

   The  file  /usr/local/share/sqwebmail/ldapsearch  is  a  wrapper shell
   script  that  calls  the  ldapsearch  tool.  The  configuration script
   attempts  to  find the location of where OpenLDAP tools are installed.
   The  path  to  ldapsearch in this shells script should be verified and
   fixed,  if  necessary.  The  default shell script adds some additional
   options  to  ldapsearch to limit the search time to sixty seconds, and
   to return a maximum of twenty entries from the address book.

Mail Filtering

   Mail   filtering   is  an  optional  feature.  Mail  filtering  allows
   installation  of  rules  that  either  automatically  deliver incoming
   messages  to  specific folders, forward it, or reject it, based on the
   contents  of the message's header or body. A simple autoreply function
   is  also  available.  Mail  filtering  requires that the maildrop mail
   filter  must  be  installed  as  the  local  mail delivery agent. Mail
   filtering  requires  maildrop version 1.3.4, or higher. SqWebMail will
   generate  a filtering recipe for maildrop to use when delivering mail.
   Maildrop's mail filtering language is very powerful, and SqWebMail can
   reasonably  use  only  a  fraction of the mail filtering language, but
   enough  functionality  is supported for the majority if mail filtering
   needs.

   For  information  on installing and activating mail filtering, see the
   file maildir/README.maildirfilter.html.

  Autoreplies

   The  mail  filtering  option  can  also be used to set up autoreplies.
   Autoreplies  are  prepared in advance on a separate screen. By default
   there  is  no  limit on the number of the size of created autoreplies,
   therefore  it is recommended that a quota be set up on the autoreplies
   (see "Runtime Configuration").

   Autoreplies  can  include  any  valid MIME content (MIME content other
   than  plain  text  can  be  uploaded). The following special procedure
   needs  to be used to prepare multipart autoreply content, such as text
   and html alternatives of the same message:

   Assign  a  filename  extension to the message/rfc822 MIME content. For
   example,  edit your mime.types file, find the message/rfc822 MIME type
   (append  one  if it's not in mime.types), and make sure that it has at
   least one filename extension, such as "msg".

   Prepare  the  multipart  MIME autoreply. The most convenient way is to
   prepare  a  normal  E-mail message using a conventional E-mail client.
   Save  the  RFC822-formatted message in a file with a ".msg" extension,
   and upload it on the autoreply screen.

   SqWebMail  handles  uploaded  message/rfc822  content  by removing all
   headers except the MIME headers, leaving the MIME content type header,
   and the actual MIME content.

Calendaring

   This  release  of  SqWebMail  contains  a beta implementation of basic
   calendaring, that can be optionally enabled. For more information, see
   the  file  pcp/README.html.  SqWebMail's calendaring implementation is
   designed  to  be used on a private mail server. It is not suitable for
   use  on  public  webmail  servers.  See the README file for additional
   information.

Encryption

   SqWebMail  can  be set up to encrypt and decrypt mail using GnuPG. For
   more  information  on  setting  up and using encryption, read the file
   gpglib/README.html in the source distribution.

FAQ: Unable to compile an authentication module

   See  http://www.courier-mta.org/FAQ.html#authlib  for  a more thorough
   description   of  authentication  modules,  and  some  suggestions  on
   troubleshooting the most common problems.

FAQ: Authentication module compiles, but code doesn't run

   Sometimes,  on  certain  oddball  operating systems, like Solaris, the
   procedures in the previous section may get the code to compile, but it
   fails to run, with increasingly bizarre error messages.

   This happens when the operating system also looks only in the standard
   directories  to  locate runtime libraries. Even though it was possible
   to  link  against  a  shared  library  in /usr/local/openldap/lib, the
   operating  system is only smart enough to search /lib and /usr/lib for
   runtime libraries.

   Your compiler may have additional options that hardcode shared library
   pathname  in  the  executable. Consult your compiler documentation for
   more information. If you are unable to determine whether those options
   are  available,  your  only  remaining  option is to move any required
   libraries  to  /usr/lib,  or  create  soft  links in /usr/lib for each
   affected library.

FAQ: Problems with downloading attachments with Internet Explorer versions 4
and 5

   Certain versions of Microsoft Internet Explorer have a bug in HTTP/1.1
   protocol  implementation  that  results in MSIE reporting random weird
   errors when downloading attachments.

   Here's how to tweak Apache to work around this particular bug. Add the
   following   directive  to  Apache's  httpd.conf  forces  the  HTTP/1.0
   protocol response for Internet Explorer clients:
BrowserMatch "MSIE [45]" nokeepalive downgrade-1.0 force-response-1.0
