Installation

Upgrading from an earlier version

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

Upgrading from versions prior to 3.0

THIS IS A MAJOR UPGRADE

All mail passwords must be reset when upgrading from versions prior to 3.0. Prior to 3.0 SqWebMail maintained a separate password file for webmail logins. It was automatically initialized with the system password, but then maintained separately. "System password" 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 start a separate copy of version 3's authdaemond process, and to set up version 3's cleanup cron job. For a short period of time there will be two copies of each. Some careful attention will be needed to keep everything in order.
  
  
• If you are using the authuserdb authentication module, run the makeuserdb script from sqwebmail 3.0 to rebuild the userdb database.
  
  
• Create a test mail account (if none already exist). Log into the mail account using the previous version of SqWebMail's (which should still be installed) password, password A.
  
  
• Start the new authdaemond process (and install version 3's cron job). Reset the test mail account's password to password B. Load the URL for version 3's sqwebmail binary in a browser. The URL will probably be http://domain/cgi-bin/sqwebmail3/sqwebmail. Log into the test mail account with password B. Go into the preferences and change password B to password C. Log out and log in using password C. Now, go back to the existing version of SqWebMail (probably http://domain/cgi-bin/sqwebmail), and observe that you will still use password A with the existing version of SqWebMail, which maintains a separate password file.
  
  
• Convince yourself that everything Is Working Right[tm].
  
  
• Make arrangements to reset all mail account passwords. That's mostly an administrative function.
  
  
• Go into the cgi-bin directory. Rename the existing sqwebmail binary to sqwebmail.old, then move the new sqwebmail binary from the sqwebmail3 subdirectory. Take care to preserve the ownership and permission settings on the binary.
  
  
• After everything has been running smoothly for a couple of weeks, blow away the old version of SqWebMail. Decommission its authdaemond process, and delete its cron job. You'll have to make yourself a mental note to always use the extra options to the configure script in order to be able to upgrade future versions of SqWebMail into the same non-default installation location. That's not the end of the world, and if you feel comfortable knowing what you're doing, you can always rerun configure, and reinstall version 3 into the default installation location. This is up to you.

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

Upgrading from versions prior to 1.1

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

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

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

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

Overview

The requirements to install SqWebMail are:

• A C++ compiler. SqWebMail is written in C but there are some auxiliary programs that are written in C++. gcc is recommended.
  

  
  

• GNU 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 "expect". expect is usually included with most systems. Expect can be downloaded from http://expect.nist.gov/ if it's not installed on your system. This utility is used to change system login passwords, by scripting the passwd command. If you do not have expect installed you will not be able to change system login passwords through SqWebMail. However you can still use non-system authentication modules (see below).
  
  
• A web server. Apache will do nicely, but so will any web server that fully implements the Common Gateway Interface. SqWebMail is a straight CGI app, and does not need any other support from the web server. However, the web server must implement the full CGI interface, since SqWebMail makes the use of pretty much every CGI variable in existence.
  
  
• If you want to implement LDAP, PostgreSQL, or MySQL-based authentication you will need OpenLDAP, PostgreSQL and MySQL development libraries.

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

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

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

  # Tweak your web server for MSIE

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

The options to the configure program are as follows:

• --without-module - explicitly disable an authentication module named "module". Example: --without-authpam. See below for more details.
  
  
• --disable-changepass - disable the ability to change login passwords. Use this if you don't want to install the authdaemon.passwd suid utility that is used to change login passwords for system accounts.
  
  
• --disable-utf7-folder-encoding - do not use modified-UTF7 to encode 8-bit characters in names of folders. See "IMAP and Unicode", below, for more information. (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.
  
  You MUST add a periodic cron job to run the cleancache.pl script in order to delete stale cache records from the cache directory. make install will display the message containing the text of the cron job.
  
  
• --without-gzip - do not use gzip compression. By default, some pages will be compressed with gzip before being sent by sqwebmail (to browsers that support gzip compression). Note that this may result in additional load on your server, so --without-gzip can be used to turn it off, if necessary. The gzip program must be in your default path at the time you run configure in order for gzip compression to be enabled (the absolute pathname is computed and used at runtime).
  
  

• --with-db=db - Either the GDBM or the DB library is required by SqWebMail. The configuration script will check for either one's availability. If both are found, GDBM is selected. Use this option to select the DB library instead (if you only have the DB library installed, this option is not required).
  
  

• --enable-https - have SqWebMail generate https:// URLs for all accesses, instead of http://.
  
  
• --enable-https=login - generate a single https:// URL for the login function only. The idea is to use SSL just to send the login and the password. In order for this option to work the URL for both http:// and https:// path to SqWebMail must be identical!
  
  
• --enable-https=auto - this is now the default option. SqWebMail will detect whether the client connects via SSL, or not, and generate either http:// or https:// URLs, appropriately.
  
  
• --enable-hardtimeout=seconds - hard session timeout interval, in seconds. After the interval expires, the user is automatically logged out.
  
  
• --enable-softtimeout=seconds - soft session timeout interval, in seconds. If no account accesses come within the indicated time period, the user is automatically logged out.
  
  
• --enable-autopurge=days - messages in the Trash folder are automatically deleted after this time interval.
  
  
• --enable-maxpurge=days - allow users to specify "days" as the maximum interval for preserving messages in the trash.
  
  
• --with-defaultlang=en - reserved for future use. Selects which set of HTML template files SqWebMail uses by default. Currently only English HTML templates are supplied.
  
  
• --enable-cgibindir=directory - where to install the sqwebmail executable program. This should be your /cgi-bin directory. The configure script will look for a cgi-bin directory in some popular locations; this option can be used to tell configure where to look.
  
  
• --enable-imagedir=directory - where to install the icons and graphic images. This should be somewhere in your web server's document hierarchy. The configure script searches for your web server's document directory in the usual places, this option can be used to tell configure where to look.
  
  
• --enable-imageurl=URL - the URL to the directory containing images and icons.
  
  
• --enable-mimetypes=filelist - a colon-separated list of your mime.types files. When an attachment is uploaded, the corresponding MIME type is derived by searching for the file's extension in the mime.types file. A mime.types file normally comes with Pine or Apache. If this option is not specified, configure looks in some places where mime.types is usually found. If a mime.types file is found in any directory, it is added to the list. This is a list of multiple files separated by a colon. If the MIME type is not found in the first file, SqWebMail will look in the next file.
  
  
• --enable-mimecharset=charset - default charset= tag to stick into the Content-Type: header. the default is iso-8859-1.
  
  
• --enable-lang=lang - reserved for future. Default language of web pages to serve.
  
  
• --enable-bannerprog=program - full path to a banner program. sqwebmail replaces the character sequence [#B#] in HTML template files with the output generated by this program. The first argument to the program will be the name of the HTML file. The banner program can use that to customize banner output.

  It is also possible for a site to stick multiple @B tags in the same HTML page. To distinguish each instance follow the @B tag with up to 30 letters or digits, surrounded by braces. For example: [#B#]{TOP} and [#B#]{BOTTOM}. "TOP", or "BOTTOM" (or anything else) will be the second argument to the banner program.
  
  

• --with-maxargsize =n - set maximum size of an HTTP post SqWebMail will accept. This is, essentially, the maximum length of a text message (excluding any attachments) that SqWebMail will accept.
  
  
• --with-maxformargsize=n - like the above, but applies to an HTTP multipart/formdata post. This is approximately the largest attachment that can be uploaded SqWebMail.
  
  
• --with-maxmsgsize=n - maximum size of messages (including attachments. Defaults to 2097152 (two megabytes). Note that attachments are base64-encoded, which adds 25% overhead, so the maximum size of all attachments is really about 1.5 megabytes.
  
  
• --with-ispell=pathname - if configure finds ispell in the default path, or if you specify the full name to ispell using this option, users will be able to spell check their documents.
  
  
• --without-ispell - disable spell checking.
  
  
• --with-fcgi - enable fastcgi support (see http://www.fastcgi.com). Assumes libfcgi.a and headers are in search path or in main sqwebmail build directory. --enable-bannerprog doesn't work with fcgi.
  
  
• --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.

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.

Install the cleancache.pl cron job

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

Install configuration files

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

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

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

Post-install configuration

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

The default configuration script installs the authdaemond process that handles authentication. Add the following command to your system startup scripts so that the authentication process gets started at system boot:

/usr/local/share/sqwebmail/libexec/authlib/authdaemond start

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

Tweak the web server for MSIE

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

BrowserMatch "MSIE" nokeepalive downgrade-1.0 force-response-1.0

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

Load the login screen

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

IMAP and Unicode

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

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

There are a few IMAP clients that do not use modified UTF7 to encode folder names. --disable-utf7-folder-encoding should be used if that is the case. It is 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).

Spell checking

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

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

Authentication modules

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

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

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

Here's a brief list of the available authentication modules:

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

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

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

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

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

Alternative authdaemond modules

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

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

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

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

authpam

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

Although the exact procedure to configure PAM authentication differs from system to system, if you have the directory /etc/pam.d try creating the file /etc/pam.d/webmail, containing the following text:

#%PAM-1.0
auth    required  /lib/security/pam_pwdb.so shadow nullok
account required  /lib/security/pam_pwdb.so

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

If instead of /etc/pam.d you have a global file named /etc/pam.conf, try appending the following lines to the end of this file:

webmail auth    required pam_pwdb.so shadow nullok
webmail account required pam_pwdb.so shadow nullok

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

The current version of the Linux-PAM library uses a new pam_stack.so module that provides a common set of authentication parameters for most system services. This is now the common configuration in most Linux distributions. See the file sqwebmail/webmail.authpam for an example.

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

NOTE: If optional calendaring is enabled in groupware mode, PAM must be configured to authenticate the "calendar" service in addition to "webmail". In most cases, creating a soft link from /etc/pam.d/calendar to /etc/pam.d/webmail does the trick.

authuserdb

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

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

authmysql

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

authpgsql

Edit the authpgsqlrc configuration file to configure this module. PostgreSQL configuration is nearly identical to MySQL information, see authlib/README.authpostgres.html for more information.

authdaemon

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

Confirming selected authentication options

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

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

Password changes

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

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

     # passwd
     Changing password for luser
     (current) UNIX password:         (old password typed here)
     New UNIX password:               (new password typed here)
     Retype new UNIX password:        (new password retyped here)
     passwd: all authentication tokens updated successfully
     #

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

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

Runtime configuration

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

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

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

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

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

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

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

/usr/local/share/sqwebmail/logindomainlist - if this file exists, 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/local/share/sqwebmail/nodsn - if this file exists 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. Qmail does not implement DSNs, so this file is created by default since most SqWebMail installations use Qmail. Remove this file if the local mail server is not Qmail, and it implements DSNs.

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

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

Adjusting session timeouts

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

SetEnv SQWEBMAIL_TIMEOUTSOFT 3600

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

WARNING:

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

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

Domain-based templates

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

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

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

To do this, make copies of the HTML template directory, /usr/local/share/sqwebmail/html. Then, configure the web server to initialize SQWEBMAIL_TEMPLATEDIR appropriately. For example, with Apache:

  <VirtualHost a.b.c.d>
    ServerName webmail.example.com
    [...]
    SetEnv SQWEBMAIL_TEMPLATEDIR /usr/local/share/webmail/webmail.example.com
    [...]
  </VirtualHost>

Shared folders

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

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

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

LDAP address books

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

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

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

name<tab>host<tab>port<tab>suffix<tab>binddn<tab>bindpw

<tab> is a single ASCII TAB character.

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

Mail Filtering

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

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

Autoreplies

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

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

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

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

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

Calendaring

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

Encryption

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

FAQ: Unable to compile an authentication module

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

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

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

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

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

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

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

Here's how to tweak Apache to work around this particular bug. Add the following directive to Apache's httpd.conf forces the HTTP/1.0 protocol response for Internet Explorer clients:

BrowserMatch "MSIE [45]" nokeepalive downgrade-1.0 force-response-1.0