Aerospace Software Ltd.

Citadel How-to Guide

For Mandriva Linux 10.2, 2005LE

Scope

Configuration of a mail system on Linux is notoriously difficult. The Postfix mail transport system is an enormous improvement over Sendmail, but it too suffers from configuration option overload. Note that I'm speaking as someone who actually edited a Sendmail configuration file by hand a few times - something that used to earn a common Geek the right to grow a Guru beard...

I have meant to write a guide on mail system installation for a small business, but time and again, I found that it is imposible, since I always get into a position where I have to run little experiments to figure out how to make the darn system work and then eventually, when I do get it to work, I'm not quite sure anymore, what I did to get to that point!

It came to pass a few weeks ago, that I wanted to install an ultimate mail system - a Groupware System. Something with POP and IMAP mail, Calendars and a Discussion forum. I looked at Kolab and after reading the web site for a few days, I still could not figure out where to begin. I then moved on to PhpGroupware thinking that Apache with PHP should be easy since I have used it for many other applications, but after a few days of banging my head, I looked around for a less torturous system again.

Enter Citadel. What a pleasant surprise! If ever there was a Groupware Mail System that can do absolutely everything and Just Works (TM), then this is it. It turned out that a basic installation of Citadel takes about 15 minutes. This is unbelievable - setting up any other mail system with only half the functionality will take a whole week!

Furthermore, Citadel is highly scalable and efficient. The back end is a Berkeley database. It only stores one copy of a message, so if a message is forwarded to everyone in the company, then it won't gobble up the whole disk drive. Multiple Citadel servers can be hooked together and will replicate mail between them if you need to spread the load in a truly large corporation. It has its own IMAP, SMTP and Web server and did I mention that It Just Works?

With Citadel, you can configure any mail client to use IMAP or POP, but the web interface is so good, that most people will probably only use a browser for access and handle mail, calendars and chat all via their favourite browser and simply not bother with a mail client.

Of course, each system has its place in life. If you need a shared system with multiple, virtual domains running on one machine, then maybe use Postfix (though Citadel does that very well too!), but if you need a private groupware system, then Citadel really comes into its own.

Note that I've run the whole thing on a little 800MHz netbook Eee PC 701 as a demo system (http://aeronetworks.ca/eeepc-mdv-howto.html). The system appears to be good quality code.

Enough chatting. Let's dive right in. Here is how.

Requirements

Do a very basic Mandriva installation. You don't need any servers and databases. Don't install Postfix, Mailman, IMAP, POP or Apache. If those things are installed, disable them. Citadel is self contained. It comes with everything you need, including the kitchen sink. I said that It Just Works and I really mean it - honest, really, believe me... :-)

Citadel is designed to be used as a standalone mail system, exposed to the internet, with its own IP address. Its configuration is very simple and for 99% of users, it is a dream come true. If you are a member of that remaining 1% with a disjunct mail system, behind a firewall with some blocked ports, then you will have some more work to do. In extreme cases, you may have to put Citadel behind Postfix and Fetchmail to get it to do your bidding, but that is really the odd exception and it has special hooks to allow you to do that.

Easy Install

More information on Easy Install is available on the web at http://easyinstall.citadel.org

The main Citadel web site is here http://www.citadel.org

Before you begin, ensure that your machine has a fully qualified domain name of the form "mail.example.com" and that the DNS resolves forward and reverse, otherwise Citadel won't be able to send mail on the internet. Once Citadel is installed, it forever remembers this domain name and if you ever need to change it, you need to re-install Citadel. Just running 'setup' again, won't help. Draco dormiens nunquam titillandus.

Open a console, log in as root and run the following script:

$ su -
password
# curl http://easyinstall.citadel.org/install | sh

and answer the following questions:
Configure Citadel yadda, yadda: y
Admin user: admin
Citadel user: citadel
IP: 0.0.0.0
TCP port: 504
Auto start: y
Now run Webcit yadda, yadda... there is no whatever add one: y
On which port yadda yadda: 80
HTTPS port: 443
long wait...

Fifteen to twenty minutes later, you can log in at http://localhost

Basic Configuration

The first time, log in as 'admin' and set the password, click 'New user' and La Voila!

That is pretty much it, the system should now work and you can log in at http://localhost and create more users.

