                                  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.

    Rocky/RHEL 8/9 notes

Courier packages require C++17 support, but the default version of gcc does not
fully support it, and a newer gcc is needed:

dnf install --enablerepo=crb -y gcc-toolset-14
scl enable gcc-toolset-14 "rpmbuild -ta sqwebmail-VERSION.tar.bz2"

  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.

NOTE: if the courier-debuild script stops with an error complaining about
missing dependencies, then use "apt install" to install them, then try again.

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

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

NOTE: All Courier packages should be built with the same version of gcc, which
is selected by the DEBGCC environment variable before running courier-debuild.
See courier-unicode's INSTALL for more information.

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.

    Ubuntu and Debian

Courier packages require C++17 support, but the default version of gcc on Ubuntu
20 does not fully support it, and a newer gcc is needed:

$ sudo apt install -y gcc-10 g++-10
$ DEBGCC=10 ./courier-debuild -us -uc

make check requires both the ISO-8859-1 based en_US locale in addition to the
default en_US.UTF-8, on all versions of Ubuntu and Debian.

  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
    https://www.courier-mta.org/unicode/.
  • The Courier authentication library. Before installing SqWebMail, download
    and install https://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
https://www.courier-mta.org/download.html#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.
  • --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.

Banner program

>       SetEnv SQWEBMAIL_BANNERPROG=/usr/local/bin/bannerprog
>

The SQWEBMAIL_BANNERPROG environment variable, if set, defines a full path to a
program that generates a banner. 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.

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.
