                                  Installation

     • Installation
     • Upgrading from an earlier version
     • Manual compilation and installation
     • Spell checking
     • PAM authentication
     • Password changes
     • Runtime configuration
     • Account initialization hook
     • Adjusting session timeouts
     • Adjusting maximum message size
     • Random seed
     • Domain-based templates
     • Name-based templates
     • Shared folders
     • LDAP address books
     • Mail Filtering
     • Calendaring
     • Encryption

Installation

  rpm and deb packages

   These are not the same packages as the ones from various distributions'
   repositories. These packages carry a higher internal revision level in
   order to prevent them from getting upgraded by the distribution packaging,
   and their installation layout may differ from the distributions' preferred
   package installation layout. This packaging exists in order to have a
   convenient way of updating after a release without waiting for the
   distribution's package to get built, and to have a better correspondence
   with the documentation.

   NOTE: If a distribution package is already installed it should be removed
   completely before switching to the upstream version (dnf remove or apt
   purge). Preserve any existing configuration files, beforehand, in order to
   restore it after switching packages. This applies to all Courier packages.
   A switch to this courier-imap package requires switching the
   courier-unicode and courier-authlib packages too.

   NOTE: These packages use their own, generic, installation layout that may
   deviate slightly from the package installation conventions preferred by
   the distributions.

  rpm

   Run dnf install rpm-build if it's not installed already, then:

 rpmbuild -ta sqwebmail-VERSION.tar.bz2

   If this fails due to any missing dependencies, install them.

   This ends up building an sqwebmail binary rpm and an sqwebmail-ldap rpm
   with an additional LDAP dependency (for the LDAP address book hook
   described below). The sqwebmail binary rpm installs the sqwebmail binary
   directly into Apache's cgi-bin directory, and after a "systemctl enable
   sqwebmail" and "systemctl start sqwebmail" the webmail server's URL is
   http(s)?://server/cgi-bin/sqwebmail, with its images installed in
   http(s)?://server/webmail.

  deb

   Run "apt install devscripts debhelper", if they're not installed already.
   Create an empty directory and copy/move the tarball into it:

 $ mkdir tmp
 $ mv sqwebmail-VERSION.tar.bz2 tmp
 $ cd tmp

   Unpack the tarball and cd into the unpacked subdirectory:

 $ tar xvf sqwebmail-VERSION.tar.bz2
 $ cd sqwebmail-VERSION

   Run the courier-debuild script, this is a wrapper for debuild, and it
   forwards its parameters to it:

 $ ./courier-debuild -us -uc

   NOTE: the above steps must be followed strictly. The courier-debuild
   script expects the distributed tarball in its parent directory.

 $ DEBGCC=10 ./courier-debuild -us -uc

   Setting the DEBGCC environment variable selects a non-default gcc version.

   NOTE: all Courier packages should be built using the same version of gcc.

   This ends up producing the sqwebmail binary deb, an sqwebmail-ldap deb
   with an additional LDAP dependency (for the LDAP address book hook
   described below), and an sqwebmail-apache2 deb that provides an apache2
   configuration for sqwebmail. After installing it: "a2enmod alias",
   "a2enmod cgi" and "a2enmod sqwebmail" enables the webmail server by
   configuring Apache to redirect the URL http(s)://server/sqwebmail to the
   webmail server. The http(s)://server/sqwebmail-images URL also gets
   redirected internally to the webmail server's UI images.

  Maintainer Mode (see README in the git repository to set up)

   make rpm or make deb, as appropriate, will:

    1. Increment an internal release number.

    2. Run make dist.

    3. Proceed and build a new release, creating the native packages in the
       rpm or deb subdirectory.

  Manual installation

   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.
     • Version 2 of the PCRE library (pcre2).
     • GNU make. This is the default make on Linux. xBSD and other systems
       usually install GNU make as "gmake". Replace all references to "make"
       in this document to "gmake".
     • The GNU IDN library (https://www.gnu.org/software/libidn/).
     • 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.
     • Courier Unicode Library. Before installing SqWebMail, download and
       install http://www.courier-mta.org/unicode/.
     • The Courier authentication library. Before installing SqWebMail,
       download and install http://www.courier-mta.org/authlib/.

   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

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 6.0.0

   SqWebMail 6.0.0 update is coordinated with the Courier-IMAP update to
   Courier-IMAP version 5.0, which added native IMAP UTF8 (Unicode) support
   and switched to using Unicode for folder names. An update to SqWebMail 6
   requires a concurrent upgrade to Courier-IMAP 5, and a one-time conversion
   of all existing mail folders. See the maildirmake(1) manual page for more
   information.

  Upgrading from versions prior to 5.7.3

   Building SqWebMail now requires the Courier Unicode Library to be
   installed first.

  Upgrading from versions prior to 5.4

   Building SqWebMail now requires the The GNU IDN library.

  Upgrading from versions prior to 5.1

   SqWebMail now requires the PCRE library to compile. Additionally, if using
   maildrop, maildrop must be upgraded to version 2.0.

   Version 2.0 of maildrop now uses the PCRE for pattern matching (PCRE is
   still required to compile SqWebMail even if maildrop is not used), and
   it's possible that some arkane existing pattern is no longer valid under
   maildrop 2.0. What will happen is that the first time SqWebMail's mail
   filtering screen is opened, the non-compatible filtering rules will be
   quietly deleted. This is a necessary even, and must be done, and the
   updated filtering rules must be saved, in order to enable mail delivery to
   this account.

  Upgrating from versions prior to 5.0

   There are two major changes in version 5.0. Starting with 5.0, the
   authentication library that used to be a part of SqWebMail's source has
   been spun off into a standalone authentication library.

   You must download and install the Courier authentication library from
   http://www.courier-mta.org/download.php#authlib before upgrading. Review
   the documentation in the courier-authlib package for more information.

   The second major change is that the default installation directories for
   SqWebMail have been changed. SqWebMail's default installation is now more
   closely aligned with standard installation directories used by many other
   packages based on the GNU toolchain.

   Earlier versions of SqWebMail preferred to be installed in
   /usr/local/share/sqwebmail, with various bits and pieces scattered
   elsewhere.

   Now, SqWebMail's installation layout follows the standards much closer.
   SqWebMail now implements the usual configuration directives: --prefix,
   --exec-prefix, --bindir, --datadir, and all the rest. There's only one
   non-standard default: unless the --prefix option is specified, SqWebMail
   will be install in /usr/lib/sqwebmail. That's the default installation
   tree.

   Use the following procedure to upgrade the current installation of
   SqWebMail:

   If you're using a package manager, such as RPM or APT, build a new
   package, and let the package manager figure out what to do. Only one
   manual step may be required, which the package manager probably won't be
   able to handle on its own: there might be some left-over custom
   configuration files in /usr/local/share/sqwebmail. Review the old
   configuration files, and re-apply any custom changes to the new version's
   configuration file (which will be in /usr/lib/sqwebmail/etc, or wherever
   your --sysconfdir option places them). DO NOT just copy the configuration
   file verbatim. Manually re-apply changes, one at a time.

   Otherwise: install the authentication library first. Make sure it is
   working. Use the authtest program to verify that the authentication
   library is seeing the existing mail accounts.

   Download the new version of SqWebMail, and extract the source code into a
   new directory. Follow the regular installation instructions up until the
   "make install" command.

   Don't run the "make install" command. Switch to the directory with the old
   SqWebMail's source code, and run "make uninstall" to remove the old
   version of SqWebMail. Go back to the new source code, then run "make
   install", then "make install-configure".

   After upgrading, check SqWebMail's older installation directory (usually
   /usr/local/share/sqwebmail). It'll probably still have some left-over
   configuration files. Start the new version of SqWebMail, verify that it's
   working, then nuke /usr/local/share/sqwebmail in order to avoid any future
   confusion.

  Upgrading from versions prior to 4.1

   In 4.1, the sqwebmaild, authdaemond and pcpd processes all run in the
   foreground; they are daemonized by running them under the control of a
   'courierlogger' process, which also captures their stderr output and sends
   it to syslog. The script sqwebmaild.rc takes care of this for you. After
   upgrading to 4.1 you will need to modify your system startup script to run
   sqwebmaild.rc start and not to run sqwebmaild start or authdaemond start.
   See below for more information.

   Additional authentication debugging capabilities have been added. See
   authlib/README.authdebug.html for more information.

   A new configuration file, /usr/local/share/sqwebmail/sqwebmaild has been
   added. Make sure you run make install-configure to create the initial
   version of this file.

  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" here 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 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.
     • Run the new sqwebmaild.rc start script (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.
     • 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.

Manual compilation and installation

   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:

     • --with-libcharset - use the GNU libcharset library, if installed. Some
       systems do not implement the nl_langinfo(CODESET) system call, which
       determines the character set used by system messages. If SqWebMail
       cannot determine the system character set then some items may not be
       displayed in the correct character set. One example would be the
       message date times, which use the system strftime() function. Some
       systems nl_langingo(CODESET) may be available, but may not return the
       preferred or the correct MIME character set name. Both problems may be
       fixed by installing the GNU libcharset library, and using the option
       to compile the support for it.
     • --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 CGI
       stub. 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 utf-8.
     • --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. This setting
       can also be adjusted at runtime. See Adjusting maximum message size,
       below.
     • --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. This setting can also be adjusted at
       runtime. See Adjusting maximum message size, below.
     • --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. This setting can also be
       adjusted at runtime. See Adjusting maximum message size, below.
     • --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.
     • --disable-autorenamesent - do not rename the Sent folder every month.
       This option can also be controlled by the SQWEBMAIL_AUTORENAMESENT
       environment variable (which can be set in Apache's httpd.conf, for
       example). This setting gives the initial configuration, that can be
       individually adjusted in the Preferences screen.
     • --with-calendarpurge=N - if calendaring is enabled, purge expired
       calendar events after N days (default: 30).
     • --with-trashquota - include deleted messages, and the Trash folder, in
       the estimated quota usage for maildirs. Quotas are optional, see the
       file maildir/README.maildirquota.html for more information. The
       default configuration does not count messages marked as deleted (but
       not yet expunged) and the contents of the Trash folder (which are
       automatically purged by the server) against the quota usage.
     • --with-syslog=DEST - select syslog destination, giving one of the
       facility codes from syslog.h such as "LOCAL7". Defaults to "MAIL".

   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-stripto 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.

  Modify your system startup script

   The following command starts sqwebmail. This command should be added to
   the system startup script so that sqwebmail automatically starts during
   the system boot.

   /usr/lib/sqwebmail/libexec/sqwebmaild.rc start

   "sqwebmaild.rc stop" may also be used to shut down the webmail service.

  SELinux

   The following extension may be necessary to make SqWebMail work when
   SELinux kernel extensions are turned on:

 allow httpd_sys_script_t var_t:sock_file write;
 allow httpd_sys_script_t unconfined_t:unix_stream_socket connectto;

  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/lib/sqwebmail/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

   The default configuration script installs the authdaemond process that
   handles authentication, and it is started by sqwebmaild.rc start

   sqwebmaild.rc 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.

Spell checking

   The configure script checks if the hunspell, ispell, or aspell package is
   installed, to use for spell-checking messages. --without-spellcheck
   disables spell checking. --with-spellcheck=hunspell,
   --with-spellcheck=aspell, or --with-spellcheck=ispell directly selects a
   specific spell checking package when two or more are available. Install
   hunspell, ispell or aspell before installing SqWebMail.

   NOTE: SqWebMail assumes that the spell checking dictionary is called
   "english", with ispell or aspell, and "en_US" for hunspell. 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/lib/sqwebmail/share/sqwebmail/html/en-us/ISPELLDICT.

PAM authentication

   SqWebMail uses the "webmail" service with the Courier authentication
   library. When the optional groupware calendaring mode is enabled,
   SqWebMail also uses the "calendar" service. You will have to take
   additional, site-specific, steps in order to configure your PAM library
   for the "webmail" and "calendar" PAM services. The specific details
   regarding your PAM configuration differs from system to system, and you
   should consult your own documentation.

   See the Courier authentication library documentation for more PAM-related
   information.

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

Password changes

   After installing SqWebMail be sure to test that the login password can be
   changed through SqWebMail. Be sure to change the password a couple of
   times, logging out and back in each time.

   If you do not want to use the password change function you can also remove
   the sqwebpasswd program. This is a helper program, installed with the
   set-groupid bit set, that relays the password change request to the
   authentication daemon, through the filesystem socket that is not globally
   accessible. The password change request consists of the account name, the
   old password, and the new password. The password change request is
   validated by the authentication daemon, and the old password must match
   the existing password on the account, before the password change goes
   through. This set-groupid helper program is safe to use.

Runtime configuration

   There are some options which can be used to change sqwebmail's behaviour
   on individual accounts, or globally, using the "Account Options" feature
   in the Courier Authentication library. The individual account's setting
   takes precedence over the DEFAULTOPTIONS settings in the authdaemonrc
   configuration, so for example if you want to disable webmail access for
   most accounts but enable it for a select few, you can set
   DEFAULTOPTIONS="disablewebmail=1" in the authdaemonrc configuration file,
   and add the option disablewebmail=0 to individual accounts. See the
   section "Account options" in README_authlib.html in the courier-authlib
   package for more information on setting the following account options:

   disablewebmail - if set to a non-zero value, this account will not be
   permitted to login to webmail (e.g. because the user is only allowed to
   use POP3 or IMAP)

   wbnochangingfrom - if set to a non-zero value, SqWebMail will not allow
   the From: header to be changed, it will always have its default value.

   wbnochangepass - if set to a non-zero value, SqWebMail will not allow
   passwords to be changed. See "Password changes", above, for more
   information.

   wbusexsender - if set to a non-zero value, 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.

   wbnoimages - if set to a non-zero value then no images or icons will be
   used. The generated interface will be a text-only interface.

   wbnodsn - set to a non-zero value then the option to request delivery
   confirmation receipts will not be shown. Delivery confirmation receipts
   require the local mail server to support RFC 1894 delivery status
   notifications, and some mail servers do not implement DSNs. NOTE: Qmail
   does not implement DSNs, so this option must be set when installing
   sqwebmail on a Qmail box.

   In addition, there's some global configuration that can be done after
   installation. The following presumes that SqWebMail's configuration files
   are installed in /usr/lib/sqwebmail (the default).

   /usr/lib/sqwebmail/etc/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/lib/sqwebmail/etc/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/lib/sqwebmail/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/lib/sqwebmail/etc/logindomainlist - if this file exists, it can be
   used in a vast number of ways to fine tune the user login experience. See
   README.logindomainlist.html for more information.

   /usr/lib/sqwebmail/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. The footer file carries the following requirements:

     • The footer file must be coded in UTF-8.

     • The footer file must follow the format=flowed; delsp=yes format, as
       specified by RFC 3676. Capsule summary:

          • Paragraphs are delimited by blank lines.

          • Paragraphs that consist of more than one line must have a
            trailing space ending each line except the last line in the
            paragraph.

          • That trailing space is in addition to a space that delimits
            individual words in most Western languages. Therefore, a line
            that ends on a word without punctuation and continues with the
            next word at the beginning of the next line must end with two
            spaces: the usual space that separates individual words, and a
            second space that indicates that the paragraph continues on the
            next line.

          • Restated: a line that ends with a space is logically joined with
            the next line, after the trailing space is logically removed.

          • Lines that begin with a space character or the ">" character must
            have an additional space character prepended to them. This
            leading space character is logically removed from the contents of
            the line.

     • Signature content gets formatted as part of the message together with
       the rest of the content. Sender-selected option to format the message
       as either a plain text message, or using wiki-style HTML markup
       applies to the footer file too. The footer file's contents should be
       constructed taking into account the possibility that wiki-style HTML
       markup may get optionally applied to the footer content.

   /usr/lib/sqwebmail/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.

Account Initialization Hook

   If there is a file or a symbolic link in the maildir called "loginexec",
   and if it is executable, then the executable file will be invoked after a
   succesful login. If the program terminates with an exit code of 0, the
   "loginexec" file (or a symbolic link) will be removed.

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.

Adjusting maximum message size

   The --with-maxargsize, --with-maxformargsize, and --with-maxmsgsize
   options to the configure script set the parameters that control the
   maximum size of messages and attachments. These parameters can also be set
   through the following environment variables.

   > NOTE: The configure script parameters define the minimum settngs. The
   > following environment variables may be used to set larger limits only.

   > NOTE: These settings limit only the maximum size of messages sent by
   > SqWebMail. The limit on the incoming message size is set by your mail
   > server.

   SQWEBMAIL_MAXARGSIZE
   Approximate maximum size, in bytes, of the message, excluding any
   attachments (overrides the --with-maxargsize parameter to the configure
   script). This is the maximum message that can be typed into SqWebMail.

   NOTE: SqWebMail has an inactivity timeout. While composing a new message
   use the "Preview" button frequently to save the unfinished message and
   keep the session from timing out.

   SQWEBMAIL_MAXATTSIZE
   Approximate maximum size, of each allowed attachment. (overrides the
   --with-maxargsize parameter to the configure script).

   NOTE: Attaching binary files to E-mail messages incurs an overhead of
   approximately 33%. E-mail is really not the optimum medium for exchanging
   files. Setting SQWEBMAIL_MAXATTSIZE to 4000000 will effectively allow
   attaching files of up to 3000000 bytes in length, approximately.

   SQWEBMAIL_MAXMSGSIZE
   Approximate maximum size, of a message, including the text portion and all
   attachments (overrides the --with-maxmsgsize parameter to the configure
   script). There can be any number of attachments, each one up to
   SQWEBMAIL_MAXATTSIZE bytes long, but the sum total of the entire message
   cannot exceed SQWEBMAIL_MAXMSGSIZE.

   These variables must be set in the environment that runs the SqWebMail CGI
   program. With Apache, these variables can be set in the httpd.conf file by
   the SetEnv command. httpd.conf example:

   SetEnv SQWEBMAIL_MAXATTSIZE 1000000
   SetEnv SQWEBMAIL_MAXMSGSIZE 4000000

   > NOTE: These settings are global, and apply to all mailboxes. However,
   > advanced Apache configuration can be used to use different environment
   > variable settings with different virtual hosts.

   > NOTE: On 32-bit platforms, the maximum limits may not exceed 2
   > gigabytes. A 64-bit platform is required to have SqWebMail capable of
   > handling attachments and messages larger than 2 gigabytes.

Random seed

   A random seed is required for preventing certain kinds of external attacks
   against the SqWebMail server. The random seed must be a constant value,
   only varying between different instances of SqWebMail. By default the
   random seed is derived from the inode number of one of the supporting
   script files. The script file ordinarily remains constant, thus the random
   seed does not change, but different SqWebMail installs will end up with a
   different seed.

   When a pool of SqWebMail servers is combined for load-balancing, all
   servers must use the same random seed. This is done by defining the
   SQWEBMAIL_RANDSEED environment variable. This can be set in the httpd.conf
   as well:

   SetEnv SQWEBMAIL_RANDSEED 82738AZ

   SQWEBMAIL_RANDSEED should contain up to ten letters or numbers.

Domain-based templates

   The default set of templates for the dynamically generated HTML is
   installed in /usr/lib/sqwebmail/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/lib/sqwebmail/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/lib/sqwebmail/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/lib/sqwebmail/share/sqwebmail/webmail.example.com
     [...]
   </VirtualHost>

   The possibilities are endless.

Name-based templates

   In versions of sqwebmail greater than sqwebmail-3.5.3.20030629 it is
   possible to display two or more templates from the same CGI binary WITHOUT
   setting up multiple domain names.

   For example, with Name-based templates an sqwebmail administrator can set
   up sqwebmail to display a template in the
   /usr/lib/sqwebmail/share/sqwebmail/html directory when sqwebmail is called
   from the URL: http://www.foo.com/cgi-bin/sqwebmail

   And display a different template in the
   /usr/lib/sqwebmail/share/sqwebmail/alternate-html directory when sqwebmail
   is called from the URL: http://www.foo.com/cgi-bin/sqwebmail-alt-template

   This is made possible by a little web server magic (explained below in the
   section entitled "Apache Name-based template configuration example") and
   the setting of TWO sqwebmail environment variables:

   SQWEBMAIL_TEMPLATEDIR SQWEBMAIL_IMAGEURL

   You should recognize the SQWEBMAIL_TEMPLATEDIR environment variable from
   the section above on Domain-based templates. If you haven't read that
   section yet, please do so now.

   The SQWEBMAIL_IMAGEURL environment variable is new in versions of
   sqwebmail greater than sqwebmail-3.5.3.20030629. It allows us to set, at
   run time, the image URL, or the root URL, in which to look for our
   template's images. This image URL is then automatically inserted into the
   current template anytime a conditional image tag or an IMAGEURL tag is
   encountered.

   This is an example of a conditional image tag:

   [#@image.gif, ... @text@#]

   The conditional image tag is replaced at template processing time with an
   HTML <img src="..."> tag if (hence the word "conditional") sqwebmail is
   set up to display images.

   This is an example of an IMAGEURL tag:

   [#IMAGEURL#]

   The IMAGEURL tag is replaced at template processing time with the contents
   of the SQWEBMAIL_IMAGEURL environment variable, if set, and otherwise with
   the value of the --with-imageurl configure option, which defaults to
   "/webmail".

  Apache Name-based template configuration example

   Let's take a look at a simple Apache Name-based sqwebmail template
   configuration example:


   # Sqwebmail Alternate Template URL
   ScriptAlias /cgi-bin/sqwebmail-alt-template "/usr/local/apache/cgi-bin/sqwebmail"

   <Location /cgi-bin/sqwebmail-alt-template>
       Setenv SQWEBMAIL_TEMPLATEDIR "/usr/lib/sqwebmail/share/sqwebmail/alternate-template"
       Setenv SQWEBMAIL_IMAGEURL "/alternate-webmail"
       [...]
   </Location>


   The above should allow your users to run sqwebmail with the template in
   /usr/lib/sqwebmail/share/sqwebmail/alternate-template and an image URL of
   /alternate-webmail, simply by calling sqwebmail from the following URL:

   http://www.yourdomain.com/cgi-bin/sqwebmail-alt-template

   The original sqwebmail templates would then still be available from this
   URL:

   http://www.yourdomain.com/cgi-bin/sqwebmail

   Using Apache's <Location> directive we can utilize a virtually unlimited
   number of templates without setting up a single virtual domain.

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/lib/sqwebmail/libexec/sqwebmail by default, and the manual page will
   be installed in /usr/lib/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.

   The OpenLDAP development toolkit must be installed before building
   SqWebMail, in order for LDAP search code to compile.

   The file /usr/lib/sqwebmail/etc/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. name is the unique name for this
   LDAP server. host and port specify the connection parameters. suffix
   specifies the root LDAP entry whose subtree gets searched. The binddn and
   bindpw fields are not presently used (they were used in earlier version of
   SqWebMail, before the LDAP search interface was rewritten and simplified).

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 2.0,
   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
   libs/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.
