Installation and Configuration of the Horde applications on FreeBSD

From DFWLPiki
Jump to: navigation, search

Scope of this Document

This document provides instruction for installing these mail services, using the FreeBSD ports system: 1) Dovecot - IMAP/IMAPS/POP3 access 2) Procmail for mail delivery to user's ~/Maildir 3) Cyrus-SASL2authd - for SMTP Authentication 3) SpamAssassin - Spam Filtering and subject line tagging 4) The Horde group of applications

Dependent on these goals, will also require Apache 2.2.x and MySQL 5.0 server, and PHP5 (don't forget, PHP5 will require the apache module as well). Sendmail (the default MTA on FreeBSD) is used for mail transport.

This documentation was written against an install using FreeBSD 6.2 and the current version of Horde available in the ports collection (3.1.4_4). To begin this tutorial, you should have already completed a FreeBSD minimal buildout and update, as documented here.

Initial Preparation

To begin, we will first build Apache 2.2.x, and then also the base portion of PHP5. When you build PHP5, don't forget to select the apache module from the configuration options, if you do not, php5 will not work with apache (I also deselect IPv6, as I don't use it).

# cd /usr/ports/www/apache22/
# make install clean
# cd /usr/ports/lang/php5
# make config
# make install clean

We will need to add some lines to /usr/local/etc/apache22/httpd.conf so that the php modules will work. At the end of the LoadModules section of httpd.conf:

AddType application/x-httpd-php .php
AddType application/x-httpd-php-source .phps

Also, append this to the DirectoryIndex line:

index.php

We need to generate SSL keys for the Apache server, so type these commands:

# cd /root
# openssl genrsa -des3 -out server.key 1024
# openssl req -new -key server.key -out server.csr
# openssl x509 -req -days 365 -in /root/server.csr -signkey /root/server.key -out /root/server.crt

Copy the certs to the destination directory.

# cp ~/server.key /usr/local/etc/apache22/
# cp ~/server.crt /usr/local/etc/apache22/

I prefer to remove the passphrase from the cert, otherwise each time apache22 must start, you must enter the passphrase.

# cd /usr/local/etc/apache22/
# cp server.key server.key.orig
# openssl rsa -in server.key.orig -out server.key

Set the proper security on your new keys.

# chmod 0400 /usr/local/etc/apache22/server.key
# chmod 0400 /usr/local/etc/apache22/server.crt

Uncomment this line in the /usr/local/etc/apache22/httpd.conf to call the SSL config (remove the '#' sign)

#Include etc/apache22/extra/httpd-ssl.conf

Add this to /etc/rc.conf to autostart Apache with SSL at boot:

apache22_enable="YES"
apache22_flags="-DSSL"

Next, we build MySQL 5.0 server.

# cd /usr/ports/databases/mysql50-server/
# make install clean 

Set MySQL to start automatically by adding this to /etc/rc.conf:

mysql_enable="YES"

Spamassassin is a great anti-spam tool, and is an integral part of our FreeBSD email server.

# cd /usr/ports/mail/spamass-milter/
# make install clean

The configuration page will pop up, and you won't need to make any changes. TAB down to OK, and hit enter to start the build process. When it completes, you will also need a configuration file. Use an editor to create the file /usr/local/etc/mail/spamassassin/local.cf

rewrite_header Subject *****SPAM*****
report_safe 1
required_score 5.0
use_bayes 1
bayes_auto_learn 1
skip_rbl_checks         0
use_razor2              1
use_pyzor               1
bayes_ignore_header X-Bogosity
bayes_ignore_header X-Spam-Flag
bayes_ignore_header X-Spam-Status

Note, that you can change the "rewrite_header Subject" to customize the rewrite to how you prefer. Also, as time passes, if you decide that too much spam is passing into your inbox, you can decrease the "required_score" to an even lower number (I actually run my mail server with a 3.6!) As always, you should let time and experience decide what is best for your mail server. Also, note that SpamAssassin learns what is and isn't spam over time (with its autolearning features), so it's best to start with the default of 5.0.

Speaking of autolearning, we need to create the folders where this information will be kept.

