Qmail-Vmailmgr-Courier-SquirrelMail Installation Guide (Red Hat Linux

Qmail-Vmailmgr-Courier-SquirrelMail Installation Guide (Red Hat Linux 7.3) Konstantin Riabitsev icon@duke.edu Version 1.10: June 21, 2002 Abstract This document is useful for people who are looking to set up an email system with an easy-to-use client webmail front end and support for name-based virtual domains. It proposes a Qmail-Vmailmgr-CourierSquirrelMail tie-in as the best small to mid-class server solution. This document is written for Red Hat Linux systems running OS version 7.3. Copyright (c) 2001-2002 by Konstantin Riabitsev . Permission is granted to copy, distribute and/or modify this document under the terms of the GNU Free Documentation License, Version 1.1 or any later version published by the Free Software Foundation; with the Invariant Sections being (no invariant sections), with the Front-Cover Texts being (none), and with the Back-Cover Texts being (none). A copy of the license is available to you in Appendix B. Contents 1 The problem 2 Conventions used in this Guide 3 The Software 3.1 OSes, packages, and disclaimers . . . . . . . . . . . . . . . . . . . 4 From Zero to Sixty in 30 minutes 4.1 Considering the Hardware . . . . 4.1.1 HDD space . . . . . . . . 4.1.2 RAM requirements . . . . 4.1.3 CPU requirements . . . . 4.1.4 Other stuff . . . . . . . . 4.2 Installing Red Hat Linux 7.3 . . 4.2.1 Partitioning . . . . . . . . 1 2 2 2 2 3 3 3 4 5 6 6 6 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . CONTENTS CONTENTS 4.3 4.2.2 Installation Type . . . . . . . . . . . . . . . . . . . . . . . 4.2.3 Sit back and relax . . . . . . . . . . . . . . . . . . . . . . Red Hat Network . . . . . . . . . . . . . . . . . . . . . . . . . . . 6 7 7 8 8 8 9 9 10 10 10 10 11 11 11 11 11 12 12 12 13 13 14 14 5 Preparing the scene 5.0.1 GPG keys . . . . . . . . . . . . . . . . . . . . . . . . . . . 6 Getting and installing the packages 6.1 Removing sendmail . . . . . . . . . . . . . . . . . . . . . . . . . . 6.2 Romantic Getaway . . . . . . . . . . . . . . . . . . . . . . . . . . 7 Configuring your system 7.1 qvcs-install.sh . . . . . 7.1.1 tcp-wrappers . 7.1.2 Apache . . . . 7.1.3 Courier-Imap . 7.1.4 SquirrelMail . . 7.1.5 Firewall . . . . 7.2 vadmin-install.sh . . . 7.3 Configuring Services . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8 Setting Up Virtual Domains 8.1 Running addvirt.sh . . . . . . . . . 8.2 Creating a super-user . . . . . . . 8.3 Logging in to squirrelmail/vadmin 8.4 More Vmailmgr/Vadmin Goodness 8.4.1 Lowly admins . . . . . . . . 8.4.2 Cross-admins . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9 Finishing touches 14 9.1 Root address . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15 9.2 Selective Relaying . . . . . . . . . . . . . . . . . . . . . . . . . . 15 10 Notes and advanced info 10.1 SSL support for IMAP and POP3 . 10.2 SSL support for Apache . . . . . . . 10.3 Vmailmgr login handles . . . . . . . 10.4 Enabling quotas . . . . . . . . . . . 10.5 Running rdate . . . . . . . . . . . . 10.6 Other possible Apache configurations 10.6.1 Required Parts . . . . . . . . 10.7 SquirrelMail plugins . . . . . . . . . 10.8 Keep your system updated . . . . . . 16 16 16 17 17 18 18 18 19 19 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Revision 1.10, as of June 21, 2002 by graf25 CONTENTS CONTENTS 11 Finalizing it all 11.1 Why this is not recommended 11.2 Subsribe to the mailing lists! 11.3 Corrections and Comments . 11.4 Thank you and good luck! ;) for . . . . . . large . . . . . . . . . systems . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19 19 19 20 20 21 22 22 23 24 24 26 26 27 27 27 27 A Upgrading from Red Hat Linux 7.2 to 7.3 B GNU Free Documentation License B.1 Applicability and Definitions . . . . . B.2 Verbatim Copying . . . . . . . . . . . B.3 Copying in Quantity . . . . . . . . . . B.4 Modifications . . . . . . . . . . . . . . B.5 Combining Documents . . . . . . . . . B.6 Collections of Documents . . . . . . . B.7 Aggregation With Independent Works B.8 Translation . . . . . . . . . . . . . . . B.9 Termination . . . . . . . . . . . . . . . B.10 Future Revisions of This License . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Revision 1.10, as of June 21, 2002 by graf25 3 THE SOFTWARE 1 The problem Say, you are looking to start your own small-to-medium hosting business and you need to come up with the best solution for an e-mail server. The things you are looking for are: • Security • Reliability • Lax hardware requirements • Support for many virtual hosts, all sitting on one IP address (name-based hosting) • SMTP relaying for your clients • POP3 and IMAP mailbox access • A nice webmail front-end for your clients I was facing the same problem and I have found that one of the best solutions would be to use Qmail-Courier-Vmailmgr-SquirrelMail tie-in. It is very easy to configure, runs very reliably, and has very good security features. This guide will help you configure and set up a similar system. 2 Conventions used in this Guide For an easier read, the following conventions will be used throughout this guide. File names and directory paths will be shown inline in typewriter font, e.g. “/usr/libexec”. Names of commands will be presented in bold typeface, for example “ps auxww | grep qmail”. Software names and other random bits and pieces that I find worthy of highlighting will be marked in italics typeface. Scripts and verbatim commands that you will need to execute will be presented in typewriter font and placed in paragraphs of their own. For example: [root@mail root]# echo ’Hello World’ | wc -l [root@mail root]# clear 3 3.1 The Software OSes, packages, and disclaimers There are many flavors of UN*X software out there and it’s very hard to write a uniform document that would work for every distribution. Currently, I have two versions of the guide – one aimed at Red Hat Linux people (since that’s what I use as well), and one guide aimed at a more generic BSD-ish system, Revision 1.10, as of June 21, 2002 by graf25 4 FROM ZERO TO SIXTY IN 30 MINUTES be it FreeBSD, OpenBSD, NetBSD, or SlackWare. You are reading the version written for Red Hat Linux 7.3. A number of binary and source packages are provided with this guide to make the installation process easier for you. You must understand, that although I have put a lot of effort into making and troubleshooting these packages, no guarantee WHATSOEVER is given that they will work for you. There is no warranty, no assurance, not even an implication that these packages are suitable for the task described in this document. Having said that (this is a standard disclaimer, really. :)), I am quite convinced that a lot of people will find these packages quite useful and suitable. 4 From Zero to Sixty in 30 minutes This section will walk you through a generic Red Hat Linux installation process. The system we are going to install is going to aim exclusively at being a mail server running nothing but virtual servers and webmail interface (so-called “poptoaster”). If you are planning to use your system for any other services, you can still glance through this installation part for hints and caveats, but your install will differ from the one outlined below. 4.1 Considering the Hardware This setup is aimed at low- to middle-low-end installations, hence we will be VERY relaxed about our hardware requirements. Nevertheless, there are several important things to consider. First of all, we need to make sure that our server is capable of handling peak loads, such as happen at times when a new outlook virus hits the Internet (you HAVE banned outlook from your company’s systems, right? RIGHT? ). Another thing to consider is how many clients you are planning to support, together with how much maximum space you are going to allow them to have. Overall, we are looking at three different variables – memory amount, processor speed, and hard drive space. Let’s consider a setup with 500 clients max and look at all three of these variables. 4.1.1 HDD space A sensible amount of mail quota to allow per client would be about 50Mb, so the amount of hard drive space we will require just for our 500 clients’ e-mails would be around 25Gb. That’s not all, though, as we will need to consider the amount of hard drive space that we will require for the mail queue. Let’s imagine that we’ve been hit with a virus that mails itself to a hundred people and all 500 our clients got infected because we’ve stupidly allowed Outlook on our network (gee, did I come across as biased? :)). If the virus is around 100Kb in size, that means that the total amount of traffic a single client will generate will be around 10Mb. Multiply that by 500, and we arrive at a Revision 1.10, as of June 21, 2002 by graf25 4 FROM ZERO TO SIXTY IN 30 MINUTES4.1 Considering the Hardware staggering 5Gb of traffic just to handle that virus. Since qmail will spend a good deal of time making connections, we will want to make sure that there is plenty of space to queue all of these requests. What this means is that we will have to allow around 5-7Gb of space for queuing, which brings us to 30-35Gb of total space for the mail subsystem. The OS itself will actually require very little space – no more than 500Mb for everything we will need, including virtual web-servers preferences and other miscellaneous data. After we allow about one more gigabyte for system swap space, we arrive at 35-40Gb overall HDD space needed for our installation with 500 clients. Re-calculate the requirements for your number of clients using the following formula: • User space: N*50Mb • Qmail queue: N*10Mb • System and swap: 1.5Gb Whether you decide to choose SCSI or IDE is up to you, but you should consider that most common HDD activity will be accessing and moving small files, something that high-RPM SCSI drives do best. Depending on how redundant you want to be (which generally depends on how pissed off your clients can get, times the amount of downtime), you might consider creating a RAID array to mirror all your data. If you do decide to go with RAID, then my advice would be to get 1 small IDE drive for the system, and 3 SCSI drives for a RAID-1 array (1 active, 1 mirror, and 1 spare). Granted, this setup will be more expensive, but believe me, you will sleep MUCH better at night. 4.1.2 RAM requirements The amount of RAM we will require depends on the number of simultaneous connections we are going to have to our server. This largely depends on the environment you are setting this up for. If you are creating this setup for your company, then it’s a good possibility that a good chunk of these 500 will be accessing your system simultaneously, especially around 9am in the morning when people first arrive at work and check their e-mail. If, however, you are an ISP and your clients are mostly home-users, then the amount of simultaneous connections your server is likely to experience would be MUCH lower, since people will tend to check their e-mail at various times during the day. Let’s approximate – if you are setting up a server for your company, the likely peak usage would be around 90% of all your clients. The amount of memory each request will consume depends largely on what kind of connection it is – smtp and imap require very small amounts of memory for each connection, within Revision 1.10, as of June 21, 2002 by graf25 4 FROM ZERO TO SIXTY IN 30 MINUTES4.1 Considering the Hardware a few hundred kilobytes each. Webmail requests, however, are very memoryhungry and will likely gobble up a hefty chunk of RAM – around 5Mb per each request. However, the good thing about webmail is that each request lasts only a few seconds, so even if 200 people decide to connect to your server at around the same time, it’s unlikely that there will be any more than 50 http processes running simultaneously. But let’s be pessimistic and allow for freaky coincidences. Let’s imagine that all of your 500 clients decided to connect to your server at roughly the same time, and our apache daemon spawned 150 processes, consuming 5Mb each. That brings the memory usage up to 750Mb. The system itself consumes about 50Mb of your memory, so at peak loads we will be consuming around 800Mb of RAM. If you want your server to be snappy at all times, you will need to have at least that much memory in your box, however, if you decide that such coincidence is not very likely and you’d rather save on extra memory, you can settle on 512Mb and let the swapping process catch the rest. If, however, you are an ISP with most clients being home-users, you are not likely to experience more than 10% of your clients trying to connect at the same time. The memory requirement would be more relaxed, and it is likely that 256Mb of memory will suffice for you. Nevertheless, it’s always better to have more memory, than less, so you are still encouraged to use 512Mb for 500 clients. In general, to calculate how much memory you will need use the following formulas: • For a company install: N/3*5+50 • For an ISP with home-users install: N/10*5+50 For 500 users these values will be 880Mb and 300Mb respectively. If you are going to rely on swapping, you can bring those values down to 512Mb and 256Mb. 4.1.3 CPU requirements None of the processes are very CPU-intensive, actually, and you are not very likely to bottleneck at the processor level. The only exception would be when someone tries to sort a mailbox with thousands of e-mails in it via the squirrelmail interface, but I believe that is punishable by law anyway. The best way to avoid this is to set up message count quotas. Overall, I would recommend using something like a near-Ghz Duron system for our 500 users, so our calculation formula would look something like so: • N*1.5+400 I’m using the +400 method simply because I think that if you decide to use something less than a 400Mhz system, you are likely to be plagued by various problems related to aging hardware. Revision 1.10, as of June 21, 2002 by graf25 4 FROM ZERO TO SIXTY IN 30 MINUTES 4.2 Installing Red Hat Linux 7.3 4.1.4 Other stuff I am not covering networking environment and bandwidth, since you will likely have to stick with what you already have anyway. A common 100Base-T network card will suffice in terms of a NIC. However, you should consider implementing some sort of a backup solution to make sure that you don’t lose your job or go out of business when your server catches on fire and you find it reduced to cinders when you come to work one lovely Monday morning. I have only good words to say about Amanda http://www.amanda.org/, or you may choose some of the many alternatives. Backups are not covered by this document, but you are strongly encouraged to investigate this issue on your own. Like I said, it will probably save you from being fired one of those days. 4.2 Installing Red Hat Linux 7.3 Get the Cd’s, or use a floppy to install over ftp/http – your choice, really. 4.2.1 Partitioning You need to create 4 partitions: • / • swap • /var • /home Use the calculations we just did in the previous section to come up with appropriate partition sizes, and create the “/home” partition last letting it use the rest of the remaining disk space. If you’re making a RAID-1, utilize Disk Druid ’s nice RAID’ing features. For our example, the partitions would look like so, for a 40Gb HDD: / swap /var /home 4.2.2 500Mb 1024Mb 7Gb the rest. Installation Type Unless you have other plans for this box besides just letting it be the “poptoaster”, select “Custom”, and when it comes to the component selection, just choose the following two: • Network Support Revision 1.10, as of June 21, 2002 by graf25 4 FROM ZERO TO SIXTY IN 30 MINUTES 4.3 Red Hat Network • Web server This will make your system install just over 300Mb, and that will include everything we will ever need. If you do have other plans for this system, selecting a “Server ” installation type would probably be a safe choice, but you might have to make your “/” partition bigger in order to provide enough space for additional packages. 4.2.3 Sit back and relax Does anyone remember the times when installing Linux was HARD? If, however, you do have problems, please contact support lists to solve them, or, if you purchased Cd’s from Red Hat, bug the Red Hat Support department. 4.3 Red Hat Network After your installation is complete, you are STRONGLY encouraged to use Red Hat Network to keep your system up-to-date. In fact, the very first thing you should do after you are done installing the system and it comes up with the login prompt is to login as root and run the following command:1 [root@mail root]# rhn_register Red Hat Network membership costs $60 per year per box, but your first machine is free of charge. If you are not willing to pay, you can upgrade your packages manually by subscribing to the Red Hat Linux errata mailing list and downloading and installing package updates manually whenever they are released. However, let’s face it – if you take your business seriously, $60 per year per box is NOT going to break you. ;) Among the other nifty things that Red Hat Network provides is a convenient website interface which allows you to update your box remotely. Check out more information about RHN on http://rhn.redhat.com/. After you have registered with RHN, run the following command: [root@mail root]# up2date -u It will tell you to run a “gnupg” command in order to import Red Hat’s public GPG key. Do what it says, then re-run “up2date -u”. This will download and install updated packages from Red Hat, patching up your system.2 After up2date finishes, go ahead and reboot to bring up the updated kernel. 1 If you’re ssh’ing into the system and using “su”, don’t forget to use “su -” to make sure that you have root’s environment enabled. 2 If you want up2date to upgrade your kernel automatically as well, you can edit /etc/sysconfig/rhn/up2date and modify the pkgSkipList parameter changing the line so it looks like so: pkgSkipList= or just run up2date --configure. Revision 1.10, as of June 21, 2002 by graf25 6 GETTING AND INSTALLING THE PACKAGES 5 Preparing the scene Now that your server is installed and updated, we can proceed with the installation of QVCS-related packages. 5.0.1 GPG keys All packages provided with this guide have been signed with my gpg key. To make sure that the packages weren’t corrupted (be it accidentally or deliberately), let’s install the key so we can verify them. Run these commands:3 [root@mail root]#: wget qvcs-guide.sourceforge.net/RPMS/rpm-key.asc [root@mail root]#: gpg --import rpm-key.asc [root@mail root]#: gpg --fingerprint icon-rpms IMPORTANT: Make sure that the key fingerprint is as follows 98AC E60E D862 92FD A03D 977F E7AF 5135 1EB3 93EA If you get a different fingerprint, please contact me IMMEDIATELY at icon@ duke.edu. Otherwise, proceed with the installation. 6 Getting and installing the packages root]# root]# root]# root]# root]# cd mkdir qvcs-rpms cd qvcs-rpms wget -r -nd -np qvcs-guide.sourceforge.net/RPMS/rh73/current/ rpm --checksig *.rpm Run the following commands: [root@mail [root@mail [root@mail [root@mail [root@mail Make sure the report for every package is “md5 gpg OK ” if there are any failures, try to get the packages again by using the wget command from above – maybe some of the packages got mangled during download. If you get failures repeatedly, please notify me right away and do NOT install the packages, as it is quite possible that they have been compromised. If everything verifies again, it’s time to go ahead and do the installation. [root@mail root]# rpm -ivh *.rpm Congratulations, everything is installed. Ignore vadmin’s ever-helpful message about running vadmin-install.sh, we’ll get to that in due time. ;) 3 You might have to run the gpg command twice if it has to create the .gnupg directory first. The output of the command will let you know if you have to run it again or not. Revision 1.10, as of June 21, 2002 by graf25 6 GETTING AND INSTALLING THE PACKAGES6.1 Removing sendmail 6.1 Removing sendmail Now that we got qmail installed, let’s remove sendmail and set the alternatives system to point to qmail instead. Run the following commands: [root@mail root]# rpm -e sendmail sendmail-cf [root@mail root]# alternatives --auto mta That’s it. 6.2 Romantic Getaway Let me explain in more detail what we just installed. There are overall 14 packages that constitute the qvcs system: • qmail: This is the package with all main qmail binaries. Qmail is an MTA and MDA, which stands for “Mail Transport Agent” and “Mail Delivery Agent”. It was written with security in mind and hasn’t had a single security exploit in many years. Moreover, the author of this package has set up a prize of $1000 to anyone who can find a security flaw in qmail – this prize has gone unclaimed in years.4 • qmail-initscripts: This package contains initialization and xinetd scripts for qmail, written specifically for Red Hat Linux 7.x. • courier-imap: Courier-Imap is a very well-done IMAP server which was written specifically to work with “Maildir ” mail storage system used by qmail. It is very fast, very standards compliant, and takes very little space in your computer’s memory. • vmailmgr: This is the Virtual Mail Manager for qmail – it is also an MDA and allows you to have “virtual ” e-mail users without giving said users shell access on your system, which can often lead to security compromises. • vmailmgr-courier-imap: This small package adds an authentication module to courier-imap which allows it to work with virtual users set up by vmailmgr. • vmailmgr-daemon: A small package containing a special binary which lets vmailmgrd communicate with other daemons, like perl or php in our case. • vmailmgr-php: A package containing an include file with php functions allowing php to communicate with the vmailmgr daemon. • ucspi-unix: This is a support package for vmailmgr-daemon and allows creating UNIX sockets on the system for communication between daemons. 4 Just in case you are wondering: yes, I do have a permission to distribute this rpm. See “rpm -qi qmail” for more information. Revision 1.10, as of June 21, 2002 by graf25 7 CONFIGURING YOUR SYSTEM • libmcrypt: This is a set of encryption libraries used by vadmin plugin. Vadmin uses libmcrypt to encrypt the passwords before storing them on the hard drive for enhanced security. • libmcrypt-devel: Some additional files needed for binding libmcrypt to php. • php-mcrypt: A shared library file which ties libmcrypt to php and provides php encryption functions. • squirrelmail: This is a great IMAP-based php webmail system. • vadmin: Vadmin is a plugin for squirrelmail which makes administering vmailmgr virtual domains a part of squirrelmail. It has some very nice features like the ability to add/remove users, set quotas or account expiration dates, etc. • qvcs-helpers: This package has a few helper scripts which come with this guide. They will be explained later. And no, the title of this section doesn’t have anything to do with any of it. It simply states what I would rather be doing right now instead of writing this guide. :) 7 7.1 Configuring your system qvcs-install.sh The qvcs-helpers package provides a convenient (albeit a bit dumb) script called “qvcs-install.sh”. It was written to make the configuration of a dedicated mail server very easy, but if you are planning to do something else with this system, you will need to choose which configurations you wish to apply. Let’s run it: [root@mail mail]# qvcs-install.sh 7.1.1 tcp-wrappers After the introductory spiel you will be presented with an option to modify your tcp-wrappers. You need these in any case, so say “y” to this one and don’t worry, tcp-wrappers will be discussed a bit further – they play an important role in our system setup. 7.1.2 Apache Here is where the script is dumb – it will assume that all you are trying to set up on this system is a dedicated SquirrelMail server. If you have other plans for this system, say “n” to this part and read on – there will be a section devoted to apache configuration. Revision 1.10, as of June 21, 2002 by graf25 7 CONFIGURING YOUR SYSTEM 7.2 vadmin-install.sh 7.1.3 Courier-Imap You need this one. Say “y”. 7.1.4 SquirrelMail Go ahead and say “y” to this one as well. 7.1.5 Firewall This is another part that is up to you. This will configure a pretty restrictive firewall on your system, but as many things with this install script, it will assume that all you are ever going to be running on this system is mail services. If you have other plans for this box that are going to involve things other than just mail and web-server access, choose “n”, otherwise go ahead with the “y”. 7.2 vadmin-install.sh Now let’s configure vadmin by executing the following command: [root@mail root]# vadmin-install.sh Read the description to each screen. Come up with a good “hash line” to encrypt passwords with. Blowfish is a good encryption algorithm, but feel free to choose any other. When it asks you about a super-user, just hit “enter” – we will create one later. When it’s done, vadmin-install will configure the plugin for you and even restart the httpd server. 7.3 Configuring Services Run the following command: [root@mail root]# ntsysv This will bring up a window full of patriotic colors with the services currently configured to run at boot time. Configuring this part is up to you, but here is the list you will need to run JUST the mail server: anacron atd courier-imap crond httpd ipchains keytable kudzu network Revision 1.10, as of June 21, 2002 by graf25 8 SETTING UP VIRTUAL DOMAINS qmail random rhnsd smtp sshd syslog vmailmgrd xinetd Remove any services you don’t need. Httpd will be disabled by default – make sure you enable it. After you’re done configuring the services, go ahead and reboot the system. You don’t technically need to do this, but it’s by far simpler than running a bunch of “service blah stop” and “service blah start”. 8 Setting Up Virtual Domains Let’s create a virtual domain. For the sake of providing examples I’m going to use “hogwarts.jk ” for a virtual domain (what Harry Potter addiction?). You, of course, would need to use something relevant to your environment. 8.1 Running addvirt.sh The “addvirt.sh” script is a part of the qvcs-helpers package. Let’s run it and create a virtual domain: [root@mail root]# addvirt.sh hogwarts.jk The script will ask you for a password – this is a system password, so make it a good one. This version of “addvirt.sh” will automatically store the password on the hdd in its encrypted form, that’s why it’ll ask you to enter the same password three times instead of two. The script will automatically call “vaddomain.sh” provided by vadmin. When it asks you for “lowly admins” or “cross-admins” just say “n” – we’ll get to that later. 8.2 Creating a super-user Before we can use vadmin we will need to create a super-user, amiably called “elvis” in vadmin. Execute the following commands substituting “hogwarts.jk ” and “albus” for whatever else you might have chosen. [root@mail root]# su - hogwarts.jk [hogwarts.jk@mail hogwarts.jk]$ vadduser albus Enter the user’s new password: Please type it again for verification: vadduser: user ’albus’ successfully added Revision 1.10, as of June 21, 2002 by graf25 8 SETTING UP VIRTUAL DOMAINS 8.3 Logging in to squirrelmail/vadmin [hogwarts.jk@mail hogwarts.jk]$ exit [root@mail root]# Now we need to specify that “albus@hogwarts.jk ” is a super-user. Execute the following: [root@mail root]# elvised.sh Yes, there will be a small error saying “grep: *: No such file or directory”. Ignore it. Type in “albus@hogwarts.jk ” say “y” to the next question, and then type “exit”. 8.3 Logging in to squirrelmail/vadmin Surf to “http://mail.hogwarts.jk”. Login as “albus@hogwarts.jk ” with the password you specified just earlier when creating the user “albus”. When you log in, click on the “Admin” link in the right frame. The system will ask you to type in your mailbox password one more time in order to log into vadmin interface. Once you do, you are in the system and can add other users to the “hogwarts.jk” domain. Vadmin plugin interface is pretty well-documented – it looks like the guy who wrote it doesn’t mind writing good documentation. ;) Play around with it. 8.4 More Vmailmgr/Vadmin Goodness Let’s add two more domains to better illustrate the idea of lowly admins and cross-admins. The domains I’m going to use as example ones are going to be “theministry.jk ” and “theburrow.jk ”. It is not possible to use vadmin to create domains – security risks are just too high to use a web-interface for something like that. Therefore, let’s continue using the command line: [root@mail root]# addvirt.sh theministry.jk [root@mail root]# addvirt.sh theburrow.jk Answer “n” to the cross-admins and lowly admins questions. Now go back to our vadmin interface. Login as “albus@hogwarts.jk ” (the elvis user) and click on the “Admin” link again. In the text field where it says “hogwarts.jk” put “theministry.jk” instead and log in – note, that the password is still the mailbox password for “albus@hogwarts.jk ”. Let’s add one user to this domain – “fudge”. Make it a real user, not an alias. After you create “fudge”, log out of this domain by clicking the “Logout” link at the bottom, then click “Log back in”. This time put “theburrow.jk” in the text field and log in. For this domain let’s create two users – “molly” and “arthur ”. These, too, are real users and not just aliases. Now let’s designate some admins. We are going to use the command line for this again. Revision 1.10, as of June 21, 2002 by graf25 9 FINISHING TOUCHES 8.4.1 Lowly admins Lowly admins are the users who can only administer one domain – their own. Let’s make “fudge@theministry.jk ” and “molly@theburrow.jk ” lowly admins for their domains. Run:5 [root@mail root]# admined.sh theministry.jk Add one entry “fudge@theministry.jk ”. Save, exit. Now run: [root@mail root]# admined.sh theburrow.jk and add “molly@theburrow.jk”. Let’s test it. Surf to “mail.theministry.jk” and log in as “fudge@theministry.jk ”. You will notice that after you click on the “Admin” link, there will not be an option to change the domain name. This admin can only administer his own domain. You can check “molly@theburrow.jk ” as well, if you feel like it. 8.4.2 Cross-admins Cross-admins are users who can administer more than one domain, but not all of them. Let’s make “arthur@theburrow.jk ” a cross-admin in charge of both “theburrow.jk” and “theministry.jk” since he lives at the Burrow, but also works at the Ministry. Run this command: [root@mail root]# xadmined.sh This will bring the list with “albus@hogwarts.jk ” already there. Type in “arthur@theburrow.jk ”, answer “y” to the next question, and this will bring up a whole new screen titled “Editing arthur@theburrow.jk ”. Let’s type in two domains: “theministry.jk” and “theburrow.jk”. Type “exit” when you’re done. Now let’s check. Surf to “mail.theburrow.jk” and log in as “arthur@theburrow.jk ”. When you click on the “Admin” link, you will notice that you have an option to edit either “theburrow.jk” or “theministry.jk”. This feature is useful if you have someone who owns several domains and wants to administer all of them – this way you don’t have to create an administrative account for that user within each domain – they can just use one login to edit all of their domains. 9 Finishing touches Just a few more things we should do before we can pronounce our system officially configured. 5 This command will bring up “vi” as your editor. Don’t be alarmed if you aren’t familiar with vi. To insert text press “i”, then type as you normally would. When you are done typing, press “ESC ” on your keyboard, then “:wq” to save and quit. Revision 1.10, as of June 21, 2002 by graf25 9 FINISHING TOUCHES 9.1 Root address 9.1 Root address Due to several reasons all mail for the root address will currently arrive to the /etc/qmail/alias/Mailbox file. This needs to change. You will most likely want to redirect it to some other e-mail address that you check frequently. To do that, edit the /etc/aliases file, and change where it says at the bottom “#root: marc”. Uncomment the entry and change “marc” to some valid email address, like “albus@hogwarts.jk ” if you intend to make that e-mail address your main. After you’re done editing /etc/aliases, run: [root@mail root]# newaliases [root@mail root]# rm /etc/qmail/alias/.qmail-root Note that /etc/aliases should only be used for system users, and not virtual users. Use vadmin to set up virtual user aliases. 9.2 Selective Relaying Selective relaying of e-mail is an important concept to understand. Back in earlier days of the Internet nearly every mail server was configured to accept any e-mail message and relay it to any other destination. Unfortunately, such altruism was soon abused by spammers, who used it to send junk e-mail to unsuspecting people. Ever since then the mail servers were configured to allow only certain small networks to relay outgoing e-mail through then. Those who didn’t ended up on various blacklists. We will use tcp wrappers for selective relaying. Open the /etc/hosts.allow file in “vi”, it should currently have the following entries: tcp-env: 127.0.0.1 : setenv RELAYCLIENT tcp-env: ALL Let’s say that we want everyone from our trusted network to send their outgoing e-mail through our mailserver. If our trusted network is 192.168.1.0/24, then we would change /etc/hosts.allow as follows: tcp-env: 127.0.0.1 192.168.1. : setenv RELAYCLIENT tcp-env: ALL If we only had a fraction of class C, we could change it as follows: tcp-env: 127.0.0.1 192.168.1.0/255.255.255.128 : setenv RELAYCLIENT tcp-env: ALL or, we could limit it by domain name, like so: tcp-env: 127.0.0.1 .hogwarts.jk : setenv RELAYCLIENT tcp-env: ALL Revision 1.10, as of June 21, 2002 by graf25 10 NOTES AND ADVANCED INFO This would mean that any host with IP address resolving to “somehost.hogwarts.jk” would be allowed to relay e-mail. If you have a lot of relaying rules, keeping them all on one line might get tedious. In this case you may create a separate file with all the allowed hosts and networks in it. For example, put all your rules in the file /etc/relay.rules, so it contains something like this: 127.0.0.1 .hogwarts.jk 192.168.1.0/255.255.255.128 rosmerta.hogsmeade.jk and change /etc/hosts.allow to contain the following entries: tcp-env: /etc/relay.rules : setenv RELAYCLIENT tcp-env: ALL For more information about various patterns read the manual page for tcp wrappers. You can view it by executing: [root@mail root]# man hosts.allow 10 Notes and advanced info Your pop-toaster system is now configured. However, here are some notes that you might want to look over in case you’re interested in any of the following. 10.1 SSL support for IMAP and POP3 Your clients might ask you for this feature. It is enabled by default, but the SSL certificates that come with the default installation of courier-imap are bogus. The passwords will be protected, but all e-mail clients will throw major fits before they accept the connection. Obtain a valid SSL certificate for your domain from a Certificate Authority like Thawte or Verisign and put it in /usr/lib/courier-imap/share, replacing the files imapd.pem and pop3d.pem. 10.2 SSL support for Apache You can enable SSL support for Apache, but making it work sanely is a whole different problem. Currently, with the default configuration, only one SSL certificate is allowed per all your virtual domains. You can fix this if you wish, by creating additional configurations in your httpd.conf, but getting valid certificates for all of your virtual domains could get quite costly. What you can do, if you definitely want your clients to access SquirrelMail over SSL, is to set up ONE virtual domain with a valid certificate, for example Revision 1.10, as of June 21, 2002 by graf25 10 NOTES AND ADVANCED INFO 10.3 Vmailmgr login handles create one for “mail.hogwarts.jk”, and ask all your clients to access the webmail at “https://mail.hogwarts.jk/”. The only problem with such approach is that vadmin administrators are required to access the webmail interface via the domain name they are registered to administer. E.g. “molly@theburrow.jk ” will not get an “Admin” link if she accesses it via “mail.hogwarts.jk” – she must access it at “mail.theburrow.jk” in order to administer that domain. She can still access “https://mail.theburrow.jk/” over a secure connection, but her browser will complain each time that the certificate belongs to “mail.hogwarts.jk”. It’s still just as secure, but is somewhat of an annoyance. However, you should realize that apart from vadmin administrators accessing squirrelmail over the cleartext connection is a low security risk since the most that is at stake is your clients’ mailboxes and not your system security. As to the clients’ personal data – it’s inherently insecure anyway, since their e-mail travels over cleartext protocols between the SMTP servers. You can create a test certificate if you don’t want to get a “real” one. The steps are: [root@mail [root@mail [root@mail [root@mail root]# root]# root]# root]# cd /etc/httpd/conf rm -f ssl.crt/server.crt rm -f ssl.key/server.key make testcert Follow the instructions and when done issue a “service httpd restart” to enable the new certificate. 10.3 Vmailmgr login handles As you have already noticed, vmailmgr makes virtual users possible by requiring the full e-mail address as the login. Actually, it will accept any of the following: • albus@hogwarts.jk • albus:hogwarts.jk • hogwarts.jk-albus However, heed my advice and don’t use anything but the first one. Users tend to get very confused between colons and dashes, so just tell them to use their full e-mail address as username and everyone will be happy. 10.4 Enabling quotas Quotas don’t come enabled by default because this adds more load on the server. However, if you decide that you do want to use quotas, you will need to enable them. Execute the following: [root@mail [root@mail [root@mail [root@mail root]# root]# root]# root]# cd /etc/vmailmgr echo ’#!/bin/sh’ > vdeliver-predeliver echo ’/usr/bin/vcheckquota’ >> vdeliver-predeliver chmod 0755 vdeliver-predeliver Revision 1.10, as of June 21, 2002 by graf25 10 NOTES AND ADVANCED INFO 10.5 Running rdate 10.5 Running rdate It’s important to keep your mailserver clock in good shape. You can either run ntpd to syncronise your clock with some ntp server, or, as I usually do, just run “rdate” once an hour. To set up rdate, execute the following: [root@mail [root@mail [root@mail [root@mail root]# root]# root]# root]# cd /etc/cron.hourly echo ’#!/bin/sh’ > rdate.cron echo ’/usr/bin/rdate -s time.nist.gov’ >> rdate.cron chmod 0755 rdate.cron 10.6 Other possible Apache configurations Thick books have been written on the subject of Apache configuration. Naturally, most configurations are out of the scope of this guide. I can only give a few pointers. If you are planning to use this Apache server for other stuff, you might want to bump all SquirrelMail-related stuff into VirtualHost directives so it doesn’t get in the way. There are several ways to do this. For one, create a default VirtualHost which will handle all requests that don’t have their own ServerName allocated. The DocumentRoot for this server would be ’/var/www/squirrelmail’ and therefore anybody accessing it as mail.domain.tld will be served this default setting. You may also set up every mail.domain.tld VirtualHost separately if you can stand the hassle. If you choose to do this, then simply point their DocumentRoot’s all to the same place where your SquirrelMail installation is. If you are planning to host regular websites for these domains and want the users to access mail in a special /webmail subfolder of the www.domain.tld, you might want to create a global alias /mail/ pointing to /var/www/squirrelmail. This will save you a headache of creating symlinks in every documentroot. Overall, there are many ways to configure SquirrelMail so there is only one document root for each virtual domain. You are encouraged to experiment on your own. ;) 10.6.1 Required Parts Only two things are required – UseCanonicalName must be set to “Off” and there MUST be the following include line in the config file: Include /etc/vadmin/apache.inc Otherwise vadmin will not work. Revision 1.10, as of June 21, 2002 by graf25 11 FINALIZING IT ALL 10.7 SquirrelMail plugins 10.7 SquirrelMail plugins One of the greatest features of SquirrelMail is the ability to extend the basic application with additional snippets of code. Many plugins come bundled with SquirrelMail, and you are welcome to investigate them on your own. Plugin installation is usually as easy as just untarring it in the plugins directory, and then running the SquirrelMail’s conf.pl script, however some plugins will require you to manually edit config files or running installer scripts. Consult the plugin’s documentation for more information and installation instructions. 10.8 Keep your system updated Remember – “up2date” is your friend. Run it whenever you receive errata alerts from Red Hat, or use RHN’s nice website front-end to update your boxes. Also, subscribe to the qvcs-guide mailing lists to receive notifications when newer packages become available. See further down. 11 Finalizing it all Your mail system is set up. If you have encountered any problems during the install, then consult the documentation provided with the misbehaving component – it will most likely tell you whom to contact for support. If everything is running smoothly and you are happy with your system, then congratulations – you’ve got yourself one of the best solutions for a pop-toaster out there. 11.1 Why this is not recommended for large systems The only reason this is not recommended for large systems is because SquirrelMail is currently not very scalable – you cannot easily run it on a server farm, since both SquirrelMail and Vadmin save their preferences onto the HDD (a trade-off for not requiring a database engine). However, if you decide not to use SquirrelMail/Vadmin, then Qmail-VmailMgr-Courier is definitely a strong enough solution to be run on high-demand servers, but this has its own set of requirements and is not covered under this guide. 11.2 Subsribe to the mailing lists! No, honestly, do so. Subscribe to the following two mailing lists: • qvcs-guide-rpms@lists.sourceforge.net • qvcs-guide-announce@lists.sourceforge.net The first one will notify you when newer RPMs become available, and the second one will tell you of any other happenings. To subscribe to these lists please go to the qvcs-guide website, at http://qvcs-guide.sf.net/. Revision 1.10, as of June 21, 2002 by graf25 11 FINALIZING IT ALL 11.3 Corrections and Comments 11.3 Corrections and Comments If you’ve found a mistake in this document which you would like to correct, or would just like to comment on something, please send a message to qvcs-guidelist@lists.sourceforge.net so I can make the correction or read your comments. You may also check the qvcs-guide website at http://qvcs-guide.sf.net/ for the latest version of this document. 11.4 Thank you and good luck! ;) If you found this Guide useful, please let me know by executing: [root@mail root]# uname -a | mail icon@duke.edu -s ’Thanks’ Sincerely, Konstantin Riabitsev, aka Mr.Icon. Revision 1.10, as of June 21, 2002 by graf25 A UPGRADING FROM RED HAT LINUX 7.2 TO 7.3 A Upgrading from Red Hat Linux 7.2 to 7.3 NOTE: Please back up your system before upgrading. No, really. If it breaks, you get to keep ALL the pieces. Just use Red Hat’s stock upgrader to up your system from 7.2 to 7.3. However, it will not upgrade cleanly since php-mcrypt depends on the version of php provided in 7.2. Here is what you should do before you upgrade: [root@mail root]# cd /etc [root@mail root]# tar czvf vadmin.tar.gz vadmin [root@mail root]# rpm -e php-mcrypt vadmin This will back up the vadmin configuration so you can restore it after the upgrade. After you do this, go ahead and upgrade your system using either the 7.3 CDs, or any other method supported by the Red Hat Installer. After the upgrade is complete, run the following commands: [root@mail [root@mail [root@mail [root@mail [root@mail [root@mail root]# root]# root]# root]# root]# root]# cd rm -rf qvcs-rpms mkdir qvcs-rpms cd qvcs-rpms wget -r -nd -np qvcs-guide.sourceforge.net/RPMS/rh73/current/ rpm --checksig *.rpm Make sure the signatures verify. If they do, then run: [root@mail [root@mail [root@mail [root@mail [root@mail [root@mail root]# root]# root]# root]# root]# root]# rpm -Uvh php-mcrypt-*.rpm vadmin-*.rpm rpm -Fvh *.rpm cd /etc tar xzvf vadmin.tar.gz rm vadmin.tar.gz alternatives --auto mta If it worked, remember to offer a sacrifice to the GNU gods by microwaving a Windows XP CD. :) Revision 1.10, as of June 21, 2002 by graf25 B GNU FREE DOCUMENTATION LICENSE B GNU Free Documentation License Version 1.1, March 2000 Copyright c 2000 Free Software Foundation, Inc. 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA Everyone is permitted to copy and distribute verbatim copies of this license document, but changing it is not allowed. Preamble The purpose of this License is to make a manual, textbook, or other written document “free” in the sense of freedom: to assure everyone the effective freedom to copy and redistribute it, with or without modifying it, either commercially or noncommercially. Secondarily, this License preserves for the author and publisher a way to get credit for their work, while not being considered responsible for modifications made by others. This License is a kind of “copyleft”, which means that derivative works of the document must themselves be free in the same sense. It complements the GNU General Public License, which is a copyleft license designed for free software. We have designed this License in order to use it for manuals for free software, because free software needs free documentation: a free program should come with manuals providing the same freedoms that the software does. But this License is not limited to software manuals; it can be used for any textual work, regardless of subject matter or whether it is published as a printed book. We recommend this License principally for works whose purpose is instruction or reference. B.1 Applicability and Definitions This License applies to any manual or other work that contains a notice placed by the copyright holder saying it can be distributed under the terms of this License. The “Document”, below, refers to any such manual or work. Any member of the public is a licensee, and is addressed as “you”. A “Modified Version” of the Document means any work containing the Document or a portion of it, either copied verbatim, or with modifications and/or translated into another language. A “Secondary Section” is a named appendix or a front-matter section of the Document that deals exclusively with the relationship of the publishers or authors of the Document to the Document’s overall subject (or to related matters) and contains nothing that could fall directly within that overall subject. (For example, if the Document is in part a textbook of mathematics, a Secondary Section may not explain any mathematics.) The relationship could be a matter of historical connection with the subject or with related matters, or of legal, commercial, philosophical, ethical or political position regarding them. Revision 1.10, as of June 21, 2002 by graf25 B GNU FREE DOCUMENTATION LICENSE B.2 Verbatim Copying The “Invariant Sections” are certain Secondary Sections whose titles are designated, as being those of Invariant Sections, in the notice that says that the Document is released under this License. The “Cover Texts” are certain short passages of text that are listed, as FrontCover Texts or Back-Cover Texts, in the notice that says that the Document is released under this License. A “Transparent” copy of the Document means a machine-readable copy, represented in a format whose specification is available to the general public, whose contents can be viewed and edited directly and straightforwardly with generic text editors or (for images composed of pixels) generic paint programs or (for drawings) some widely available drawing editor, and that is suitable for input to text formatters or for automatic translation to a variety of formats suitable for input to text formatters. A copy made in an otherwise Transparent file format whose markup has been designed to thwart or discourage subsequent modification by readers is not Transparent. A copy that is not “Transparent” is called “Opaque”. Examples of suitable formats for Transparent copies include plain ASCII A without markup, Texinfo input format, L TEX input format, SGML or XML using a publicly available DTD, and standard-conforming simple HTML designed for human modification. Opaque formats include PostScript, PDF, proprietary formats that can be read and edited only by proprietary word processors, SGML or XML for which the DTD and/or processing tools are not generally available, and the machine-generated HTML produced by some word processors for output purposes only. The “Title Page” means, for a printed book, the title page itself, plus such following pages as are needed to hold, legibly, the material this License requires to appear in the title page. For works in formats which do not have any title page as such, “Title Page” means the text near the most prominent appearance of the work’s title, preceding the beginning of the body of the text. B.2 Verbatim Copying You may copy and distribute the Document in any medium, either commercially or noncommercially, provided that this License, the copyright notices, and the license notice saying this License applies to the Document are reproduced in all copies, and that you add no other conditions whatsoever to those of this License. You may not use technical measures to obstruct or control the reading or further copying of the copies you make or distribute. However, you may accept compensation in exchange for copies. If you distribute a large enough number of copies you must also follow the conditions in section 3. You may also lend copies, under the same conditions stated above, and you may publicly display copies. Revision 1.10, as of June 21, 2002 by graf25 B GNU FREE DOCUMENTATION LICENSE B.3 Copying in Quantity B.3 Copying in Quantity If you publish printed copies of the Document numbering more than 100, and the Document’s license notice requires Cover Texts, you must enclose the copies in covers that carry, clearly and legibly, all these Cover Texts: Front-Cover Texts on the front cover, and Back-Cover Texts on the back cover. Both covers must also clearly and legibly identify you as the publisher of these copies. The front cover must present the full title with all words of the title equally prominent and visible. You may add other material on the covers in addition. Copying with changes limited to the covers, as long as they preserve the title of the Document and satisfy these conditions, can be treated as verbatim copying in other respects. If the required texts for either cover are too voluminous to fit legibly, you should put the first ones listed (as many as fit reasonably) on the actual cover, and continue the rest onto adjacent pages. If you publish or distribute Opaque copies of the Document numbering more than 100, you must either include a machine-readable Transparent copy along with each Opaque copy, or state in or with each Opaque copy a publiclyaccessible computer-network location containing a complete Transparent copy of the Document, free of added material, which the general network-using public has access to download anonymously at no charge using public-standard network protocols. If you use the latter option, you must take reasonably prudent steps, when you begin distribution of Opaque copies in quantity, to ensure that this Transparent copy will remain thus accessible at the stated location until at least one year after the last time you distribute an Opaque copy (directly or through your agents or retailers) of that edition to the public. It is requested, but not required, that you contact the authors of the Document well before redistributing any large number of copies, to give them a chance to provide you with an updated version of the Document. B.4 Modifications You may copy and distribute a Modified Version of the Document under the conditions of sections 2 and 3 above, provided that you release the Modified Version under precisely this License, with the Modified Version filling the role of the Document, thus licensing distribution and modification of the Modified Version to whoever possesses a copy of it. In addition, you must do these things in the Modified Version: • Use in the Title Page (and on the covers, if any) a title distinct from that of the Document, and from those of previous versions (which should, if there were any, be listed in the History section of the Document). You may use the same title as a previous version if the original publisher of that version gives permission. • List on the Title Page, as authors, one or more persons or entities responsible for authorship of the modifications in the Modified Version, together Revision 1.10, as of June 21, 2002 by graf25 B GNU FREE DOCUMENTATION LICENSE B.4 Modifications with at least five of the principal authors of the Document (all of its principal authors, if it has less than five). • State on the Title page the name of the publisher of the Modified Version, as the publisher. • Preserve all the copyright notices of the Document. • Add an appropriate copyright notice for your modifications adjacent to the other copyright notices. • Include, immediately after the copyright notices, a license notice giving the public permission to use the Modified Version under the terms of this License, in the form shown in the Addendum below. • Preserve in that license notice the full lists of Invariant Sections and required Cover Texts given in the Document’s license notice. • Include an unaltered copy of this License. • Preserve the section entitled “History”, and its title, and add to it an item stating at least the title, year, new authors, and publisher of the Modified Version as given on the Title Page. If there is no section entitled “History” in the Document, create one stating the title, year, authors, and publisher of the Document as given on its Title Page, then add an item describing the Modified Version as stated in the previous sentence. • Preserve the network location, if any, given in the Document for public access to a Transparent copy of the Document, and likewise the network locations given in the Document for previous versions it was based on. These may be placed in the “History” section. You may omit a network location for a work that was published at least four years before the Document itself, or if the original publisher of the version it refers to gives permission. • In any section entitled “Acknowledgements” or “Dedications”, preserve the section’s title, and preserve in the section all the substance and tone of each of the contributor acknowledgements and/or dedications given therein. • Preserve all the Invariant Sections of the Document, unaltered in their text and in their titles. Section numbers or the equivalent are not considered part of the section titles. • Delete any section entitled “Endorsements”. Such a section may not be included in the Modified Version. • Do not retitle any existing section as “Endorsements” or to conflict in title with any Invariant Section. Revision 1.10, as of June 21, 2002 by graf25 B GNU FREE DOCUMENTATION LICENSE B.5 Combining Documents If the Modified Version includes new front-matter sections or appendices that qualify as Secondary Sections and contain no material copied from the Document, you may at your option designate some or all of these sections as invariant. To do this, add their titles to the list of Invariant Sections in the Modified Version’s license notice. These titles must be distinct from any other section titles. You may add a section entitled “Endorsements”, provided it contains nothing but endorsements of your Modified Version by various parties – for example, statements of peer review or that the text has been approved by an organization as the authoritative definition of a standard. You may add a passage of up to five words as a Front-Cover Text, and a passage of up to 25 words as a Back-Cover Text, to the end of the list of Cover Texts in the Modified Version. Only one passage of Front-Cover Text and one of Back-Cover Text may be added by (or through arrangements made by) any one entity. If the Document already includes a cover text for the same cover, previously added by you or by arrangement made by the same entity you are acting on behalf of, you may not add another; but you may replace the old one, on explicit permission from the previous publisher that added the old one. The author(s) and publisher(s) of the Document do not by this License give permission to use their names for publicity for or to assert or imply endorsement of any Modified Version. B.5 Combining Documents You may combine the Document with other documents released under this License, under the terms defined in section 4 above for modified versions, provided that you include in the combination all of the Invariant Sections of all of the original documents, unmodified, and list them all as Invariant Sections of your combined work in its license notice. The combined work need only contain one copy of this License, and multiple identical Invariant Sections may be replaced with a single copy. If there are multiple Invariant Sections with the same name but different contents, make the title of each such section unique by adding at the end of it, in parentheses, the name of the original author or publisher of that section if known, or else a unique number. Make the same adjustment to the section titles in the list of Invariant Sections in the license notice of the combined work. In the combination, you must combine any sections entitled “History” in the various original documents, forming one section entitled “History”; likewise combine any sections entitled “Acknowledgements”, and any sections entitled “Dedications”. You must delete all sections entitled “Endorsements.” B.6 Collections of Documents You may make a collection consisting of the Document and other documents released under this License, and replace the individual copies of this License in the various documents with a single copy that is included in the collection, Revision 1.10, as of June 21, 2002 by graf25 B GNU FREE DOCUMENTATION LICENSE B.7 Aggregation With Independent Works provided that you follow the rules of this License for verbatim copying of each of the documents in all other respects. You may extract a single document from such a collection, and distribute it individually under this License, provided you insert a copy of this License into the extracted document, and follow this License in all other respects regarding verbatim copying of that document. B.7 Aggregation With Independent Works A compilation of the Document or its derivatives with other separate and independent documents or works, in or on a volume of a storage or distribution medium, does not as a whole count as a Modified Version of the Document, provided no compilation copyright is claimed for the compilation. Such a compilation is called an “aggregate”, and this License does not apply to the other self-contained works thus compiled with the Document, on account of their being thus compiled, if they are not themselves derivative works of the Document. If the Cover Text requirement of section 3 is applicable to these copies of the Document, then if the Document is less than one quarter of the entire aggregate, the Document’s Cover Texts may be placed on covers that surround only the Document within the aggregate. Otherwise they must appear on covers around the whole aggregate. B.8 Translation Translation is considered a kind of modification, so you may distribute translations of the Document under the terms of section 4. Replacing Invariant Sections with translations requires special permission from their copyright holders, but you may include translations of some or all Invariant Sections in addition to the original versions of these Invariant Sections. You may include a translation of this License provided that you also include the original English version of this License. In case of a disagreement between the translation and the original English version of this License, the original English version will prevail. B.9 Termination You may not copy, modify, sublicense, or distribute the Document except as expressly provided for under this License. Any other attempt to copy, modify, sublicense or distribute the Document is void, and will automatically terminate your rights under this License. However, parties who have received copies, or rights, from you under this License will not have their licenses terminated so long as such parties remain in full compliance. B.10 Future Revisions of This License The Free Software Foundation may publish new, revised versions of the GNU Free Documentation License from time to time. Such new versions will be Revision 1.10, as of June 21, 2002 by graf25 B GNU FREE DOCUMENTATION LICENSE B.10 Future Revisions of This License similar in spirit to the present version, but may differ in detail to address new problems or concerns. See http://www.gnu.org/copyleft/. Each version of the License is given a distinguishing version number. If the Document specifies that a particular numbered version of this License ”or any later version” applies to it, you have the option of following the terms and conditions either of that specified version or of any later version that has been published (not as a draft) by the Free Software Foundation. If the Document does not specify a version number of this License, you may choose any version ever published (not as a draft) by the Free Software Foundation. ADDENDUM: How to use this License for your documents To use this License in a document you have written, include a copy of the License in the document and put the following copyright and license notices just after the title page: Copyright c YEAR YOUR NAME. Permission is granted to copy, distribute and/or modify this document under the terms of the GNU Free Documentation License, Version 1.1 or any later version published by the Free Software Foundation; with the Invariant Sections being LIST THEIR TITLES, with the Front-Cover Texts being LIST, and with the Back-Cover Texts being LIST. A copy of the license is included in the section entitled “GNU Free Documentation License”. If you have no Invariant Sections, write “with no Invariant Sections” instead of saying which ones are invariant. If you have no Front-Cover Texts, write “no Front-Cover Texts” instead of “Front-Cover Texts being LIST”; likewise for Back-Cover Texts. If your document contains nontrivial examples of program code, we recommend releasing these examples in parallel under your choice of free software license, such as the GNU General Public License, to permit their use in free software. Revision 1.10, as of June 21, 2002 by graf25