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.
Building SqWebMail now requires the The GNU IDN library.
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.--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). 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-strip
to install the files. As mentioned before,
use make install
if make install-strip
doesn't work.
WARNING: set your umask to 022 before running
make install
or make install-strip
.
Before running make install-strip
, verify the
contents of the sendit.sh
script, and make sure that
your mail transfer agent is corrently invoked.
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.
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/defaultdomain
- 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.
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
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
--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.
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.
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