A word of warning though - do create more than one Administrator (Aide) user. It is possible to delete the administrator user. I did that. Don't ask me why. Let's just say that I won't do it again...

Advanced Setup

Now is the time to read the manual... ;-)

Install Spam Assassin

Installation of Spam Assassin is a typical Perl dependency nightmare. You need to install a large menagerie of Perl modules to get Spam Assassin to work. You also need Razor2 and DCC if you want Spam Assassin to be effective.

Go to http://search.cpan.org and download the following modules, make and install them in this order:

IO-Zlib-1.04.tar.gz          
Algorithm-Diff-1.1901.zip
Text-Diff-0.35.tar.gz
Archive-Tar-1.26.tar.gz      
IO-Socket-SSL-0.97.tar.gz    
Socket6-0.19.tar.gz
IO-Socket-INET6-2.51.tar.gz  
Net-Ident-1.20.tar.gz
IP-Country-2.20.tar.gz       
Net-IP-1.24.tar.gz
Net-DNS-0.53.tar.gz
Net-CIDR-Lite-0.18.tar.gz
Sys-Hostname-Long-1.4.tar.gz
Mail-SPF-Query-1.997.tar.gz
Mail-SpamAssassin-3.1.0.tar.gz

Make and install each of the above with:

# tar -zxvf whatever
# cd whatever
# perl Makefile.PL
# make
# make test
# make install
# cd ..

Go to http://www.rhyolite.com/anti-spam/dcc/ and download:

dcc.tar.Z

Make and install with:

# tar -zxvf dcc[tab]
# cd dcc[tab]
# ./configure
# make
# make install
# cd ..

Go to http://razor.sourceforge.net/ and download:

razor-agents-2.77.tar.bz2

Make and install with:

# tar -jxvf razor[tab]
# cd razor[tab]
# perl Makefile.PL
# make
# make test
# make install
# cd ..

Configure DCC

Test DCC with:

/var/dcc/libexec/dccifd -b -d

It should run, connect and be happy. Quit with Ctrl-C. Add a line to the bottom of /etc/rc.d/rc.local so it will run when you reboot:

# /var/dcc/libexec/dccifd

and run DCC as a daemon

# /var/dcc/libexec/dccifd

Configure Spam Assassin

At the end of /etc/rc.d/rc.local add this line:

/usr/bin/spamd -d

If you would now run spamd (without the -d), you will see that it complains about DCC. Edit file /etc/mail/spamassassin/local.cf last line so it reads:

dcc_home  /var/dcc

Now edit file /etc/mail/spamassassin/v310.pre and uncomment the two load plugin lines for DCC and Razor2. If you now run spamd (without the -d), it should be happy and tell you that the server started and spawned a child and so on. Kill it with Ctrl-C, then run it as a daemon:

# spamd -d

It should quietly go into the background.

Hook Spam Assassin into Citadel

We still have to add ClamAV, but lets give it a whirl to see how it goes so far. Log into Citadel as admin and go to Administration, Domain names and Internet, then set the Spam Assassin hook to 127.0.0.1.

Now if all the gods are smiling kindly upon you, Spam Assassin will remove your junk mail. This can be hard to verify. Look at the log files in /var/log. I'll post some more details, once I figured it out myself.

Install ClamAV

The recommended way to hook ClamAV into the system, is via a Spam Assassin plugin, as described here: http://wiki.apache.org/spamassassin/ClamAVPlugin

First go to http://www.clamav.net and download the file clamav-0.87.tar.gz then install and configure as follows:

# tar -zxvf clam[tab]
# cd clam[tab]
# ./configure --sysconfdir=/etc
# make
# make install
# cd ..

Now you need to edit the two configuration files, /etc/freshclam.conf and /etc/clamd.conf. All you need to do, is comment out the two lines that read "example" (line 9).

You can run 'freshclam -V' and it should be happy. To keep the system current, put a call to freshclam in /etc/cron.hourly. We do that with a soft link:

# ln -s /usr/local/bin/freshclam /etc/cron.hourly/freshclam

Head over to http://search.cpan.org and find file::scan::clamav. Download File-Scan-ClamAV-1.8.tar.gz compile and install it:

# tar -zxvf File[tab]
# cd File[tabb]
# perl Makefile.PL
# make
# make test
# make install
# cd ..

