| Article Index |
|---|
| Installing a Webmail System Based on Horde on IIS |
| Page 2 |
| Page 3 |
| All Pages |
(NB: This article is out of date, but may still have useful material.)
For the purposes of this article, there are a few assumptions made:
- You have IIS enabled and functioning with some web site already.
- You have MySQL installed and functioning.
- You have PHP installed and functioning. (preferably the latest in the 4.x branch for the moment) This includes making sure extensions and such work.
- You are installing Horde 2.2.7, IMP 3.2.6, Kronolith 1.1.2, Mnemo 1.1.2, Nag 1.1.1, and Turba 1.2.2.
- You already have a functioning IMAP or POP3 server setup and working.
- You already have a functioning SMTP server setup and working (if needed).
- You are not using an LDAP server (Horde supports this, but I have not tested this configuration).
You will need the following things:
- A MySQL database and user (with password). phpMyAdmin is highly recommended for creating this, and patching in some SQL later on.
- A text editor of some kind (Crimson Editor is highly recommended).
- The extensions gettext, imap, and xml must be installed (edit your php.ini to include them, then restart IIS). You should probably also install domxml while you're at it.
- Something to do file archiving and unarchiving, like FilZip.
- Finally, you need to download the following from Horde.org: Horde, IMP, Kronolith, Mnemo, Nag, and Turba (you install other Horde apps at your own risk).
STEP 1: UNZIP EVERYTHING
The Horde framework is rather versatile, unfortunately, it is also rather tedious to set up. Now that you've downloaded your Horde and co. files, unzip Horde to its own directory on your local hard drive, and rename it to the directory you expect it to be in on your server. For example, if you plan on having http://www.myserver.com/webmail/, rename the freshly created Horde directory to webmail (if you're running webmail in a root directory as its own website, call it webmail for the moment anyway). Afterwards, you need to unzip IMP and the rest of the packages to underneath the webmail directory you just made. After you unzip these to subfolders underneath your webmail directory, rename the directories to simple names from the "name + version number" you have to just the name. For example, rename imp-3.2.6 to just imp (so you end up with something like C:hordeimp). Go through this process with each app, from kronolith to turba.
Now that you've gotten that out of the way, there's more file operations to be done. Under the horde/webmail directory, there's a config directory containing many files with the php.dist extension. You need to make copies of these (select them, hit CTRL-C, then CTRL-V to make copies quickly), and rename them to simply filename.php. For example, prefs.php.dist should be copied, then renamed to prefs.php. Do this first for the files in the main webmail directory, and then repeat the process for each of the applications (eg, impconfig, kronolithconfig, and so on).
The final step is to make a temp directory directly underneath your webmail directory. Once that's done, you're ready for step two.
STEP 2: MYSQL SETUP
Next up is how to set up the Horde MySQL database you'll be using. To make things simple, we'll assume you're using phpMyAdmin, so fire it up and take a look at the database you made for Horde. Be sure you've set proper access permissions for this database for your Horde user (ie, don't just give any user access to this database, if indeed you have that power).
Now, the problem with Horde's default setup is that it insists on using 'horde' as both a username and password, which for many folks will be unacceptable. Therefore, we're going to go over how to fix it. The first thing you need to do is open up the webmailscriptsdbmysqlcreate.sql file in your text editor (note: if it appears as garbage, your editor isn't handling UNIX formatted files correctly, get another editor). From here, you need to change some values. Since you've already created your own Horde user and set its permissions, you don't need the first two REPLACE INTO commands nor the FLUSH PRIVILEDGES that add a user and database and flush priviledges. Delete these lines or comment them out with hash marks (#). Also delete or comment out the CREATE DATABASE horde and USE horde lines (you've already created the Horde database and are going to be using it already). Lines that read GRANT SELECT, INSERT, UPDATE, DELETE ON horde_(table) TO horde@localhost should also be unnecessary; comment these out (there should be three). After you do this, copy the text of the modified SQL script into phpMyAdmin's SQL entry for your webmail database, and it should create the horde_users, horde_prefs, and horde_categories tables for you. Save this SQL file as a different file for later reference.
If you are for whatever reason using MySQL sessions in your setup (instead of PHP sessions), you'll need to open up sessionhandler.sql and paste that into phpMyAdmin, once again excluding the GRANT SELECT... line. Vfs.sql (for a SQL based virtual file system, used only if you have some reason for it) is similar.
To complete SQL setup, you need to go through each of the applications' scripts directories and paste in as appropriate, generally following the same guidelines as above (ie, don't use the last GRANT SELECT... line in them). You need to do this for Kronolith (Kronolith.sql), Mnemo (mnemo_memos.sql), Nag (nag_tasks.sql), and Turba (mysql_create.sql). Note that in the Turba script, you should not copy the USE horde; line. Once you have all the tables installed, you're ready for the next configuration step.
STEP THREE: PEAR INSTALL
(This is the part I'm most sketchy on...if anyone can confirm what I've got here, please do)
PEAR, the PHP Extension and Application Repository, is something not assumed to be installed in this guide because most PHP scripts do not take advantage of it. Horde requires the Log, Mail_Mime, and Net_Socket PEAR modules to be installed. If you work with a web host, you'll likely have to talk them into setting it up; if not, you need to set it up yourself.
The first step is to enable PEAR on your system. Running the GOPEAR.bat batch file should kick that off. Afterwards, you need to install the modules listed above. Note that some of them may be beta and thus PEAR by default won't let you install them, so you'll need to use the force option to make PEAR install them.
STEP FOUR: HORDE CONFIGURATION
Almost there. Remember all those .php files you had to copy and rename back in step one? It's now time to configure them. Don't worry, not all of these files actually need to be touched on. To summarize what needs changing, you must edit the following:
- Webmail\config: horde.php, registry.php
- Webmail\imp\config: conf.php, servers.php, filter.txt, header.txt, trailer.txt
- Webmail\kronolith\config: conf.php
- Webmail\mnemo\config: conf.php
- Webmail\nag\config: conf.php
- Webmail\turba\config: conf.php, sources.php
For the applications (IMP, Turba, etc.) you can also customize the top menu by adding items in the menu.php files. One use for this is making a link back to your main site if webmail is in a subdirectory. There are some other settings you may find in other unmentioned files.
Most of the settings for the files are fairly well explained in said files; simply mind your syntax, know what settings you need (eg, your MySQL username, password, and database name), and you should be fine. However, there are a few changes that may be necessary that are not so obvious. For example, in Webmailconfigregistry.php, you'll want to set IMP as your main login method by uncommenting the auth login and auth logout options with IMP in them. Further down under the application registry, you need to change your webroot (something like /webmail/). To make the home icon work, you may need to set an absolute web path (eg: https://www.mysite.com/webmail/graphics/home.gif). Other icon paths may need to be altered so they don't start with a slash. Try the stock configuration (enabling installed services, of course) before you try editing these paths as this weirdness may have been fixed by now. Also, when asked for absolute paths, make sure you use the absolute path that your server will use in the standard DOS format (eg, D:Serversmysitewebmailfile.txt). Also, in Horde.php, turn off page compression, especially if you have IIS' page compression running.
STEP FIVE: UPLOAD AND CONFIGURE FILE PERMISSIONS
By whichever method you use (FTP, file copy, etc.), transfer the webmail directory you've created to your server. The last thing to do before testing is to set the temporary folder you created back in step four to be writeable by the IIS web user. This is the only directory that should need any such treatment.
STEP SIX: ENJOY YOUR WEBMAIL
Now go to your webmail address (probably something like http://www.myserver.com/webmail/), and login to Horde using your regular mail username and password. That's it!
APPENDIX A: SECURING HORDE USING SSL
Sending plaintext usernames and passwords is not too healthy from a security standpoint, so implementing SSL is a wise idea. For right now, Dylan Beattie's advice on setting up a self-signed certificate on IIS 5 largely applies to IIS 6. Instead of try to reproduce that effort, I've copied that page here in case that site ever goes down. Full credit goes to Dylan, and this was copied per the GNU license listed. Also, note that in your webmailconfighorde.php file, you may want to set the use_ssl parameter to 1 (always generate SSL URLs) after you confirm that SSL works.
One last thing; under IIS management, you can set up a site or directory to use SSL only. If you only want SSL allowed for webmail (generally a good idea), be sure to configure this. Also be aware that you may need to configure firewalls and such to allow for SSL/HTTPS communication; this is by default done on port 443.
In a nutshell, here's the steps to follow:
1. Generate and install your certificate (see below).
2. Set Horde to use SSL only URLs.
3. Set IIS to use SSL on your webmail directory.
4. Check firewalls to make sure they allow port 443 to work.
5. Login to your webmail with a https:// URL, not http://.
Below is Dylan's guide. Please note that it was made originally for IIS5, but I found it was largely applicable to 6.
Overview
This document describes how to sign your own SSL certificate requests using the OpenSSL toolkit and use these self-signed certificates to allow HTTPS connections to Microsoft's IIS 5 web server (as supplied with Windows 2000).
If you know what a self-signed certificate is and understand the concept of a certificate authority, great. If not, this should still work but you'll have no idea what you've acheived when it does :)
Command transcripts are shown in monospaced type, with the bits you type shown in bold. Bits in italics are comments to explain what's going on and what you should be doing.
Disclaimer
I'm by no means a security expert, and I'm not an OpenSSL guru. If you find these notes helpful, great - if you don't, there's plenty of more detailed resources out there which will answer your questions if you take the time to read them properly. Contributions and testimonials are welcome; questions will be read and possibly answered but I'm making no guarantees, and please don't rely on this information for anything important. I don't know whether it's the most secure or most effective way of doing this, but it works and that's good enough for me. If it's not good enough for you, don't use it :)
These instructions were tested using OpenSSL 0.9.6g (v1.0 Final) on Windows 2000 Server running Service Pack 3.
Ingredients
- Windows 2000 running Internet Information Services (IIS)
- The OpenSSL tools for Windows from Shining Light Productions. This is a Windows port of the popular OpenSSL toolkit.
Walkthrough
Install and configure the OpenSSL toolkit
- Get OpenSSL from the address above, and run the installer, accepting the defaults. These instructions assume OpenSSL is installed in C:\OpenSSL.
- Add C:\OpenSSL\bin to your system path (Control Panel, System, Advanced, Environment Variables, System Variables) - this isn't strictly necessary but it makes things a lot easier.
- Create a working directory - here, we'll use c:ssl as our working folder.
- Download this copy of openssl.conf to your working folder. (Note: I have no idea what most of the options in this file mean. I just hacked it around until it worked...)
- Set up the directory structure and files required by OpenSSL:
C:\ssl>md keys
C:\ssl>md requests
C:\ssl>md certs
- Create the file database.txt - an empty (zero-byte) text file. This can be done using the 'touch' command if you have it (it's a Unix tool not available on Windows by default, but you might have one lying around), or by creating an empty file manually:
c:\ssl>copy con database.txt
MS-DOS veterans will recognise this particular invocation. We're copying from CON (the console) to a file called database.txt, and that's a Control-Z end-of-file character on the first line. This should produce a zero-byte file called c:ssldatabase.txt
^Z
C:\ssl>
- Create the serial number file serial.txt. This is a plain ASCII file containing the string "01" on the first line, followed by a newline. Again, we can use a little bit of ancient DOS magic:
C:\ssl>copy con serial.txt
to achieve the desired effect. (That's keystrokes zero, one, return, control-Z, return)
01
^Z
C:\ssl>
Set up a Certificate Authority (CA)
- First, we create a 1024-bit private key to use when creating our CA.:
C:\ssl>openssl genrsa -des3 -out keys/ca.key 1024
The pass phrase will be requested whenever you use this certificate for anything, so make sure you remember it. This will create a file called c:sslkeysca.key, containing our certificate authority private key.
Loading 'screen' into random state - done
warning, not much extra random data, consider using the -rand option
Generating RSA private key, 1024 bit long modulus
...........++++++
..................++++++
e is 65537 (0x10001)
Enter PEM pass phrase: - choose a memorable pass phrase to use for this key
Verifying password - Enter PEM pass phrase: - type your pass phrase again for verification
- Next, we create a master certificate based on this key, to use when signing other certificates:
C:\ssl>openssl req -config openssl.conf -new -x509 -days 1001 -key keys/ca.key -out certs/ca.cer
This will create our CA certificate and store it as c:sslcertsca.cer
Using configuration from openssl.conf
Enter PEM pass phrase: - type your passphrase here.
You are about to be asked to enter information that will be incorporated
into your certificate request.
What you are about to enter is what is called a Distinguished Name or a DN.
There are quite a few fields but you can leave some blank
For some fields there will be a default value,
If you enter '.', the field will be left blank.
-----
Country Name (2 letter code) []:
State or Province Name (full name) []:
Locality Name (eg, city) []:
Organization Name (eg, company) []:
Organizational Unit Name (eg, section) []:
Common Name (eg, your websites domain name) []:
Email Address []:
C:\ssl>
- (optional) Finally, we export our CA certificate in PKCS12 format - this will allow Windows users to import the PKCS12 certificate into their Trusted Root Store, so they don't get warning messages every time they use one of our certificates.
UPDATE (2004-08-08): Apparently doing this includes the private key with the PKCS12 file, which means anyone with the PKCS12 cert can forge certificates from our CA. You should be able to import the ca.cer file directly into your browser instead. I haven't tested this yet, but in the meantime, be warned. (I already told you I didn't know what I was doing...) Thanks to Baahl for this heads-up.
C:\ssl>openssl pkcs12 -export -in certs/ca.cer -inkey keys/ca.key -out certs/ca.p12
This will create c:sslcertsca.p12, which can be imported via Internet Options -> Content -> Certificates on most Windows computers.
Loading 'screen' into random state - done
Enter PEM pass phrase:
Enter Export Password: - users will need this password when importing the certificate
Verifying password - Enter Export Password:
C:\ssl>
Create an IIS Certificate Request
This is described in detail elsewhere on the web - see Microsoft Knowledge Base Article Q228821. You should end up with a file called certreq.txt.
Sign the Certificate Request
- Copy the certreq.txt file into c:\ssl\requests
- Sign the request
C:\ssl>openssl ca -policy policy_anything -config openssl.conf -cert certs/ca.cer -in requests/certreq.txt -keyfile keys/ca.key -days 360 -out certs/iis.cer
Let's just take a look at those command-line options in a bit more detail:
Using configuration from openssl.conf
Loading 'screen' into random state - done
Enter PEM pass phrase:
Check that the request matches the signature
Signature ok
The Subjects Distinguished Name is as follows
commonName :PRINTABLE:'myCommonName'
organizationalUnitName:PRINTABLE:'myOrganisationalUnit'
organizationName :PRINTABLE:'myOrganisation'
localityName :PRINTABLE:'myLocality'
stateOrProvinceName :PRINTABLE:'myProvince'
countryName :PRINTABLE:'US'
Certificate is to be certified until Feb 2 01:13:14 2004 GMT (360 days)
Sign the certificate? [y/n]:y
1 out of 1 certificate requests certified, commit? [y/n]y
Write out database with 1 new entries
Data Base Updated
C:\ssl>
- -policy policy_anything - specifies that we're using the 'policy_anything' policy from our openssl.conf file. This is a relaxed policy in which the name, country, etc. in the certificate don't need to match those used by the certification authority. Use -policy policy_match for a more restrictive CA.
- -config openssl.conf - specifies we're reading our configuration from openssl.conf in the current directory.
- -cert certs/ca.cer - specifies we're using our CA master certificate to sign the request.
- -in requests/certreq.txt - the certificate request we're signing.
- -keyfile keys/ca.key - the private key for our CA master certificate, which proves we're allowed to use it.
- -days 360 - the time until the certficate will expire
- -out certs/iis.cer - the file in which to place our newly-signed certificate
- Convert the signed certificate into x509 format for use with IIS:
C:\ssl>openssl x509 -in certs/iis.cer -out certs/iisx509.cer
This will leave the new certificate in c:sslcertsiisx509.cer - signed, sealed and ready to install!
C:\ssl>
Install the new certificate under IIS
Again, this is described elsewhere on the web - remember that the iisx509.cer file is our certificate response file, and the instructions in Knowledge Base article 228836 should make everything clear.
APPENDIX B: CUSTOMIZATION
Horde has quite a bit of customization options, and while many settings can be configured by the users (such as how often to refresh to check for mail, how to notify of new mail, etc.), much more can be done by tweaking the backend.
By default, Horde comes with a rather purple-based theme, which you may or may not like. Remember all those html.php configuration files you probably noticed back when you were doing the configuration? Well, you can modify the main html.php and the html.php in your IMPconfig directory to have your own Horde Theme Page. There are also downloadable themes found on the net.
Add this page to your favorite Social Bookmarking websites