# mkdir /root/.spamassassin
# chmod 775 /root/.spamassassin
# chown root:spamd /root/.spamassassin

We need SpamAssassin to start automatically, so add this to /etc/rc.conf:

spamd_enable="YES"
spamd_flags="-u spamd"
spamass_milter_enable="YES"

SMTP Authentication is handled via Cyrus-SASL2.

# cd /usr/ports/security/cyrus-sasl2-saslauthd
# make install clean

When the configuration pops up for cyrus-sasl-saslauthd, take the default options that are presented.

Configure saslauthd to load at boot. Add this to the end of /etc/rc.conf:

saslauthd_enable="YES"

Our MDA (Mail Delivery Agent) will be procmail.

# cd /usr/ports/mail/procmail
# make install clean

During this build there might be a pause to manually specify some other options. You probably don't need to add anything else, and you can just hit [enter] to continue. We also need a main Procmail configuration file, so that our mail will deliver in Maildir format. Create /usr/local/etc/procmailrc, and add these lines:

VERBOSE=off
SHELL=/bin/sh
DEFAULT=$HOME/Maildir/
ORGMAIL=$HOME/Maildir/
MAILDIR=$HOME/Maildir/
PMDIR=$HOME/.procmail
LOGFILE=$PMDIR/log

Also, each new user added to the system will need to have a Maildir folder, which is not there by default. Change directory to /usr/share/skel, and then simply use mkdir to create a folder.

# cd /usr/share/skel
# mkdir Maildir
# mkdir .procmail

