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.
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.
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.
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.
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.
--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.
make install DESTDIR=/tmp/sqwebmail3 (as always, use
gmake instead of make on xBSD, this command is
implemented by GNU make only)./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.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.makeuserdb script from sqwebmail 3.0 to rebuild the userdb
database.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.cgi-bin directory. Rename the existing
sqwebmail binary to sqwebmail.old, then move
the new sqwebmail binary from the sqwebmail3
subdirectory.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.
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.
The requirements to install SqWebMail are:
The typical sequence of commands to compile and install SqWebMail is as follows:
./configure [options - see below] make configure-check make make check make install-strip # Do a make install if this doesn't work make install-configure # Install configuration files. # Create post-install cron jobs, and modify system startup script # Tweak your web server for MSIE
GNU make is required to compile and install SqWebMail. On xBSD systems GNU make is installed as the "gmake" command. Anywhere this documentation mentions the make command, substitute gmake for make. If you do not have gmake on your system, install it before installing SqWwebMail.
The options to the configure program are as follows:
--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.--disable-utf7-folder-encoding - do not use modified-UTF7
to encode 8-bit characters in names of folders. See "IMAP and Unicode", below, for more information. (Note
- this option will also disable Unicode support, which is required for
GPG support, so if you specify this option and do not explicitly use
--enable-unicode, GPG support will be disabled).--enable-unicode=chset,chset,... - include the
specified Unicode charset mappings. See "IMAP and
Unicode", below, for more information.--with-cachedir=dir,
--with-cacheowner=userid - SqWebMail uses a cache of
currently active logins. SqWebMail runs for each and every HTTP request,
and after starting, it needs to locate the account's maildir. Because
hitting the authentication module can be expensive (think
MySQL/PostgreSQL/LDAP query for every HTTP request!) SqWebMail caches the
login information, in order to avoid having your authentication server
brought down to its knees. By default, the directory
/var/cache/sqwebmail or /var/run/sqwebmail will
be used, owned by the bin user. These options can be used to
specify a different location for the sqwebmail login cache directory.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
iso-8859-1.--enable-lang=lang - reserved for future. Default
language of web pages to serve.--enable-bannerprog=program - full path to a
banner program. sqwebmail replaces the character sequence [#B#] in HTML
template files with the output generated by this program. The first
argument to the program will be the name of the HTML file. The banner
program can use that to customize banner output.
It is also possible for a site to stick multiple @B tags in the same
HTML page. To distinguish each instance follow the @B tag with up to 30
letters or digits, surrounded by braces. For example:
[#B#]{TOP} and [#B#]{BOTTOM}. "TOP", or
"BOTTOM" (or anything else) will be the second argument to the banner
program.
--with-maxargsize =n - set maximum size of an HTTP post
SqWebMail will accept. This is, essentially, the maximum length of a text
message (excluding any attachments) that SqWebMail will accept. 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).--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.
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.
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;
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.
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
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.
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.
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.
The option --disable-utf7-folder-encoding removes some code
from SqWebMail that's not needed if the mail accounts are not accessible via
IMAP. IMAP encodes names of folders that contain non-ASCII characters using a
scheme called "modified-UTF7". Currently, the only known IMAP server
compatible with SqWebMail is Courier-IMAP.
Modified-UTF7 support involves some overhead, so this option can be used to disable modified-UTF7. If there isn't going to be any IMAP access to the same mail accounts, there's no need to include all this baggage.
There are a few IMAP clients that do not use modified UTF7 to encode
folder names. --disable-utf7-folder-encoding should be used if
that is the case. It is not possible to support both UTF7 and non-UTF7
clients at the same time.
The additional overhead in SqWebMail consists of translation tables that
map the local character set to Unicode (from which modified UTF-7 is
derived). This is what happens unless the
--disable-utf7-folder-encoding option is used. The
configure script takes the character set used for the HTML
templates, and loads the Unicode mappings just for that character set. By
default, SqWebMail is distributed with a single set of HTML templates that
use the iso-8859-1 character set. If you are installing a
modified derivative that includes additional templates, the
configure will pick up any additional character sets used by
those templates. The list of all the available character sets can be found in
the file unicode/charsetlist.txt.
You may observe that all the available character sets will be compiled. Rest assured that only the required character sets will be included in the final SqWebMail executable.
IMPORTANT: for UTF7 encoding to work correctly, it is necessary to set the same identical character set in all applications involved: the IMAP client, and SqWebMail. For SqWebMail, it means that the CHARSET file in the HTML template directory must be initialized to set the correct character set.
The option --enable-unicode can be used to explicitly specify
which character set tables to include, overriding the default selected by the
configure. Sometimes this is useful when there are alternative
encodings for the same base character set, like KOI8-R and
IBM866. The option "--enable-unicode=koi8-r,ibm866"
- when used with HTML templates for the koi8-r character set -
allows SqWebMail to display ibm866-encoded E-mail using the
koi8-r character set (and vice versa). Note, for this to work
you will need to install a set of KOI8-R HTML templates. In a
pinch, you can simply edit sqwebmail/html/en/CHARSET.
NOTE: the utf-8 character set MUST be specified if GnuPG 1.0.5 (or later)
is used. The configure script defaults to enabling unicode
support and adding the utf-8 character set if the script finds
that GnuPG 1.0.5 (or later).
SqWebMail can use either the ispell or the aspell package for spell checking messages. Install ispell or aspell before installing SqWebMail.
NOTE: SqWebMail assumes that the spell checking dictionary is called
"english". Some systems use a different name for the default spell checking
dictionary. To change the name of the spell checking dictionary used by
SqWebMail, put the name of the dictionary into the file
/usr/lib/sqwebmail/share/sqwebmail/html/en-us/ISPELLDICT.
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.
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.
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.
/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.
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.
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.
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
configurescript 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--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--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--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.
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.
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".
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.
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.
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 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
maildir/README.maildirfilter.html.
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.
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.
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.
Certain versions of Microsoft Internet Explorer have a bug in HTTP/1.1 protocol implementation that results in MSIE reporting random weird errors when downloading attachments.
Here's how to tweak Apache to work around this particular bug. Add the
following directive to Apache's httpd.conf forces the HTTP/1.0
protocol response for Internet Explorer clients:
BrowserMatch "MSIE [45]" nokeepalive downgrade-1.0 force-response-1.0