1 Installation 2 3 * Upgrading from an earlier version 4 * Overview 5 * Spell checking 6 * PAM authentication 7 * Password changes 8 * Runtime configuration 9 * Account initialization hook 10 * Adjusting session timeouts 11 * Adjusting maximum message size 12 * Random seed 13 * Domain-based templates 14 * Name-based templates 15 * Shared folders 16 * LDAP address books 17 * Mail Filtering 18 * Calendaring 19 * Encryption 20 * FAQ: Problems with downloading attachments with Internet Explorer 21 versions 4 and 5 22 23Upgrading from an earlier version 24 25 Follow the general installation instructions, below, in order to upgrade 26 an existing installation. You just need to make sure that the options to 27 the configure script are the same as for the previous version. You may 28 specify additional options as well, that are new to this release. 29 30 Upgrading from versions prior to 6.0.0 31 32 SqWebMail 6.0.0 update is coordinated with the Courier-IMAP update to 33 Courier-IMAP version 5.0, which added native IMAP UTF8 (Unicode) support 34 and switched to using Unicode for folder names. An update to SqWebMail 6 35 requires a concurrent upgrade to Courier-IMAP 5, and a one-time conversion 36 of all existing mail folders. See the maildirmake(1) manual page for more 37 information. 38 39 Upgrading from versions prior to 5.7.3 40 41 Building SqWebMail now requires the Courier Unicode Library to be 42 installed first. 43 44 Upgrading from versions prior to 5.4 45 46 Building SqWebMail now requires the The GNU IDN library. 47 48 Upgrading from versions prior to 5.1 49 50 SqWebMail now requires the PCRE library to compile. Additionally, if using 51 maildrop, maildrop must be upgraded to version 2.0. 52 53 Version 2.0 of maildrop now uses the PCRE for pattern matching (PCRE is 54 still required to compile SqWebMail even if maildrop is not used), and 55 it's possible that some arkane existing pattern is no longer valid under 56 maildrop 2.0. What will happen is that the first time SqWebMail's mail 57 filtering screen is opened, the non-compatible filtering rules will be 58 quietly deleted. This is a necessary even, and must be done, and the 59 updated filtering rules must be saved, in order to enable mail delivery to 60 this account. 61 62 Upgrating from versions prior to 5.0 63 64 There are two major changes in version 5.0. Starting with 5.0, the 65 authentication library that used to be a part of SqWebMail's source has 66 been spun off into a standalone authentication library. 67 68 You must download and install the Courier authentication library from 69 http://www.courier-mta.org/download.php#authlib before upgrading. Review 70 the documentation in the courier-authlib package for more information. 71 72 The second major change is that the default installation directories for 73 SqWebMail have been changed. SqWebMail's default installation is now more 74 closely aligned with standard installation directories used by many other 75 packages based on the GNU toolchain. 76 77 Earlier versions of SqWebMail preferred to be installed in 78 /usr/local/share/sqwebmail, with various bits and pieces scattered 79 elsewhere. 80 81 Now, SqWebMail's installation layout follows the standards much closer. 82 SqWebMail now implements the usual configuration directives: --prefix, 83 --exec-prefix, --bindir, --datadir, and all the rest. There's only one 84 non-standard default: unless the --prefix option is specified, SqWebMail 85 will be install in /usr/lib/sqwebmail. That's the default installation 86 tree. 87 88 Use the following procedure to upgrade the current installation of 89 SqWebMail: 90 91 If you're using a package manager, such as RPM or APT, build a new 92 package, and let the package manager figure out what to do. Only one 93 manual step may be required, which the package manager probably won't be 94 able to handle on its own: there might be some left-over custom 95 configuration files in /usr/local/share/sqwebmail. Review the old 96 configuration files, and re-apply any custom changes to the new version's 97 configuration file (which will be in /usr/lib/sqwebmail/etc, or wherever 98 your --sysconfdir option places them). DO NOT just copy the configuration 99 file verbatim. Manually re-apply changes, one at a time. 100 101 Otherwise: install the authentication library first. Make sure it is 102 working. Use the authtest program to verify that the authentication 103 library is seeing the existing mail accounts. 104 105 Download the new version of SqWebMail, and extract the source code into a 106 new directory. Follow the regular installation instructions up until the 107 "make install" command. 108 109 Don't run the "make install" command. Switch to the directory with the old 110 SqWebMail's source code, and run "make uninstall" to remove the old 111 version of SqWebMail. Go back to the new source code, then run "make 112 install", then "make install-configure". 113 114 After upgrading, check SqWebMail's older installation directory (usually 115 /usr/local/share/sqwebmail). It'll probably still have some left-over 116 configuration files. Start the new version of SqWebMail, verify that it's 117 working, then nuke /usr/local/share/sqwebmail in order to avoid any future 118 confusion. 119 120 Upgrading from versions prior to 4.1 121 122 In 4.1, the sqwebmaild, authdaemond and pcpd processes all run in the 123 foreground; they are daemonized by running them under the control of a 124 'courierlogger' process, which also captures their stderr output and sends 125 it to syslog. The script sqwebmaild.rc takes care of this for you. After 126 upgrading to 4.1 you will need to modify your system startup script to run 127 sqwebmaild.rc start and not to run sqwebmaild start or authdaemond start. 128 See below for more information. 129 130 Additional authentication debugging capabilities have been added. See 131 authlib/README.authdebug.html for more information. 132 133 A new configuration file, /usr/local/share/sqwebmail/sqwebmaild has been 134 added. Make sure you run make install-configure to create the initial 135 version of this file. 136 137 Upgrading from versions prior to 3.0 138 139 THIS IS A MAJOR UPGRADE 140 141 All mail passwords must be reset when upgrading from versions prior to 142 3.0. Prior to 3.0 SqWebMail maintained a separate password file for 143 webmail logins. It was automatically initialized with the system password, 144 but then maintained separately. "System password" here refers to whatever 145 password authentication was installed: traditional /etc/passwd file, or 146 MySQL, LDAP, or several other methods. 147 148 The separate webmail password file was needed because SqWebmail lacked a 149 convenient way to update the system password. Starting in 3.0, additional 150 code and scripts were added that update the "real" password, and 151 SqWebMail's separate password files are removed. Here is a suggested 152 migration plan: 153 154 Note: if you were using the authvchkpw module then you're pretty much off 155 the hook. All except very old versions of SqWebMail had a special 156 authvchkpw module that kept SqWebMail's and vpopmail's passwords in sync. 157 Although you're mostly off the hook, you should still follow these 158 instructions in order to insure a smooth transition. 159 160 * Add the following options to the configure script: 161 --prefix=/usr/local/share/sqwebmail3 162 --with-cachedir=/var/cache/sqwebmail3 --enable-imageurl=/webmail3 163 --enable-imagedir=/var/www/htdocs/webmail3 164 --enable-cgibindir=/var/www/cgi-bin/sqwebmail3 165 166 The effect of these options is to install SqWebMail3 into different 167 directories than the previous version of sqwebmail (you may need to 168 use a different --enable-imagedir option that reflects your web 169 document root). The default configuration installs SqWebMail in 170 /usr/local/share/sqwebmail (using /var/cache/sqwebmail as the login 171 cache, and /webmail for images). By carefully picking the options, 172 SqWebMail 3.0 can coexist with an earlier version. Earlier versions of 173 SqWebMail also installed a couple of files in /usr/local/libexec, 174 SqWebMail 3.0 no longer does that. 175 176 * Specify the same options to the configure script that were specified 177 for the existing SqWebMail install. 178 * After compiling, run the following command as a non-root user: make 179 install DESTDIR=/tmp/sqwebmail3 (as always, use gmake instead of make 180 on xBSD, this command is implemented by GNU make only). 181 * This essentially installs all files in /tmp/sqwebmail3, which is like 182 a virtual chroot jail: /usr/local/share/sqwebmail becomes 183 /tmp/sqwebmail3/usr/local/share/sqwebmail, etc... Examine the contents 184 of the /tmp/sqwebmail3 tree. This will allow you to confirm that the 185 real make install is not going to scribble over any part of the 186 existing installation. Examine all files and directories underneath 187 /tmp/sqwebmail3 and verify that they are different from the existing 188 install. 189 * Run make install for real. Reenter all configuration data into version 190 3's configuration files, to match the existing sqwebmail's 191 configuration. Don't forget to set up version 3's cleanup cron job. 192 For a short period of time there will be two copies of each. Some 193 careful attention will be needed to keep everything in order. 194 * If you are using the authuserdb authentication module, run the 195 makeuserdb script from sqwebmail 3.0 to rebuild the userdb database. 196 * Create a test mail account (if none already exist). Log into the mail 197 account using the previous version of SqWebMail's (which should still 198 be installed) password, password A. 199 * Run the new sqwebmaild.rc start script (and install version 3's cron 200 job). Reset the test mail account's password to password B. Load the 201 URL for version 3's sqwebmail binary in a browser. The URL will 202 probably be http://domain/cgi-bin/sqwebmail3/sqwebmail. Log into the 203 test mail account with password B. Go into the preferences and change 204 password B to password C. Log out and log in using password C. Now, go 205 back to the existing version of SqWebMail (probably 206 http://domain/cgi-bin/sqwebmail), and observe that you will still use 207 password A with the existing version of SqWebMail, which maintains a 208 separate password file. 209 * Convince yourself that everything Is Working Right[tm]. 210 * Make arrangements to reset all mail account passwords. That's mostly 211 an administrative function. 212 * Go into the cgi-bin directory. Rename the existing sqwebmail binary to 213 sqwebmail.old, then move the new sqwebmail binary from the sqwebmail3 214 subdirectory. 215 * After everything has been running smoothly for a couple of weeks, blow 216 away the old version of SqWebMail. Decommission its authdaemond 217 process, and delete its cron job. You'll have to make yourself a 218 mental note to always use the extra options to the configure script in 219 order to be able to upgrade future versions of SqWebMail into the same 220 non-default installation location. That's not the end of the world, 221 and if you feel comfortable knowing what you're doing, you can always 222 rerun configure, and reinstall version 3 into the default installation 223 location. This is up to you. 224 225 NOTE: the default configuration settings have been changed to always build 226 the authdaemon module, and build all real authentication modules inside 227 authdaemond. This is true even with the authvchkpw module. authdaemond is 228 needed to support the new password authentication framework. 229 230 Upgrading from versions prior to 1.1 231 232 Prior to SqWebMail 1.1, each version installed a default set of 233 configuration files. If some custom changes were made to an existing 234 configuration, after installation those changes had to be reapplied. 235 236 Beginning with version 1.1 this process is mostly automated. Starting with 237 version 1.1, the configuration files contain additional metadata that 238 allow them to be upgraded automatically. For this to work both the old and 239 the new configuration files must contain this metadata. 240 241 Therefore, when upgrading to version 1.1, proceed as follows. Back up the 242 existing configuration, then follow the procedures below to install this 243 version. Because the existing configuration files carry no auto-update 244 metadata, the installation script will rename each configuration file 245 "filename" to "filename.bak", and write a default "filename" in its place. 246 Afterward, edit "filename" and manully reenter all custom changes. Do NOT 247 simply copy the previous configuration file and overwrite the new version, 248 because the autoupdate metadata will be lost. 249 250 Note: not all configuration files can be upgraded automatically. Only 251 those configuration files that carry multiple settings ( authdaemonrc, 252 authldaprc, authmysqlrc, and ldapaddressbook) can be automatically 253 upgraded. 254 255Overview 256 257 The requirements to install SqWebMail are: 258 259 * A C++ compiler. SqWebMail is written in C but there are some auxiliary 260 programs that are written in C++. gcc is recommended. 261 * The PCRE library. 262 * GNU make. This is the default make on Linux. xBSD and other systems 263 usually install GNU make as "gmake". Replace all references to "make" 264 in this document to "gmake". 265 * The GNU IDN library (http://www.gnu.org/software/libidn/). 266 * A web server. Apache will do nicely, but so will any web server that 267 fully implements the Common Gateway Interface. SqWebMail is a straight 268 CGI app, and does not need any other support from the web server. 269 However, the web server must implement the full CGI interface, since 270 SqWebMail makes the use of pretty much every CGI variable in 271 existence. 272 * Courier Unicode Library. Before installing SqWebMail, download and 273 install http://www.courier-mta.org/unicode/. 274 * The Courier authentication library. Before installing Courier-IMAP, 275 download and install http://www.courier-mta.org/authlib/. 276 277 The typical sequence of commands to compile and install SqWebMail is as 278 follows: 279 280 281 ./configure [options - see below] 282 make configure-check 283 make 284 make check 285 make install-strip # Do a make install if this doesn't work 286 make install-configure # Install configuration files. 287 288 # Create post-install cron jobs, and modify system startup script 289 290 # Tweak your web server for MSIE 291 292 GNU make is required to compile and install SqWebMail. On xBSD systems GNU 293 make is installed as the "gmake" command. Anywhere this documentation 294 mentions the make command, substitute gmake for make. If you do not have 295 gmake on your system, install it before installing SqWwebMail. 296 297 The options to the configure program are as follows: 298 299 * --with-libcharset - use the GNU libcharset library, if installed. Some 300 systems do not implement the nl_langinfo(CODESET) system call, which 301 determines the character set used by system messages. If SqWebMail 302 cannot determine the system character set then some items may not be 303 displayed in the correct character set. One example would be the 304 message date times, which use the system strftime() function. Some 305 systems nl_langingo(CODESET) may be available, but may not return the 306 preferred or the correct MIME character set name. Both problems may be 307 fixed by installing the GNU libcharset library, and using the option 308 to compile the support for it. 309 * --with-cachedir=dir, --with-cacheowner=userid - SqWebMail uses a cache 310 of currently active logins. SqWebMail runs for each and every HTTP 311 request, and after starting, it needs to locate the account's maildir. 312 Because hitting the authentication module can be expensive (think 313 MySQL/PostgreSQL/LDAP query for every HTTP request!) SqWebMail caches 314 the login information, in order to avoid having your authentication 315 server brought down to its knees. By default, the directory 316 /var/cache/sqwebmail or /var/run/sqwebmail will be used, owned by the 317 bin user. These options can be used to specify a different location 318 for the sqwebmail login cache directory. 319 You MUST add a periodic cron job to run the cleancache.pl script in 320 order to delete stale cache records from the cache directory. make 321 install will display the message containing the text of the cron job. 322 * --without-gzip - do not use gzip compression. By default, some pages 323 will be compressed with gzip before being sent by sqwebmail (to 324 browsers that support gzip compression). Note that this may result in 325 additional load on your server, so --without-gzip can be used to turn 326 it off, if necessary. The gzip program must be in your default path at 327 the time you run configure in order for gzip compression to be enabled 328 (the absolute pathname is computed and used at runtime). 329 * --with-db=db - Either the GDBM or the DB library is required by 330 SqWebMail. The configuration script will check for either one's 331 availability. If both are found, GDBM is selected. Use this option to 332 select the DB library instead (if you only have the DB library 333 installed, this option is not required). 334 335 * --enable-https - have SqWebMail generate https:// URLs for all 336 accesses, instead of http://. 337 * --enable-https=login - generate a single https:// URL for the login 338 function only. The idea is to use SSL just to send the login and the 339 password. In order for this option to work the URL for both http:// 340 and https:// path to SqWebMail must be identical! 341 * --enable-https=auto - this is now the default option. SqWebMail will 342 detect whether the client connects via SSL, or not, and generate 343 either http:// or https:// URLs, appropriately. 344 * --enable-hardtimeout=seconds - hard session timeout interval, in 345 seconds. After the interval expires, the user is automatically logged 346 out. 347 * --enable-softtimeout=seconds - soft session timeout interval, in 348 seconds. If no account accesses come within the indicated time period, 349 the user is automatically logged out. 350 * --enable-autopurge=days - messages in the Trash folder are 351 automatically deleted after this time interval. 352 * --enable-maxpurge=days - allow users to specify "days" as the maximum 353 interval for preserving messages in the trash. 354 * --with-defaultlang=en - reserved for future use. Selects which set of 355 HTML template files SqWebMail uses by default. Currently only English 356 HTML templates are supplied. 357 * --enable-cgibindir=directory - where to install the sqwebmail CGI 358 stub. This should be your /cgi-bin directory. The configure script 359 will look for a cgi-bin directory in some popular locations; this 360 option can be used to tell configure where to look. 361 * --enable-imagedir=directory - where to install the icons and graphic 362 images. This should be somewhere in your web server's document 363 hierarchy. The configure script searches for your web server's 364 document directory in the usual places, this option can be used to 365 tell configure where to look. 366 * --enable-imageurl=URL - the URL to the directory containing images and 367 icons. 368 * --enable-mimetypes=filelist - a colon-separated list of your 369 mime.types files. When an attachment is uploaded, the corresponding 370 MIME type is derived by searching for the file's extension in the 371 mime.types file. A mime.types file normally comes with Pine or Apache. 372 If this option is not specified, configure looks in some places where 373 mime.types is usually found. If a mime.types file is found in any 374 directory, it is added to the list. This is a list of multiple files 375 separated by a colon. If the MIME type is not found in the first file, 376 SqWebMail will look in the next file. 377 * --enable-mimecharset=charset - default charset= tag to stick into the 378 Content-Type: header. the default is utf-8. 379 * --enable-lang=lang - reserved for future. Default language of web 380 pages to serve. 381 * --enable-bannerprog=program - full path to a banner program. sqwebmail 382 replaces the character sequence [#B#] in HTML template files with the 383 output generated by this program. The first argument to the program 384 will be the name of the HTML file. The banner program can use that to 385 customize banner output. 386 387 It is also possible for a site to stick multiple @B tags in the same 388 HTML page. To distinguish each instance follow the @B tag with up to 389 30 letters or digits, surrounded by braces. For example: [#B#]{TOP} 390 and [#B#]{BOTTOM}. "TOP", or "BOTTOM" (or anything else) will be the 391 second argument to the banner program. 392 393 * --with-maxargsize =n - set maximum size of an HTTP post SqWebMail will 394 accept. This is, essentially, the maximum length of a text message 395 (excluding any attachments) that SqWebMail will accept. This setting 396 can also be adjusted at runtime. See Adjusting maximum message size, 397 below. 398 * --with-maxformargsize=n - like the above, but applies to an HTTP 399 multipart/formdata post. This is approximately the largest attachment 400 that can be uploaded SqWebMail. This setting can also be adjusted at 401 runtime. See Adjusting maximum message size, below. 402 * --with-maxmsgsize=n - maximum size of messages (including attachments. 403 Defaults to 2097152 (two megabytes). Note that attachments are 404 base64-encoded, which adds 25% overhead, so the maximum size of all 405 attachments is really about 1.5 megabytes. This setting can also be 406 adjusted at runtime. See Adjusting maximum message size, below. 407 * --with-ispell=pathname - if configure finds ispell in the default 408 path, or if you specify the full name to ispell using this option, 409 users will be able to spell check their documents. 410 * --without-ispell - disable spell checking. 411 * --disable-autorenamesent - do not rename the Sent folder every month. 412 This option can also be controlled by the SQWEBMAIL_AUTORENAMESENT 413 environment variable (which can be set in Apache's httpd.conf, for 414 example). This setting gives the initial configuration, that can be 415 individually adjusted in the Preferences screen. 416 * --with-calendarpurge=N - if calendaring is enabled, purge expired 417 calendar events after N days (default: 30). 418 * --with-trashquota - include deleted messages, and the Trash folder, in 419 the estimated quota usage for maildirs. Quotas are optional, see the 420 file maildir/README.maildirquota.html for more information. The 421 default configuration does not count messages marked as deleted (but 422 not yet expunged) and the contents of the Trash folder (which are 423 automatically purged by the server) against the quota usage. 424 * --with-syslog=DEST - select syslog destination, giving one of the 425 facility codes from syslog.h such as "LOCAL7". Defaults to "MAIL". 426 427 After running configure, run make configure-check to verify the 428 directories where the CGI and the image files will be installed. make 429 configure-check prints the directories that the configuration script 430 thinks your web server is installed. Rerun configure and use 431 --enable-cgibindir and --enable-imagedir if SqWebMail guessed wrong. 432 433 Run make to compile SqWebMail, and make install-stripto install the files. 434 As mentioned before, use make install if make install-strip doesn't work. 435 436 WARNING: set your umask to 022 before running make install or make 437 install-strip. 438 439 Before running make install-strip, verify the contents of the sendit.sh 440 script, and make sure that your mail transfer agent is corrently invoked. 441 442 Modify your system startup script 443 444 The following command starts sqwebmail. This command should be added to 445 the system startup script so that sqwebmail automatically starts during 446 the system boot. 447 448 /usr/lib/sqwebmail/libexec/sqwebmaild.rc start 449 450 "sqwebmaild.rc stop" may also be used to shut down the webmail service. 451 452 SELinux 453 454 The following extension may be necessary to make SqWebMail work when 455 SELinux kernel extensions are turned on: 456 457 allow httpd_sys_script_t var_t:sock_file write; 458 allow httpd_sys_script_t unconfined_t:unix_stream_socket connectto; 459 460 Install the cleancache.pl cron job 461 462 After installing, add a cron job that runs the cleancache.pl script at 463 regular intervals (once an hour is fine). cleancache.pl is installed in 464 /usr/lib/sqwebmail/share/sqwebmail. make install will print additional 465 information on installing the cleancache.pl script. 466 467 Install configuration files 468 469 Run make install-configure to initialize certain configuration files. Some 470 SqWebMail's configuration files carry multiple configuration settings, 471 such as authdaemonrc, ldapaddressbook, and others (see elsewhere in 472 INSTALL for additional information regarding these configuration 473 settings). 474 475 For each such configuration file, make install installs filename.dist. 476 make install-configure takes each filename.dist and creates filename. If 477 the previous filename existed, and it contained autoupdate information 478 (SqWebMail 1.1 or later), the existing configuration settings will be 479 preserved, wherever possible. Older configuration files, that are not 480 auto-updatable, will be renamed to filename.bak. 481 482 During an autoupdate make install-configure will report on the disposition 483 of each configuration setting. A configuration setting will be preserved 484 as long as it is still valid in the new version of SqWebMail. Obsolete 485 configuration settings are automatically removed. If a configuration 486 setting may not be valid, it is not preserved, but will revert to its 487 default setting from filename.dist. It is recommended that the output of 488 make install-configure be saved (make install-configure >upgrade.log), so 489 that its report can be examined to identify any configuration settings 490 that are flagged for manual action 491 492 Post-install configuration 493 494 The default configuration script installs the authdaemond process that 495 handles authentication, and it is started by sqwebmaild.rc start 496 497 sqwebmaild.rc stop should also be executed at system shutdown, but is not 498 strictly necessary. 499 500 Tweak the web server for MSIE 501 502 The MSIE browser has a number of bugs in its HTTP/1.1 implementation, at 503 least as of MSIE 4.x and 5.x. You must configure your web server to use 504 HTTP/1.0 when talking to any MSIE browser (at least until MSIE gets 505 fixed). The problem has to do with downloading attachments. Apparently, 506 MSIE forgets how MIME works, when it uses HTTP/1.1. For the Apache server, 507 insert the following directive in httpd.conf: 508 509 BrowserMatch "MSIE" nokeepalive downgrade-1.0 force-response-1.0 510 511 Recent versions of Apache already have a similar directive for a specific 512 version of MSIE, MSIE 4.0b2. Just replace it with a browsermatch for any 513 MSIE version. 514 515 Load the login screen 516 517 Specify the URL to the sqwebmail binary to display the login page. Try to 518 log in to a test account. Review the rest of this configuration file in 519 order to enable optional features that you want to use. 520 521Spell checking 522 523 SqWebMail can use either the ispell or the aspell package for spell 524 checking messages. Install ispell or aspell before installing SqWebMail. 525 526 NOTE: SqWebMail assumes that the spell checking dictionary is called 527 "english". Some systems use a different name for the default spell 528 checking dictionary. To change the name of the spell checking dictionary 529 used by SqWebMail, put the name of the dictionary into the file 530 /usr/lib/sqwebmail/share/sqwebmail/html/en-us/ISPELLDICT. 531 532PAM authentication 533 534 SqWebMail uses the "webmail" service with the Courier authentication 535 library. When the optional groupware calendaring mode is enabled, 536 SqWebMail also uses the "calendar" service. You will have to take 537 additional, site-specific, steps in order to configure your PAM library 538 for the "webmail" and "calendar" PAM services. The specific details 539 regarding your PAM configuration differs from system to system, and you 540 should consult your own documentation. 541 542 See the Courier authentication library documentation for more PAM-related 543 information. 544 545 HINT: try to look at how other PAM services are set up, and duplicate 546 their configuration for the webmail and calendar services. A good example 547 to follow would be the ppp service, if it exists. 548 549Password changes 550 551 After installing SqWebMail be sure to test that the login password can be 552 changed through SqWebMail. Be sure to change the password a couple of 553 times, logging out and back in each time. 554 555 If you do not want to use the password change function you can also remove 556 the sqwebpasswd program. This is a helper program, installed with the 557 set-groupid bit set, that relays the password change request to the 558 authentication daemon, through the filesystem socket that is not globally 559 accessible. The password change request consists of the account name, the 560 old password, and the new password. The password change request is 561 validated by the authentication daemon, and the old password must match 562 the existing password on the account, before the password change goes 563 through. This set-groupid helper program is safe to use. 564 565Runtime configuration 566 567 There are some options which can be used to change sqwebmail's behaviour 568 on individual accounts, or globally, using the "Account Options" feature 569 in the Courier Authentication library. The individual account's setting 570 takes precedence over the DEFAULTOPTIONS settings in the authdaemonrc 571 configuration, so for example if you want to disable webmail access for 572 most accounts but enable it for a select few, you can set 573 DEFAULTOPTIONS="disablewebmail=1" in the authdaemonrc configuration file, 574 and add the option disablewebmail=0 to individual accounts. See the 575 section "Account options" in README_authlib.html in the courier-authlib 576 package for more information on setting the following account options: 577 578 disablewebmail - if set to a non-zero value, this account will not be 579 permitted to login to webmail (e.g. because the user is only allowed to 580 use POP3 or IMAP) 581 582 wbnochangingfrom - if set to a non-zero value, SqWebMail will not allow 583 the From: header to be changed, it will always have its default value. 584 585 wbnochangepass - if set to a non-zero value, SqWebMail will not allow 586 passwords to be changed. See "Password changes", above, for more 587 information. 588 589 wbusexsender - if set to a non-zero value, SqWebMail will attach an 590 X-Sender: header to all outgoing messages. This can be used in the event 591 you would like to be able to modify the From: header, yet also be able to 592 track sent mail to the original account. Although your mail server should 593 records the id of the sending user in the headers of outgoing messages, 594 this is not possible when you have many virtual accounts that share the 595 same system userid. 596 597 wbnoimages - if set to a non-zero value then no images or icons will be 598 used. The generated interface will be a text-only interface. 599 600 wbnodsn - set to a non-zero value then the option to request delivery 601 confirmation receipts will not be shown. Delivery confirmation receipts 602 require the local mail server to support RFC 1894 delivery status 603 notifications, and some mail servers do not implement DSNs. NOTE: Qmail 604 does not implement DSNs, so this option must be set when installing 605 sqwebmail on a Qmail box. 606 607 In addition, there's some global configuration that can be done after 608 installation. The following presumes that SqWebMail's configuration files 609 are installed in /usr/lib/sqwebmail (the default). 610 611 /usr/lib/sqwebmail/etc/hostname - when SqWebMail is installed with a basic 612 configuration for a single domain, SqWebMail sets the domain in the return 613 address for outgoing messages to the defined system hostname. If this file 614 exists it will be used instead of the defined system hostname. 615 616 /usr/lib/sqwebmail/etc/autoresponsesquota - the systemwide quota on 617 autoreplies, if autoreplies and mail filtering are enabled. This file 618 contains one line: "Cnnn" or "Snnn" (or both strings, on the same line). 619 Cnnn: allow up to #nnn autoreplies to be created. Snnn: allow up to #nnn 620 bytes as the total size of all autoreplies, combined. If both Cnnn and 621 Snnn are specified, both quotas apply. If this file does not exist, there 622 is no limit on autoreplies. This quota setting applies systemwide. To 623 override the quota setting for a particular Maildir, create the 624 autoresponsesquota file in that Maildir (which takes precedence). 625 626 /usr/lib/sqwebmail/share/sqwebmail/sendit.sh is a shell script that's 627 called to actually mail a message. It can be customized to do something 628 like rewriting some of the headers, or adding the client's IP address to 629 the headers (sqwebmail does not do that by default). 630 631 /usr/lib/sqwebmail/etc/logindomainlist - if this file exists, it can be 632 used in a vast number of ways to fine tune the user login experience. See 633 README.logindomainlist.html for more information. 634 635 /usr/lib/sqwebmail/share/sqwebmail/html/LANG/footer - if this file exists, 636 its contents will be appended to the end of every sent message. LANG is 637 the language code here, there can be a separate footer per installed 638 language. The footer file carries the following requirements: 639 640 * The footer file must be coded in UTF-8. 641 642 * The footer file must follow the format=flowed; delsp=yes format, as 643 specified by RFC 3676. Capsule summary: 644 645 * Paragraphs are delimited by blank lines. 646 647 * Paragraphs that consist of more than one line must have a 648 trailing space ending each line except the last line in the 649 paragraph. 650 651 * That trailing space is in addition to a space that delimits 652 individual words in most Western languages. Therefore, a line 653 that ends on a word without punctuation and continues with the 654 next word at the beginning of the next line must end with two 655 spaces: the usual space that separates individual words, and a 656 second space that indicates that the paragraph continues on the 657 next line. 658 659 * Restated: a line that ends with a space is logically joined with 660 the next line, after the trailing space is logically removed. 661 662 * Lines that begin with a space character or the ">" character must 663 have an additional space character prepended to them. This 664 leading space character is logically removed from the contents of 665 the line. 666 667 * Signature content gets formatted as part of the message together with 668 the rest of the content. Sender-selected option to format the message 669 as either a plain text message, or using wiki-style HTML markup 670 applies to the footer file too. The footer file's contents should be 671 constructed taking into account the possibility that wiki-style HTML 672 markup may get optionally applied to the footer content. 673 674 /usr/lib/sqwebmail/share/sqwebmail/html/LANG/TIMEZONELIST - a list of 675 alternative timezones. By default all dates and times are shown in the 676 server's default timezone, and the dropdown list on the login screen can 677 be used to select an alternative timezone. SqWebMail comes with a default 678 alternative timezone list that lists only a small number of timezones. 679 Additional timezones can be entered into this file to be shown on the 680 login screen. 681 682Account Initialization Hook 683 684 If there is a file or a symbolic link in the maildir called "loginexec", 685 and if it is executable, then the executable file will be invoked after a 686 succesful login. If the program terminates with an exit code of 0, the 687 "loginexec" file (or a symbolic link) will be removed. 688 689Adjusting session timeouts 690 691 A login session is automatically logged out after certain period of 692 inactivity. The timeout period defaults to 20 minutes, and is set by the 693 --enable-softtimeout option to the configure script. It is also possible 694 to adjust this value by setting the SQWEBMAIL_TIMEOUTSOFT environment 695 variable. For example, with Apache, by adding the following to httpd.conf: 696 697 SetEnv SQWEBMAIL_TIMEOUTSOFT 3600 698 699 There is also a hard timeout, which logs out a session no matter what. The 700 default of two hours is changed with the --enable-hardtimeout option to 701 the configure script, and the SQWEBMAIL_TIMEOUTHARD environment variable. 702 703 WARNING: 704 705 The hard timeout interval is used to calculate the maintenance of the 706 login cache (if that option is selected). This factor is used in the 707 cleancache.pl cleanup script, and changes to this value must be 708 coordinated appropriately. It is not possible to use different hard 709 timeout values with the same login cache (in different virtual domains, as 710 described in the next session). Leisurely tinkering with this environment 711 variable is STRONGLY DISCOURAGED, it's very easy to screw up the whole 712 system. You've been warned. 713 714 If you adjust the hard timeout, you must simultaneously delete your 715 current login cache directory, and adjust $timeouthard in the installed 716 cleancache.pl script. 717 718Adjusting maximum message size 719 720 The --with-maxargsize, --with-maxformargsize, and --with-maxmsgsize 721 options to the configure script set the parameters that control the 722 maximum size of messages and attachments. These parameters can also be set 723 through the following environment variables. 724 725 NOTE: The configure script parameters define the minimum settngs. The 726 following environment variables may be used to set larger limits only. 727 728 NOTE: These settings limit only the maximum size of messages sent by 729 SqWebMail. The limit on the incoming message size is set by your mail 730 server. 731 732 SQWEBMAIL_MAXARGSIZE 733 Approximate maximum size, in bytes, of the message, excluding any 734 attachments (overrides the --with-maxargsize parameter to the 735 configure script). This is the maximum message that can be typed 736 into SqWebMail. 737 738 NOTE: SqWebMail has an inactivity timeout. While composing a new 739 message use the "Preview" button frequently to save the unfinished 740 message and keep the session from timing out. 741 742 SQWEBMAIL_MAXATTSIZE 743 Approximate maximum size, of each allowed attachment. (overrides 744 the --with-maxargsize parameter to the configure script). 745 746 NOTE: Attaching binary files to E-mail messages incurs an overhead 747 of approximately 33%. E-mail is really not the optimum medium for 748 exchanging files. Setting SQWEBMAIL_MAXATTSIZE to 4000000 will 749 effectively allow attaching files of up to 3000000 bytes in 750 length, approximately. 751 752 SQWEBMAIL_MAXMSGSIZE 753 Approximate maximum size, of a message, including the text portion 754 and all attachments (overrides the --with-maxmsgsize parameter to 755 the configure script). There can be any number of attachments, 756 each one up to SQWEBMAIL_MAXATTSIZE bytes long, but the sum total 757 of the entire message cannot exceed SQWEBMAIL_MAXMSGSIZE. 758 759 These variables must be set in the environment that runs the SqWebMail CGI 760 program. With Apache, these variables can be set in the httpd.conf file by 761 the SetEnv command. httpd.conf example: 762 763 SetEnv SQWEBMAIL_MAXATTSIZE 1000000 764 SetEnv SQWEBMAIL_MAXMSGSIZE 4000000 765 766 NOTE: These settings are global, and apply to all mailboxes. However, 767 advanced Apache configuration can be used to use different environment 768 variable settings with different virtual hosts. 769 770 NOTE: On 32-bit platforms, the maximum limits may not exceed 2 771 gigabytes. A 64-bit platform is required to have SqWebMail capable of 772 handling attachments and messages larger than 2 gigabytes. 773 774Random seed 775 776 A random seed is required for preventing certain kinds of external attacks 777 against the SqWebMail server. The random seed must be a constant value, 778 only varying between different instances of SqWebMail. By default the 779 random seed is derived from the inode number of one of the supporting 780 script files. The script file ordinarily remains constant, thus the random 781 seed does not change, but different SqWebMail installs will end up with a 782 different seed. 783 784 When a pool of SqWebMail servers is combined for load-balancing, all 785 servers must use the same random seed. This is done by defining the 786 SQWEBMAIL_RANDSEED environment variable. This can be set in the httpd.conf 787 as well: 788 789 SetEnv SQWEBMAIL_RANDSEED 82738AZ 790 791 SQWEBMAIL_RANDSEED should contain up to ten letters or numbers. 792 793Domain-based templates 794 795 The default set of templates for the dynamically generated HTML is 796 installed in /usr/lib/sqwebmail/share/sqwebmail/html. When the same server 797 is used to provide webmail access for multiple domains it is possible to 798 specify a different set of HTML templates for each domain. 799 800 This functionality is not directly implemented in SqWebMail, simply 801 because there is no standard way to specify this. Instead, this is 802 something that will need some minor work set up. 803 804 Domain-based templates are implemented by making the web server set the 805 environment variables SQWEBMAIL_TEMPLATEDIR prior to running the sqwebmail 806 binary. The contents of this environment variable override the default 807 location of /usr/lib/sqwebmail/share/sqwebmail/html. By having the web 808 server initialize this variable based on the domain name it is possible to 809 present different templates, based on the domain name used. 810 811 To do this, make copies of the HTML template directory, 812 /usr/lib/sqwebmail/share/sqwebmail/html. Then, configure the web server to 813 initialize SQWEBMAIL_TEMPLATEDIR appropriately. For example, with Apache: 814 815 <VirtualHost a.b.c.d> 816 ServerName webmail.example.com 817 [...] 818 SetEnv SQWEBMAIL_TEMPLATEDIR /usr/lib/sqwebmail/share/sqwebmail/webmail.example.com 819 [...] 820 </VirtualHost> 821 822 The possibilities are endless. 823 824Name-based templates 825 826 In versions of sqwebmail greater than sqwebmail-3.5.3.20030629 it is 827 possible to display two or more templates from the same CGI binary WITHOUT 828 setting up multiple domain names. 829 830 For example, with Name-based templates an sqwebmail administrator can set 831 up sqwebmail to display a template in the 832 /usr/lib/sqwebmail/share/sqwebmail/html directory when sqwebmail is called 833 from the URL: http://www.foo.com/cgi-bin/sqwebmail 834 835 And display a different template in the 836 /usr/lib/sqwebmail/share/sqwebmail/alternate-html directory when sqwebmail 837 is called from the URL: http://www.foo.com/cgi-bin/sqwebmail-alt-template 838 839 This is made possible by a little web server magic (explained below in the 840 section entitled "Apache Name-based template configuration example") and 841 the setting of TWO sqwebmail environment variables: 842 843 SQWEBMAIL_TEMPLATEDIR SQWEBMAIL_IMAGEURL 844 845 You should recognize the SQWEBMAIL_TEMPLATEDIR environment variable from 846 the section above on Domain-based templates. If you haven't read that 847 section yet, please do so now. 848 849 The SQWEBMAIL_IMAGEURL environment variable is new in versions of 850 sqwebmail greater than sqwebmail-3.5.3.20030629. It allows us to set, at 851 run time, the image URL, or the root URL, in which to look for our 852 template's images. This image URL is then automatically inserted into the 853 current template anytime a conditional image tag or an IMAGEURL tag is 854 encountered. 855 856 This is an example of a conditional image tag: 857 858 [#@image.gif, ... @text@#] 859 860 The conditional image tag is replaced at template processing time with an 861 HTML <img src="..."> tag if (hence the word "conditional") sqwebmail is 862 set up to display images. 863 864 This is an example of an IMAGEURL tag: 865 866 [#IMAGEURL#] 867 868 The IMAGEURL tag is replaced at template processing time with the contents 869 of the SQWEBMAIL_IMAGEURL environment variable, if set, and otherwise with 870 the value of the --with-imageurl configure option, which defaults to 871 "/webmail". 872 873 Apache Name-based template configuration example 874 875 Let's take a look at a simple Apache Name-based sqwebmail template 876 configuration example: 877 878 879 # Sqwebmail Alternate Template URL 880 ScriptAlias /cgi-bin/sqwebmail-alt-template "/usr/local/apache/cgi-bin/sqwebmail" 881 882 <Location /cgi-bin/sqwebmail-alt-template> 883 Setenv SQWEBMAIL_TEMPLATEDIR "/usr/lib/sqwebmail/share/sqwebmail/alternate-template" 884 Setenv SQWEBMAIL_IMAGEURL "/alternate-webmail" 885 [...] 886 </Location> 887 888 889 The above should allow your users to run sqwebmail with the template in 890 /usr/lib/sqwebmail/share/sqwebmail/alternate-template and an image URL of 891 /alternate-webmail, simply by calling sqwebmail from the following URL: 892 893 http://www.yourdomain.com/cgi-bin/sqwebmail-alt-template 894 895 The original sqwebmail templates would then still be available from this 896 URL: 897 898 http://www.yourdomain.com/cgi-bin/sqwebmail 899 900 Using Apache's <Location> directive we can utilize a virtually unlimited 901 number of templates without setting up a single virtual domain. 902 903Shared folders 904 905 SqWebMail supports shared folders. The SqWebMail distribution includes an 906 enhanced maildirmake command that created shared folders. 907 908 The maildirmake command will be installed in 909 /usr/lib/sqwebmail/libexec/sqwebmail by default, and the manual page will 910 be installed in /usr/lib/sqwebmail/man by default. 911 912 See the manual page for more information on how to set up shared folders. 913 914LDAP address books 915 916 SqWebMail can import E-mail addresses from public LDAP address books into 917 an individual address book. A default systemwide list of accessible LDAP 918 address books is defined for everyone, and individuals can configure 919 additional LDAP address books for themselves. 920 921 The OpenLDAP development toolkit must be installed before building 922 SqWebMail, in order for LDAP search code to compile. 923 924 The file /usr/lib/sqwebmail/etc/ldapaddressbook should contain a default 925 systemwide list of accessible address book. A default file will be 926 installed, listing some common Internet address books. Each line in this 927 file contains the following information: 928 929 name<tab>host<tab>port<tab>suffix<tab>binddn<tab>bindpw 930 931 <tab> is a single ASCII TAB character. name is the unique name for this 932 LDAP server. host and port specify the connection parameters. suffix 933 specifies the root LDAP entry whose subtree gets searched. The binddn and 934 bindpw fields are not presently used (they were used in earlier version of 935 SqWebMail, before the LDAP search interface was rewritten and simplified). 936 937Mail Filtering 938 939 Mail filtering is an optional feature. Mail filtering allows installation 940 of rules that either automatically deliver incoming messages to specific 941 folders, forward it, or reject it, based on the contents of the message's 942 header or body. A simple autoreply function is also available. Mail 943 filtering requires that the maildrop mail filter must be installed as the 944 local mail delivery agent. Mail filtering requires maildrop version 2.0, 945 or higher. SqWebMail will generate a filtering recipe for maildrop to use 946 when delivering mail. Maildrop's mail filtering language is very powerful, 947 and SqWebMail can reasonably use only a fraction of the mail filtering 948 language, but enough functionality is supported for the majority if mail 949 filtering needs. 950 951 For information on installing and activating mail filtering, see the file 952 libs/maildir/README.maildirfilter.html. 953 954 Autoreplies 955 956 The mail filtering option can also be used to set up autoreplies. 957 Autoreplies are prepared in advance on a separate screen. By default there 958 is no limit on the number of the size of created autoreplies, therefore it 959 is recommended that a quota be set up on the autoreplies (see "Runtime 960 Configuration"). 961 962 Autoreplies can include any valid MIME content (MIME content other than 963 plain text can be uploaded). The following special procedure needs to be 964 used to prepare multipart autoreply content, such as text and html 965 alternatives of the same message: 966 967 Assign a filename extension to the message/rfc822 MIME content. For 968 example, edit your mime.types file, find the message/rfc822 MIME type 969 (append one if it's not in mime.types), and make sure that it has at least 970 one filename extension, such as "msg". 971 972 Prepare the multipart MIME autoreply. The most convenient way is to 973 prepare a normal E-mail message using a conventional E-mail client. Save 974 the RFC822-formatted message in a file with a ".msg" extension, and upload 975 it on the autoreply screen. 976 977 SqWebMail handles uploaded message/rfc822 content by removing all headers 978 except the MIME headers, leaving the MIME content type header, and the 979 actual MIME content. 980 981Calendaring 982 983 This release of SqWebMail contains a beta implementation of basic 984 calendaring, that can be optionally enabled. For more information, see the 985 file pcp/README.html. SqWebMail's calendaring implementation is designed 986 to be used on a private mail server. It is not suitable for use on public 987 webmail servers. See the README file for additional information. 988 989Encryption 990 991 SqWebMail can be set up to encrypt and decrypt mail using GnuPG. For more 992 information on setting up and using encryption, read the file 993 gpglib/README.html in the source distribution. 994 995FAQ: Problems with downloading attachments with Internet Explorer versions 4 and 9965 997 998 Certain versions of Microsoft Internet Explorer have a bug in HTTP/1.1 999 protocol implementation that results in MSIE reporting random weird errors 1000 when downloading attachments. 1001 1002 Here's how to tweak Apache to work around this particular bug. Add the 1003 following directive to Apache's httpd.conf forces the HTTP/1.0 protocol 1004 response for Internet Explorer clients: 1005 1006 BrowserMatch "MSIE [45]" nokeepalive downgrade-1.0 force-response-1.0 1007