This will prevent you from having to manually add Maildir and .procmail to each new user as they are added to the system. If you have already created some users on your server, now would be a good time to cd into their home directories, and create Maildirs (don't forget to use chmod to change the owner of the Maildirs you create to the user they belong to!)

Finally, it's time to configure sendmail to work with SpamAssassin and Procmail. First, we add a few lines to /etc/make.conf:

SENDMAIL_CFLAGS=-I/usr/local/include -DSASL=2
SENDMAIL_LDFLAGS=-L/usr/local/lib
SENDMAIL_LDADD=-lsasl2

Then, we enter the /etc/mail directory, and generate our configuration files:

# cd /etc/mail
# make all

Inside /etc/mail, you will find a .mc configuration file named after your server. For example, mine is named antares.dfwlp.com.mc. Open this file in a text editor, and make some space below the "DAEMON_OPTIONS(`Name=IPv4, Family=inet')" section, and paste these lines in:

define(`confAUTH_MECHANISMS',`PLAIN LOGIN')dnl
TRUST_AUTH_MECH(`PLAIN LOGIN')dnl
INPUT_MAIL_FILTER(`spamassassin', `S=local:/var/run/spamass-milter.sock, F=, T=C:15m;S:4m;R:4m;E:10m')
define(`confINPUT_MAIL_FILTERS', `spamassassin')
FEATURE(local_procmail)dnl

The first 2 lines tell Sendmail to require authentication when sending mail through this server from any other computer. The second two lines tell Sendmail to pass all mail through SpamAssassin, and the last line tells Sendmail where to hand off messages for local delivery (to Procmail). After you save the file, then regenerate the config files. Now that these things are done, we need to build the base Sendmail to use SASL2 support.

# cd /usr/src/lib/libsm; make clean; make obj; make depend; make
# cd /usr/src/lib/libsmutil; make clean; make obj; make depend; make
# cd /usr/src/usr.sbin/sendmail; make clean; make obj; make depend; make; make install

Add this line to /etc/rc.conf to allow Sendmail to listen for connetions:

sendmail_enable="YES"

There is one other file in /etc/mail that we need to create by hand. The local-host-names file lists the domain names that your server will accept mail for, and deliver to local users.

# cd /etc/mail
# touch local-host-names

For example, mine has a single line that just says:

dfwlp.com

You should put whatever domain your server will serve in this file. if you have more than one domain to accept email for (for delivery to local users), then each domain would go on a different line.

Finally, the last piece of mail infrastructure we need to add, is Dovecot. This is how we actually retrieve messages off the server.

# cd /usr/ports/mail/dovecot
# make install clean

A configuration will pop up, you can take the defaults, or deselect IPv6 (as I mentioned earlier, I don't use IPv6). By default, Dovecot will support SSL, but the configuration is not built automatically, *AND* on top of that, the script that is included has some errors. We will now correct those errors, and then build our SSL certificates that Dovecot will use.

# cd /usr/local/share/dovecot/

The first file we need to edit, is not erroneous, but is filled with example information. Edit the file dovecot-openssl.cnf and fill in valid values for each field. Mine looks like this:

[ req ]
default_bits = 1024
encrypt_key = yes
distinguished_name = req_dn
x509_extensions = cert_type
prompt = no
[ req_dn ]
# country (2 letter code)
C=US
#  State or Province Name (full name)
ST=Texas
# Locality Name (eg. city)
L=Richardson
# Organization (eg. company)
O=DFWLP
# Organizational Unit Name (eg. section)
OU=MAIL
# Common Name (*.example.com is also possible)
CN=antares.dfwlp.com
# E-mail contact
emailAddress=postmaster@dfwlp.com
[ cert_type ]
nsCertType = server 

The next file we need, has our mis-configuration we need to address. Edit mkcert.sh, and change:

SSLDIR=${SSLDIR-/etc/ssl}

to

SSLDIR=${SSLDIR-/usr/local/etc/dovecot/ssl}

Now, we need to create our target directory.

# mkdir -p /usr/local/etc/dovecot/ssl/certs
# mkdir -p /usr/local/etc/dovecot/ssl/private

To comment on my choice of location for the ../dovecot/.. directories that we just created; I always keep configurations for items from the ports directory in /usr/local/etc/. IMO, this makes server rebuilds easier, that all of my configuration files for applications built from ports are easily found in one convenient place (we do like easier, don't we?). Generally, the only configurations found in the actual /etc, are configurations belonging to items in the FreeBSD base install (for example, sshd). Now, we generate SSL certificates for use with our Dovecot server:

# sh mkcert.sh

That should complete on its own. Last step for Dovecot, is to create the dovecot.conf file. Mine looks like this:

protocols = imap imaps
disable_plaintext_auth = no
ssl_cert_file = /usr/local/etc/dovecot/ssl/certs/dovecot.pem
ssl_key_file = /usr/local/etc/dovecot/ssl/private/dovecot.pem
default_mail_env = maildir:~/Maildir
mail_extra_groups = mail
verbose_proctitle = yes
first_valid_gid = 0
protocol imap {
  imap_client_workarounds = delay-newmail outlook-idle netscape-eoh tb-extra-mailbox-sep
}
auth default {
  mechanisms = plain
  passdb pam {
  }
  userdb passwd {
  }
  user = root
}
dict {
  #quota = mysql:/etc/dovecot-dict-quota.conf
}
plugin {
} 

There are some example dovecot.conf files that you can compare these settings to, if you want to what what and why ive changed some things. If you want to also allow pop3, then you would change the first line to:

protocols = imap imaps pop3

Also, I made another important edit on the 'default_mail_env' line, this tells Dovecot where to look when it serves your users their mail files (don't forget, we specified to Procmail earlier to devlier mail to the users home directory, into a folder called Maildir).

Now add Dovecot to the startup statements in /etc/rc.conf:

dovecot_enable="YES"

So, a quick summary of what we have done so far:

1) Installed from ports: www/apache22, lang/php5 (with apache support), databases/mysql50-server, mail/spamass-milter, security/cyrus-sasl2-saslauthd, mail/procmail, and mail/dovecot.

2) Rebuilt Sendmail to use SMTP-Auth via Cyrus-SASL2.

3) Added these items to /etc/rc.conf so that they automatically start:

apache22_enable="YES"
apache22_flags="-DSSL"
mysql_enable="YES"
spamd_enable="YES"
spamd_flags="-u spamd"
spamass_milter_enable="YES"
saslauthd_enable="YES"
sendmail_enable="YES"
dovecot_enable="YES"

If this is all done we should be able to start all our services:

touch /var/run/spamass-milter.sock
/etc/rc.d/sendmail restart
/usr/local/etc/rc.d/apache22 start
/usr/local/etc/rc.d/mysql-server start
/usr/local/etc/rc.d/sa-spamd start
/usr/local/etc/rc.d/spamass-milter start
/usr/local/etc/rc.d/dovecot start

Those should have all started without any error messages. Once they are running, we are ready to move on to building out Horde suite of web applications!

Building Horde

Horde can be a fairly complicated beast. I highly recommend that you check out and join some Horde mailing lists. They can be found here:

http://www.horde.org/mail/

I would recommend joining horde@lists.horde.org and imp@lists.horde.org. OK.. on to the fun!

cd /usr/ports/www/horde-meta
make install clean

When the configuration windows comes up, we need to add Mimp, Kronolith, and Gollem (Mobile Mail, Calendar, and File manipulation). Next, to compliment Horde, we will also install ImageMagick.

# cd /usr/ports/graphics/ImageMagick
# make install clean

For ImageMagick, just accept the default configuration you are presented with when it pops up. THIS SHOULD COMPLETE THE INSTALLATION PORTION OF HORDE.

Configuration of Horde and Apache

To configure Horde, we need to first add some configuration to Apache. Change directory to to /usr/local/etc/apache22/Includes, and create a new file called httpd-local.conf (this is the file that I keep all my confurations in, seperate from the master httpd.conf file... this is for portability and ease of system recovery).

# cd /usr/local/etc/apache22/Includes
# nano httpd-local.conf

Add this to the httpd-local.conf:

<Directory /usr/local/www/horde>
    AllowOverride None
    Order Allow,deny
    Allow from all
</Directory>
Alias /horde /usr/local/www/horde

...And that's all you need for Apache. Give Apache a restart, and we are done.

# /usr/local/etc/rc.d/apache22 restart

Now we need to create the Horde database in MySQL.

# cd /usr/local/www/horde/scripts/sql

Before we run the script that adds the database, we need to make an edit to the file (change the default password). Look for this section in the file 'create.mysql.sql':

-- IMPORTANT: Change this password!
PASSWORD('horde')

...And change that password to something else. We now need to also set a password for the MySQL root account (this is not the same thing as your system's root account, do you don't need to and shouldn't use the same password as the root user). After the password is set, import the Horde database.

# mysqladmin -u root password newmysqlrootpasswd
# mysql --user=root --password=newmysqlrootpasswd < create.mysql.sql

Both of those commands should complete without any output (and that means they were sucessful). Now we change directory into a couple of our applications were going to be using that require MySQL, and populate their tables.

# cd /usr/local/www/horde/turba/scripts/sql
# mysql --user=root --password=mynewqmysqlpasswd horde < turba.mysql.sql
# cd /usr/local/www/horde/kronolith/scripts/sql
# mysql --user=root --password=mynewmysqlpasswd horde < kronolith.mysql.sql
# cd /usr/local/www/horde/nag/scripts/sql
# mysql --user=root --password=mynewmysqlpasswd horde < nag.sql

Those tthree should also run with no output (again, signifying no errors). Now, its time to test our Horde installation. Open a web browser,and browse to your server. In this tutorial, my server is named antares.dfwlp.com, so make adjustments as necessaryfor your URL.

http://antares.dfwlp.com/horde/test.php

You should see a whole bunch of lines, a lot of green YES's, and a few lines in orange. If that's what you see, you are golden, if you have some red NO's, you have a problem, and need to backup and make sure that everything down this page is installed correctly.

So, now that we are ready to log in, let me make a couple of points. First, the initial log in session will automatically log you in as Administrator. This is a one time use kind of login, and on the Authentication page, you will need to specify an account from your server that will have administrative rights over the horde configuration. I prefer not to use my normal account for this, so I created a user on my system named 'adminis'. More on this in a moment. So, put in your horde URL:

http://antares.dfwlp.com/horde/

Go down to Administration, then Setup. Here, you will see all the modules that we have installed, but which do not yet have configurations. Click on Horde, as there is much to configure here first before we move on to any other modules. I will list by TAB name, some changes you should make (and DON'T click "Generate Horde Configuration" until you have edited all the tabs)

- General - No changed needed.
- Database - Change to MySQL, on refresh, put in the horde username and the password you chose, and down below in the 'database name' field, put 'horde'.
- Authentication - In the administrators field, append your admin user, 'Administrator, adminis'. For 'what backend should we be using' field, change to IMAP, and on reload change 'configuration type to 'seperate values' and 'connection protocol' to imap/ssl/novalidate-cert. Also, change 'port' from 143 to 993 (IMAPS/SSL version of IMAP).
- Sign up - No changes needed.
- Logging - No changed needed.
- Preferences System - Change 'driver configuration' to 'SQL Server', and leave the refreshed fields on their default values.
- Datatree system - Change 'what backend should we use for Horde Datatree storage' to 'SQL Server', and take the default values for the refreshed fields.
- Groups - No changes needed, should already be on 'Datatree'.
- Cache System - No changes needed.
- Token System - No changes needed.
- Mailer - No changes needed.
- Virtual File Storage - No changes needed.
- Custom Session Handler - No changes needed.
- Image Manipulation - Insert '/usr/local/bin/convert'.
- Mime Detection - Insert '/usr/local/misc/magic'.
- Hostname Country Lookup - No changes needed.
- Problem Reporting - Change 'Where should problem report emails be sent?' to 'root' (and make sure later that roots email is forwarded to an admin user on the system...), and the 'Horde cannot determine the user's email address' field, change it to the domain you accept email for (mine is dfwlp.com).
- Menu Settings - No changes needed.
- Custom Function Hooks - No changes needed.
- Portal Block Configuratoin - No changes needed.
- IMSP Server Settings - No changes needed.
- Kolab Groupware Server - No changes needed.

OK, and now click on the "Generate Horde Configuration" button. You should see:

Successfully saved the backup configuration file /usr/local/www/horde/config/conf.php.bak.
Successfully wrote /usr/local/www/horde/config/conf.php

OK, now we will visit the tabs of our applications, and generate configurations for those.

- Address Book (Turba): No changes needed, click Generate Configuration.
- Calendar (Kronolith): Put the proper server name and reminder email address under "Reminder Settings", and click Generate Configuration.
- File Manager (Gollem): No changes needed, click Generate Configuration.
- Filters (Ingo): No changes needed, click Generate Configuration.
- Mail (Imp): On the "External Utilities and Menu" tab, in the 'location of the OpenSSL binary on your system' field, insert '/usr/bin/openssl', and click Generate Configuration.
- Mobile Mail (Mimp): No changes needed, click Generate Configuration.
- Tasks (Nag): No changes needed, click Generate Configuration.

After this, you can click logout, and this will be the last time you use the Administrator (with no password) login. Aftger this, you will only be able to change settings using the account you named in the Administrators field earlier.

So, log in with your standard user account, and check your login ability. After you confirm you can log in, log back out, and then back in with your administrator account. Go back to the Administration, Setup, and click on Horde, and then go to the Authentication tab. Change 'What backend should we use for authenticating' from our previous choice of IMAP(s) to 'Let a Horde application handle authentication', and then upon the refresh choose Imp. This will allow us to go straight to our webemail without re-authenticating again.

Now, the final test is to log back in as your normal user, and you will be able to move right to your inbox. You can also open Organizing, Address Book, and test creating a contact. Also test creating an event in the calendar, and creating a task.

There are TON of user configurable options, and youll just need to look at every one of them to set them to suit your individual needs. I will give a couple of hints tho:

1) At the top of the page, click on Folders. Right under 'Folder Navigator', hit the dropdown and Create folder for both a "Sent Items", "Drafts" and "Trash". You can also create any other folders you will need to keep your mail organized here. 2) At the top, click Options (you should now already be on Options for Mail, if not, select it in the drop down to the upper right), and click on "Server and Folder Information", and set the folders for Drafts, Trash, and Create a separate Junk Mail folder here if you want one (otherwise select Trash or whatever you like). 3) Click on Personal Information, and fill in information about yourself. At the bottom of this page, set your Sent Mail folder as well.