Create the file clamav.cf and save it in /etc/mail/spamassassin:

loadplugin ClamAV clamav.pm
full CLAMAV eval:check_clamav()
describe CLAMAV Clam AntiVirus detected a virus
score CLAMAV 10

Create the file clamav.pm and save it in /etc/mail/spamassassin:

package ClamAV;
use strict;
use Mail::SpamAssassin;
use Mail::SpamAssassin::Plugin;
use File::Scan::ClamAV;
our @ISA = qw(Mail::SpamAssassin::Plugin);

sub new {
  my ($class, $mailsa) = @_;
  $class = ref($class) || $class;
  my $self = $class->SUPER::new($mailsa);
  bless ($self, $class);
  $self->register_eval_rule ("check_clamav");
  return $self;
}

sub check_clamav {
  my ($self, $permsgstatus, $fulltext) = @_;
  my $clamav = new File::Scan::ClamAV(port => 3310);
  my ($code, $virus) = $clamav->streamscan(${$fulltext});
  my $isspam = 0;
  my $header = "";
  if(!$code) {
    my $errstr = $clamav->errstr();
    Mail::SpamAssassin::Plugin::dbg("ClamAV: Error scanning: $errstr");
    $header = "Error ($errstr)";
  } elsif($code eq 'OK') {
    Mail::SpamAssassin::Plugin::dbg("ClamAV: No virus detected");
    $header = "No";
  } elsif($code eq 'FOUND') {
    Mail::SpamAssassin::Plugin::dbg("ClamAV: Detected virus: $virus");
    $header = "Yes ($virus)";
    $isspam = 1;
  } else {
    Mail::SpamAssassin::Plugin::dbg("ClamAV: Error, unknown return code:
$code");
    $header = "Error (Unknown return code from ClamAV: $code)";
  }
  $permsgstatus->{main}->{conf}->{headers_spam}->{"Virus"} = $header;
  $permsgstatus->{main}->{conf}->{headers_ham}->{"Virus"} = $header;
  return $isspam;
}

1;

Now all we need to do is restart spamd:

# killall spamd
# spamd -d

La Voila! Now you should have a Citadel Groupware System with spam and virus protection.

Citadel and Webcit ports and protocols

Supported Mail Protocols:

SMTP port 25
SMTP over SSL port 465
We also use SMTP alternate port 2525 (To get past ISP blocks)
IMAP port 143
IMAP SSL port 993 (Best)
POP port 110
POP SSL port 992

Supported Calendar protocols:

GroupDAV
iCalendar (Webcal)

If you don't want to use the Web interface:

The best mailer to use is Mozilla Thunderbird, with IMAP and SSL protocols, but Outlook will also do it.
The easiest calendar client to use is Mozilla Sunbird.

Note that Korganizer/Kontact should work with Citadel (use the URL http://mail.example.com/groupdav/), but it is slow to display changes from Citadel and I could not get it to save changes back to Citadel. Mozilla Sunbird is recommended till the Korganizer/Kontact developers get their bugs sorted out.

Mozilla Thunderbird and Sunbird

You can use Thunderbird and Sunbird with Citadel. It works really well with these clients, but while setting up Thunderbird is straight forward, Sunbird is a little obscure.

Install Sunbird, then click File, Subscribe to Remote Calendar, On the network, Next, iCalendar (ICS), Location: http://mail.example.com/groupdav/Calendar, Next, Name: whoever, Next, Finish. If all went well, a username and password dialogue will pop up - enter your data and tell Sunbird to remember it.

To get the calendar from Citadel, click File, Reload remote calendars and to push the changes back to Citadel, click File, Publish calendar.

This simple protocol is however subject to race conditions if there are multiple users of the same calendar.

Uninstall

OK, so you finished playing around, or found that the system is not quite what you want and wish to get rid of it. Delete the following directories and soft link:

# rm -Rf /usr/local/citadel
# rm -Rf /usr/local/ctdlsupport
# rm -Rf /usr/local/webcit
# rm -f /etc/cron.hourly/freshclam

Finally edit and clean up /etc/inittab and /etc/rc.d/rc.local. That should be quite self explanatory. The rest of the stuff - Spam Assassin, DCC, ClamAV and so on, can be left behind with no ill effect. Those things are small and you may want to use them again with Postfix for example.