Documents
Resources
Learning Center
Upload
Plans & pricing Sign in
Sign Out

Baruwa Documentation

VIEWS: 24 PAGES: 45

									Baruwa Documentation
             Release 1.0.0




       Andrew Colin Kissa




               February 19, 2011
                                                                                                                                                 Contents




1   Introduction                                                                                                                                                                                 3

2   Features                                                                                                                                                                                     5

3   Screenshots                                                                                                                                                                                  7

4   Requirements                                                                                                                                                                                 9
    4.1 Baruwa requirements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .                                                                                    9
    4.2 MailScanner requirements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .                                                                                     9

5   Installation                                                                                                                                                                                 11
    5.1 Install Baruwa . . . . . . .         .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   11
    5.2 Configure Baruwa . . . . .            .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   11
    5.3 Configure MailScanner . . .           .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   12
    5.4 Testing . . . . . . . . . . .        .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   14
    5.5 Distribution / OS installation       .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   14

6   Baruwa on Centos/RHEL                                                                                                                                                                        15
    6.1 Install EPEL . . . . . .     .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   15
    6.2 Baruwa rpm install . . .     .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   15
    6.3 Configure MailScanner .       .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   16
    6.4 Configure Baruwa . . .        .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   17

7   Baruwa on Fedora                                                                                                                                                                             19
    7.1 Baruwa rpm install . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .                                                                                   19
    7.2 Configure MailScanner . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .                                                                                     19
    7.3 Configure Baruwa . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .                                                                                      21

8   Baruwa on Ubuntu/Debian                                                                                                                                                                      23
    8.1 Baruwa deb install . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .                                                                                   23
    8.2 Configure MailScanner . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .                                                                                     23
    8.3 Configure Baruwa . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .                                                                                      24

9   Migrate from Mailwatch                                                                                                                                                                       25

10 External authentication                                                                                                                                                                       27
   10.1 Configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .                                                                                   27

11 Distributed setups                                                                                                                                                                            29


                                                                                                                                                                                                  i
12 Other batteries included                                                                                                                                                                            31
   12.1 Quarantine management . . . . . . .                            .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   31
   12.2 Quarantine reports . . . . . . . . . .                         .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   31
   12.3 Database maintenance . . . . . . . .                           .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   31
   12.4 Spamassassin rule description updates                          .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   31
   12.5 PDF reports . . . . . . . . . . . . . .                        .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   32

13 User Documentation                                                                                                                                                                                  33
   13.1 Interface primer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .                                                                                         33

14 Getting Help                                                                                                                                                                                        35
   14.1 How do I do X? Why doesn’t Y work? Where can I go to get help? . . . . . . . . . . . . . . . .                                                                                                 35
   14.2 I think I’ve found a security problem! What should I do? . . . . . . . . . . . . . . . . . . . . . .                                                                                           35

15 Contributing to Baruwa                                                                                                                                                                              37
   15.1 Reporting bugs . .     .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   37
   15.2 Submitting patches     .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   37
   15.3 Documentation . .      .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   37
   15.4 Donations . . . . .    .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   37
   15.5 Translation . . . .    .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   .   38

16 Upgrading                                                                                                                                                                                           39
   16.1 1.0.1 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .                                                                                        39

17 Older documentation                                                                                                                                                                                 41




ii
                                                                     Baruwa Documentation, Release 1.0.0


Baruwa (swahili for letter or mail) is a web 2.0 MailScanner front-end.
It provides an easy to use interface for managing a MailScanner installation. It is used to perform operations
such as releasing quarantined messages, bayesian learning, whitelisting and blacklisting addresses, monitoring the
health of the services etc. Baruwa is implemented using web 2.0 features (AJAX) where deemed fit, graphing is
also implemented on the client side using SVG, Silverlight or VML. Baruwa has full support for i18n, letting you
support any language of your choosing.
It includes reporting functionality with an easy to use query builder, results can be displayed as message lists or
graphed as colorful and pretty interactive graphs.
Custom MailScanner modules are provided to allow for logging of messages to the mysql database with SQLite
as backup, managing whitelists and blacklists and managing per user spam check settings.
Baruwa is open source software, written in Python/Perl using the Django Framework and MySQL for storage, it
is released under the GPLv2 and is available for free download.




Contents                                                                                                         1
Baruwa Documentation, Release 1.0.0




2                                     Contents
                                                                                                   CHAPTER 1




                                                                              Introduction


Baruwa (swahili for letter or mail) is a web 2.0 MailScanner front-end.
It provides an easy to use interface for managing a MailScanner installation. It is used to perform operations
such as releasing quarantined messages, bayesian learning, whitelisting and blacklisting addresses, monitoring the
health of the services etc. Baruwa is implemented using web 2.0 features (AJAX) where deemed fit, graphing is
also implemented on the client side using SVG, Silverlight or VML. Baruwa has full support for i18n, letting you
support any language of your choosing.
It includes reporting functionality with an easy to use query builder, results can be displayed as message lists or
graphed as colorful and pretty interactive graphs.
Custom MailScanner modules are provided to allow for logging of messages to the mysql database with SQLite
as backup, managing whitelists and blacklists and managing per user spam check settings.
Baruwa is open source software, written in Python/Perl using the Django Framework and MySQL for storage, it
is released under the GPLv2 and is available for free download.




                                                                                                                 3
Baruwa Documentation, Release 1.0.0




4                                     Chapter 1. Introduction
                                                                                            CHAPTER 2




                                                                                 Features


• AJAX support for most operations
• Reporting with AJAX enabled query builder
• I18n support, allows use of multiple languages
• Interactive SVG graphs and PDF reports
• Archiving of old message logs
• SQLite backup prevents data loss when MySQL is down
• MTA integration for relay domains and transports configuration
• Multi user profiles (No restrictions on username format)
• User profile aware white/blacklist management
• Ip / network addresses supported in white/blacklist manager
• Easy plug-in authentication to external authentication systems (POP3, IMAP and SMTP supported out of
  the box)
• Tools for housekeeping tasks (quarantine management, rule updates, quarantine notifications, etc)
• Works both with and without Javascript enabled (graphs require Javascript)




                                                                                                     5
Baruwa Documentation, Release 1.0.0




6                                     Chapter 2. Features
                                            CHAPTER 3




                                      Screenshots


Screenshots are on our Flickr page.




                                                    7
Baruwa Documentation, Release 1.0.0




8                                     Chapter 3. Screenshots
                                                                       CHAPTER 4




                                                             Requirements



4.1 Baruwa requirements

  • Python >= 2.4
  • Django >= 1.1.1
  • MySQLdb >= 1.2.1p2
  • GeoIP
  • iPy
  • Any Web server that can run Django (Apache/mod_wsgi recommended)
  • MySQL
  • Dojo toolkit
  • Reportlab
  • Lxml
  • UUID (Only for python 2.4)
  • Sphinx (Optional - to build documentation)


4.2 MailScanner requirements
  • DBI
  • DBD-MySQL
  • DBD-SQLite




                                                                               9
Baruwa Documentation, Release 1.0.0




10                                    Chapter 4. Requirements
                                                                                            CHAPTER 5




                                                                           Installation



5.1 Install Baruwa

Download the Baruwa source and untar it:

# tar xzvf baruwa-<version>.tar.gz
# cd baruwa-<version>

Make sure you have the required packages installed then proceed. The following commands should be run as a
privileged user.
Create the database:

# mysqladmin -u root -p create baruwa

Create a Mysql user for baruwa
Run the command from the mysql prompt:

mysql> GRANT ALL ON baruwa.* TO baruwa@localhost IDENTIFIED BY ’<password>’;
mysql> flush privileges;

Install Baruwa
Run:

# python setup.py install



5.2 Configure Baruwa

Configure the Baruwa settings
Edit the Baruwa settings.py file:

# baruwa_path=$(python -c "from distutils.sysconfig import get_python_lib; print get_python_lib()"
# vi $baruwa_path/baruwa/settings.py

Set the following options:




                                                                                                       11
Baruwa Documentation, Release 1.0.0



DATABASE_NAME = ’baruwa’
DATABASE_USER = ’baruwa’
DATABASE_PASSWORD = ’<password>’
DATABASE_HOST = ’localhost’

Populate the database and create admin user:

# $baruwa_path/baruwa/manage.py syncdb

The syncdb command populates your SQL database and allows you to create the admin user.
Edit the settings.py file and make configuration changes to suit your site.:

# vi $baruwa_path/baruwa/settings.py

Link to the dojo toolkit:

# ln -s /path/to/dojo $baruwa_path/baruwa/static/js
# ln -s /path/to/dojox $baruwa_path/baruwa/static/js
# ln -s /path/to/dijit $baruwa_path/baruwa/static/js

Configure the Web server
Apache/mod_wsgi
Make sure mod_wsgi is enabled, uncomment the following line in /etc/httpd/conf.d/wsgi.conf:

LoadModule wsgi_module modules/mod_wsgi.so

Use the sample configuration provided (extras/baruwa-mod_wsgi.conf) as a template. Copy to your apache con-
figuration directory usually /etc/httpd/conf.d
Make sure that your apache is configured for name based virtual hosting such that you can run other sites on the
same box if you wish to.
Edit /etc/httpd/conf.d/baruwa-mod_wsgi.conf and set ServerName to the hostname you will use to access baruwa
Restart apache for the configuration to take effect.:

# /etc/init.d/httpd reload

Lighttpd
Use the generic django instructions at http://docs.djangoproject.com/en/1.1/howto/deployment/fastcgi/#lighttpd-
setup
Nginx
Use the nginx instructions at http://wiki.nginx.org/NginxDjangoFastCGI
Cherokee
Use the cherokee cookbook instructions at http://www.cherokee-project.com/doc/cookbook_django.html


5.3 Configure MailScanner

Edit and install BaruwaSQL.pm
Edit extras/BaruwaSQL.pm and set the variables:




12                                                                                  Chapter 5. Installation
                                                                  Baruwa Documentation, Release 1.0.0



my   ($db_name)       =   ’baruwa’;
my   ($db_host)       =   ’localhost’;
my   ($db_user)       =   ’baruwa’;
my   ($db_pass)       =   ’<password>’;
my   ($sqlite_db)     =   "/var/spool/MailScanner/incoming/baruwa.db";

Copy it to the MailScanner custom functions directory:

# confdir=$(/usr/sbin/Quick.Peek ’Custom Functions Dir’ /etc/MailScanner/MailScanner.conf)
# cp extras/BaruwaSQL.pm $confdir/

Next edit the MailScanner config file /etc/MailScanner/MailScanner.conf, you need to make sure that the following
options are set:

Quarantine User = exim (Or what ever your "Run As User" is set to)
Quarantine Group = apache (or your webserver user if not apache)
Quarantine Permissions = 0660
Quarantine Whole Message = yes
Quarantine Whole Message As Queue Files = no
Detailed Spam Report = yes
Include Scores In SpamAssassin Report = yes
Always Looked Up Last = &BaruwaSQL

To actually quarantine and later process messages with in baruwa, set ‘store’ as one of your keywords for the
“Spam Actions” and “High Scoring Spam Actions” MailScanner options
Integrate SQL Blacklists/Whitelists
Edit extras/BaruwaLists.pm and set the variables:

my   ($db_name)   =   ’baruwa’;
my   ($db_host)   =   ’localhost’;
my   ($db_user)   =   ’baruwa’;
my   ($db_pass)   =   ’<password>’;

Copy it to the MailScanner custom functions directory:

# confdir=$(/usr/sbin/Quick.Peek ’Custom Functions Dir’ /etc/MailScanner/MailScanner.conf)
# cp extras/BaruwaLists.pm $confdir/

Next edit the MailScanner config file /etc/MailScanner/MailScanner.conf, and set the following options:

Is Definitely Not Spam = &BaruwaWhitelist
Is Definitely Spam = &BaruwaBlacklist

Integrate per user settings
Edit extras/BaruwaUserSettings.pm and set the variables:

my   ($db_name)   =   ’baruwa’;
my   ($db_host)   =   ’localhost’;
my   ($db_user)   =   ’baruwa’;
my   ($db_pass)   =   ’<password>’;

Copy it to the MailScanner custom functions directory:

# confdir=$(/usr/sbin/Quick.Peek ’Custom Functions Dir’ /etc/MailScanner/MailScanner.conf)
# cp extras/BaruwaUserSettings.pm $confdir

Edit the MailScanner config file /etc/MailScanner/MailScanner.conf, and set the following options:




5.3. Configure MailScanner                                                                                   13
Baruwa Documentation, Release 1.0.0




Required SpamAssassin Score = &BaruwaLowScore
High SpamAssassin Score = &BaruwaHighScore

If you want users to be able to turn off spam checks for their own profiles, set the following options:

Spam Checks = &BaruwaShouldScan

Apply configuration changes
Restart up MailScanner:

# /etc/init.d/MailScanner restart



5.4 Testing

Verify that is working
Check your log files you should see
Baruwa SQL logger:

Aug     9 18:58:27 localhost MailScanner[8470]: Logging message 1OiVg7-0003zS-9s to Baruwa SQL
Aug     9 18:58:27 localhost MailScanner[11052]: 1OiVg7-0003zS-9s: Logged to Baruwa SQL

Baruwa Lists:

Aug 9 18:32:42 localhost MailScanner[27260]: Starting Baruwa whitelists
Aug 9 18:32:42 localhost MailScanner[27260]: Read 6 whitelist items
Aug 9 18:32:42 localhost MailScanner[27260]: Ip blocks whitelisted 192.168.1.0/24 192.168.2.0/24 x

Baruwa User settings:

Aug    9   15:00:03   localhost   MailScanner[25708]:        Baruwa    - Populating spam score settings
Aug    9   15:00:03   localhost   MailScanner[25708]:        Read 1    spam score settings
Aug    9   14:59:53   localhost   MailScanner[25668]:        Baruwa    - Populating high spam score settings
Aug    9   14:59:53   localhost   MailScanner[25668]:        Read 1    high spam score settings

Point your browser to http://hostname_used login with admin user and password and start working. You can now
use the interface to add users, domains and process messages, etc etc.


5.5 Distribution / OS installation

      • Baruwa on Centos/RHEL.
      • Baruwa on Fedora.
      • Baruwa on Ubuntu/Debian.




14                                                                                     Chapter 5. Installation
                                                                                                CHAPTER 6




                                       Baruwa on Centos/RHEL


The Baruwa rpm that is provided only supports apache out of the box, if you are running a different web server,
please install from source or rebuild the source rpm to support your web server.


6.1 Install EPEL

The EPEL repo provides packages which are in Fedora but no yet included in RHEL/CENTOS. Django is shipped
by the EPEL repo. Instructions on installing it can be found on EPEL


6.2 Baruwa rpm install

Due to the fact that the shipped MySQLdb module shipped on Centos/RHEL <= 5.x is too old, use the updated
rpm that i supply from http://topdog-software.com/oss/MySQL-python/ or install from source:

# yum --nogpgcheck localinstall MySQL-python-<version>.rpm

Now proceed and install the other dependencies:

# yum install mysql-server python-IPy python-GeoIP Django mod_wsgi python-uuid python-lxml

Install the python-reportlab rpm from http://www.topdog-software.com/oss/python-reportlab/:

# yum --nogpgcheck localinstall python-reportlab-<version>.rpm

Install the dojo rpm from http://topdog-software.com/oss/dojo/:

# yum --nogpgcheck localinstall dojo-1.4.3-1.noarch.rpm

Download the Baruwa rpm from http://www.topdog-software.com/oss/baruwa/ and install:

# yum --nogpgcheck localinstall baruwa-<version>.noarch.rpm

Create the database:

# mysqladmin -u root -p create baruwa

Create the database user:




                                                                                                            15
Baruwa Documentation, Release 1.0.0




mysql> GRANT ALL ON baruwa.* TO baruwa@localhost IDENTIFIED BY ’<password>’;
mysql> flush privileges;



6.3 Configure MailScanner

It is assumed that you have a working MailScanner system already installed and configured, if you are installing
from scratch please refer to their documentation on how to install and configure MailScanner.
Edit /usr/lib/baruwa/BaruwaSQL.pm and set the variables:

my   ($db_name)       =   ’baruwa’;
my   ($db_host)       =   ’localhost’;
my   ($db_user)       =   ’baruwa’;
my   ($db_pass)       =   ’<password>’;
my   ($sqlite_db)     =   "/var/spool/MailScanner/incoming/baruwa.db";

Next edit the MailScanner config file /etc/MailScanner/MailScanner.conf, you need to make sure that the following
options are set:

Quarantine User = exim (Or what ever your "Run As User" is set to)
Quarantine Group = apache (or your webserver user if not apache)
Quarantine Permissions = 0660
Quarantine Whole Message = yes
Quarantine Whole Message As Queue Files = no
Detailed Spam Report = yes
Include Scores In SpamAssassin Report = yes
Always Looked Up Last = &BaruwaSQL

To actually quarantine and later process messages with in baruwa, set ‘store’ as one of your keywords for the
“Spam Actions” and “High Scoring Spam Actions” MailScanner options
Integrate SQL Blacklists/Whitelists
Edit /usr/lib/baruwa/BaruwaLists.pm and set the variables:

my   ($db_name)   =   ’baruwa’;
my   ($db_host)   =   ’localhost’;
my   ($db_user)   =   ’baruwa’;
my   ($db_pass)   =   ’<password>’;

Next edit the MailScanner config file /etc/MailScanner/MailScanner.conf, and set the following options:

Is Definitely Not Spam = &BaruwaWhitelist
Is Definitely Spam = &BaruwaBlacklist

Integrate per user settings
Edit /usr/lib/baruwa/BaruwaUserSettings.pm and set the variables:

my   ($db_name)   =   ’baruwa’;
my   ($db_host)   =   ’localhost’;
my   ($db_user)   =   ’baruwa’;
my   ($db_pass)   =   ’<password>’;

Link the BaruwaUserSettings module:

ln -s /usr/lib/baruwa/BaruwaUserSettings.pm /usr/lib/MailScanner/MailScanner/CustomFunctions/

Edit the MailScanner config file /etc/MailScanner/MailScanner.conf, and set the following options:


16                                                                  Chapter 6. Baruwa on Centos/RHEL
                                                                     Baruwa Documentation, Release 1.0.0




Required SpamAssassin Score = &BaruwaLowScore
High SpamAssassin Score = &BaruwaHighScore

If you want users to be able to turn off spam checks for their own profiles, set the following options:

Spam Checks = &BaruwaShouldScan

Apply configuration changes
Restart up MailScanner:

# /etc/init.d/MailScanner restart

Verify that is working
Check your log files you should see
Baruwa SQL logger:

Aug    9 18:58:27 localhost MailScanner[8470]: Logging message 1OiVg7-0003zS-9s to Baruwa SQL
Aug    9 18:58:27 localhost MailScanner[11052]: 1OiVg7-0003zS-9s: Logged to Baruwa SQL

Baruwa Lists:

Aug 9 18:32:42 localhost MailScanner[27260]: Starting Baruwa whitelists
Aug 9 18:32:42 localhost MailScanner[27260]: Read 6 whitelist items
Aug 9 18:32:42 localhost MailScanner[27260]: Ip blocks whitelisted 192.168.1.0/24 192.168.2.0/24 x

Baruwa User settings:

Aug   9   15:00:03   localhost    MailScanner[25708]:        Baruwa    - Populating spam score settings
Aug   9   15:00:03   localhost    MailScanner[25708]:        Read 1    spam score settings
Aug   9   14:59:53   localhost    MailScanner[25668]:        Baruwa    - Populating high spam score settings
Aug   9   14:59:53   localhost    MailScanner[25668]:        Read 1    high spam score settings



6.4 Configure Baruwa

Edit the baruwa settings.py:

# baruwa_path=$(python -c "from distutils.sysconfig import get_python_lib; print get_python_lib()"
# vi $baruwa_path/baruwa/settings.py

And set the mysql database details:

DATABASE_ENGINE = ’mysql’
DATABASE_NAME = ’baruwa’
DATABASE_USER = ’baruwa’
DATABASE_PASSWORD = ’<baruwa_password>’
DATABASE_HOST = ’localhost’

Create the baruwa admin user and populate the database:

# $baruwa_path/baruwa/manage.py syncdb

Edit the settings.py file and make configuration changes to suit your site.:

# vi $baruwa_path/baruwa/settings.py




6.4. Configure Baruwa                                                                                     17
Baruwa Documentation, Release 1.0.0


Setup Web server
Edit your apache configurations to enable virtual hosting if not enabled already. Then set the correct hostname in
/etc/httpd/conf.d/baruwa.conf:

# change to your hostname
ServerName baruwa-alpha.local

Make sure mod_wsgi is enabled, uncomment the following line in /etc/httpd/conf.d/wsgi.conf:

LoadModule wsgi_module modules/mod_wsgi.so

Restart apache and point your browser to the hostname url.




18                                                                   Chapter 6. Baruwa on Centos/RHEL
                                                                                                CHAPTER 7




                                                           Baruwa on Fedora


The Baruwa rpm that is provided only supports apache out of the box, if you are running a different web server,
please install from source or rebuild the source rpm to support your web server.


7.1 Baruwa rpm install

Install the dojo rpm from http://topdog-software.com/oss/dojo/:

# yum --nogpgcheck localinstall dojo-1.4.3-1.fc13.noarch.rpm

Download the rpm from http://www.topdog-software.com/oss/baruwa/
Then proceed and install the rpm:

# yum --nogpgcheck localinstall baruwa-<version>.noarch.rpm

Create the database:

# mysqladmin -u root -p create baruwa

Create the database user:

mysql> GRANT ALL ON baruwa.* TO baruwa@localhost IDENTIFIED BY ’<password>’;
mysql> flush privileges;



7.2 Configure MailScanner

It is assumed that you have a working MailScanner system already installed and configured, if you are installing
from scratch please refer to their documentation on how to install and configure MailScanner.
Edit /usr/lib/baruwa/BaruwaSQL.pm and set the variables:

my   ($db_name)        =   ’baruwa’;
my   ($db_host)        =   ’localhost’;
my   ($db_user)        =   ’baruwa’;
my   ($db_pass)        =   ’<password>’;
my   ($sqlite_db)      =   "/var/spool/MailScanner/incoming/baruwa.db";




                                                                                                            19
Baruwa Documentation, Release 1.0.0


Next edit the MailScanner config file /etc/MailScanner/MailScanner.conf, you need to make sure that the following
options are set:

Quarantine User = exim (Or what ever your "Run As User" is set to)
Quarantine Group = apache (or your webserver user if not apache)
Quarantine Permissions = 0660
Quarantine Whole Message = yes
Quarantine Whole Message As Queue Files = no
Detailed Spam Report = yes
Include Scores In SpamAssassin Report = yes
Always Looked Up Last = &BaruwaSQL

To actually quarantine and later process messages with in baruwa, set ‘store’ as one of your keywords for the
“Spam Actions” and “High Scoring Spam Actions” MailScanner options
Integrate SQL Blacklists/Whitelists
Edit /usr/lib/baruwa/BaruwaLists.pm and set the variables:

my   ($db_name)    =   ’baruwa’;
my   ($db_host)    =   ’localhost’;
my   ($db_user)    =   ’baruwa’;
my   ($db_pass)    =   ’<password>’;

Next edit the MailScanner config file /etc/MailScanner/MailScanner.conf, and set the following options:

Is Definitely Not Spam = &BaruwaWhitelist
Is Definitely Spam = &BaruwaBlacklist

Integrate per user settings
Edit /usr/lib/baruwa/BaruwaUserSettings.pm and set the variables:

my   ($db_name)    =   ’baruwa’;
my   ($db_host)    =   ’localhost’;
my   ($db_user)    =   ’baruwa’;
my   ($db_pass)    =   ’<password>’;

Link the BaruwaUserSettings module:

ln -s /usr/lib/baruwa/BaruwaUserSettings.pm /usr/lib/MailScanner/MailScanner/CustomFunctions/

Edit the MailScanner config file /etc/MailScanner/MailScanner.conf, and set the following options:

Required SpamAssassin Score = &BaruwaLowScore
High SpamAssassin Score = &BaruwaHighScore

If you want users to be able to turn off spam checks for their own profiles, set the following options:

Spam Checks = &BaruwaShouldScan

Apply configuration changes
Restart up MailScanner:

# /etc/init.d/MailScanner restart

Verify that is working
Check your log files you should see
Baruwa SQL logger:



20                                                                             Chapter 7. Baruwa on Fedora
                                                                    Baruwa Documentation, Release 1.0.0




Aug    9 18:58:27 localhost MailScanner[8470]: Logging message 1OiVg7-0003zS-9s to Baruwa SQL
Aug    9 18:58:27 localhost MailScanner[11052]: 1OiVg7-0003zS-9s: Logged to Baruwa SQL

Baruwa Lists:

Aug 9 18:32:42 localhost MailScanner[27260]: Starting Baruwa whitelists
Aug 9 18:32:42 localhost MailScanner[27260]: Read 6 whitelist items
Aug 9 18:32:42 localhost MailScanner[27260]: Ip blocks whitelisted 192.168.1.0/24 192.168.2.0/24 x

Baruwa User settings:

Aug   9   15:00:03   localhost    MailScanner[25708]:        Baruwa   - Populating spam score settings
Aug   9   15:00:03   localhost    MailScanner[25708]:        Read 1   spam score settings
Aug   9   14:59:53   localhost    MailScanner[25668]:        Baruwa   - Populating high spam score settings
Aug   9   14:59:53   localhost    MailScanner[25668]:        Read 1   high spam score settings



7.3 Configure Baruwa

Edit the baruwa settings.py:

# baruwa_path=$(python -c "from distutils.sysconfig import get_python_lib; print get_python_lib()"
# vi $baruwa_path/baruwa/settings.py

And set the mysql database details:

DATABASE_ENGINE = ’mysql’
DATABASE_NAME = ’baruwa’
DATABASE_USER = ’baruwa’
DATABASE_PASSWORD = ’<baruwa_password>’
DATABASE_HOST = ’localhost’

Create the baruwa admin user and populate the database:

# $baruwa_path/baruwa/manage.py syncdb

Edit the settings.py file and make configuration changes to suit your site.:

# vi $baruwa_path/baruwa/settings.py

Setup Web server
Edit your apache configurations to enable virtual hosting if not enabled already. Then set the correct hostname in
/etc/httpd/conf.d/baruwa.conf:

# change to your hostname
ServerName baruwa-alpha.local

Make sure mod_wsgi is enabled, uncomment the following line in /etc/httpd/conf.d/wsgi.conf:

LoadModule wsgi_module modules/mod_wsgi.so

Restart apache and point your browser to the hostname url.




7.3. Configure Baruwa                                                                                          21
Baruwa Documentation, Release 1.0.0




22                                    Chapter 7. Baruwa on Fedora
                                                                                                CHAPTER 8




                                    Baruwa on Ubuntu/Debian



8.1 Baruwa deb install

Download the deb from http://www.topdog-software.com/oss/baruwa/
The installation process will also configure apache, mysql and baruwa should you choose.
The install asks you for the following info
    • apache virtualhost name (The name used to configure the baruwa apache virtualhost)
    • database host (The hostname or ip of the host running your mysql database)
    • database admin user (A user account with admin access on the database server)
    • database admin password (The password fo the above user)
    • database user (The user baruwa will use to connect to the database)
    • database password (The password for the above)
    • database name (The name of the baruwa database)
    • baruwa admin user (The baruwa admin user)
    • baruwa admin password (The baruwa admin user password)
    • baruwa admin email (The baruwa admin user email address)
Install Baruwa:

# apt-get install gdebi-core
# gdebi baruwa_<version>_all.deb



8.2 Configure MailScanner

Enable the custom functions in your MailScanner                 configuration,   edit   the   configuration   file
/etc/MailScanner/MailScanner.conf and set the following:

Is Definitely Not Spam = &BaruwaWhitelist
Is Definitely Spam = &BaruwaBlacklist
Always Looked Up Last = &BaruwaSQL




                                                                                                            23
Baruwa Documentation, Release 1.0.0


To actually quarantine and later process messages with in baruwa, set ‘store’ as one of your keywords for the
“Spam Actions” and “High Scoring Spam Actions” MailScanner options
Integrate per user settings
Edit the MailScanner config file /etc/MailScanner/MailScanner.conf, and set the following options:

Required SpamAssassin Score = &BaruwaLowScore
High SpamAssassin Score = &BaruwaHighScore

If you want users to be able to turn off spam checks for their own profiles, set the following options:

Spam Checks = &BaruwaShouldScan

Verify that is working
Check your log files you should see
Baruwa SQL logger:

Aug    9 18:58:27 localhost MailScanner[8470]: Logging message 1OiVg7-0003zS-9s to Baruwa SQL
Aug    9 18:58:27 localhost MailScanner[11052]: 1OiVg7-0003zS-9s: Logged to Baruwa SQL

Baruwa Lists:

Aug 9 18:32:42 localhost MailScanner[27260]: Starting Baruwa whitelists
Aug 9 18:32:42 localhost MailScanner[27260]: Read 6 whitelist items
Aug 9 18:32:42 localhost MailScanner[27260]: Ip blocks whitelisted 192.168.1.0/24 192.168.2.0/24 x

Baruwa User settings:

Aug   9   15:00:03   localhost    MailScanner[25708]:        Baruwa    - Populating spam score settings
Aug   9   15:00:03   localhost    MailScanner[25708]:        Read 1    spam score settings
Aug   9   14:59:53   localhost    MailScanner[25668]:        Baruwa    - Populating high spam score settings
Aug   9   14:59:53   localhost    MailScanner[25668]:        Read 1    high spam score settings



8.3 Configure Baruwa

Edit the settings.py file and make configuration changes to suit your site.:

# baruwa_path=$(python -c "from distutils.sysconfig import get_python_lib; print get_python_lib()"
# vi $baruwa_path/baruwa/settings.py

Thats it point your browser to the apache virtualhost url.




24                                                                   Chapter 8. Baruwa on Ubuntu/Debian
                                                                                         CHAPTER 9




                                           Migrate from Mailwatch


Out of the box migration from mailwatch to baruwa is no longer supported as from 1.0.0




                                                                                                25
Baruwa Documentation, Release 1.0.0




26                                    Chapter 9. Migrate from Mailwatch
                                                                                                CHAPTER 10




                                            External authentication


Baruwa supports authentication to external authentication systems. SMTP, POP3, IMAP are supported out of the
box. TLS, APOP are also supported to ensure user authentication details are protected over the wire.
Authentication is setup on a per domain basis.


10.1 Configuration

As the administrator click on the domain name and add an authentication server. The options are
    • Address (Either a hostname or IP address)
    • Protocol (POP3, IMAP, SMTP)
    • Port
    • Enabled
    • Split address (usernames with @ split into user and domain parts user part used to authenticate)




                                                                                                         27
Baruwa Documentation, Release 1.0.0




28                                    Chapter 10. External authentication
                                                                                                 CHAPTER 11




                                                           Distributed setups


Baruwa is capable of running in a distributed setup, The only requirement is that the nodes share session informa-
tion. If you are running your nodes from the same database backend or running multi master replication then this
will work out of the box.




                                                                                                               29
Baruwa Documentation, Release 1.0.0




30                                    Chapter 11. Distributed setups
                                                                                                 CHAPTER 12




                                          Other batteries included


Baruwa provides custom django manage.py commands to enable scripting of house keeping tasks such as quaran-
tine management and Database maintenance.


12.1 Quarantine management

manage.py cleanquarantine

Deletes quarantined files older than QUARANTINE_DAYS_TO_KEEP. QUARANTINE_DAYS_TO_KEEP is
set in the settings.py file


12.2 Quarantine reports

manage.py sendquarantinereports

Generates an email report of the quarantined messages for the past 24 hours, for each user that has quarantine
report enabled.


12.3 Database maintenance

manage.py dbclean

Deletes records older than 60 days from the maillog table of the database, and archives them to the archive table.


12.4 Spamassassin rule description updates

manage.py updatesarules

Updates the Spamassassin rule descriptions in the database.




                                                                                                               31
Baruwa Documentation, Release 1.0.0



12.5 PDF reports

manage.py sendpdfreports

Sends PDF reports by email.




32                                    Chapter 12. Other batteries included
                                                                               CHAPTER 13




                                                     User Documentation



13.1 Interface primer

The interface is a simplified and AJAX is supported for most operations
The following have full AJAX support::
         • Messages
         • Lists
         • Reports


13.1.1 Messages

The messages tab provides access to the following functionality::
         • Recent messages (top 50) automatically refreshed every 60 seconds
         • Full message list, paginated access to all records
         • Quarantine, split into
                   – full quarantine
                   – spam
                   – non spam
         • Archive, paginated access to all archived records
         • Message details with quarantine processing, list operations
                   – message release
                   – bayesian learning
                   – message deletion
                   – whitelist, blacklist from email address or IP address
         • Message release
                   – Automated release from quarantine




                                                                                       33
Baruwa Documentation, Release 1.0.0


13.1.2 Whitelists/Blacklists

The lists tab provides access to the following::
         • Management of black and whitelists


13.1.3 Settings

The settings tab provides access to the following::
         • User accounts management
         • Domain management
                 – SMTP delivery host management
                 – Authentication management
         • Scanner engine configuration


13.1.4 Reports

The settings tab provides access to the following::
         • Running of reports
         • Management of filters
         • Construction of custom queries


13.1.5 Status

The settings tab provides access to the following::
         • System status
                 – Message totals (daily)
                 – Service status
         • Bayesian status
         • Spamassassin lint check


13.1.6 Account

The settings tab provides access to the following::
         • Account management
         • Profile management




34                                                    Chapter 13. User Documentation
                                                                                                CHAPTER 14




                                                                            Getting Help



14.1 How do I do X? Why doesn’t Y work? Where can I go to get
     help?

If the documentation does not contain an answer to your issue try the Baruwa mailing list, Feel free to ask
any questions on installing, configuring, integrating and troubleshooting Baruwa. Please subscribe to the
list at http://lists.baruwa.org/ or if you prefer to use a forum like interface subscribe at http://baruwa-users-
list.963389.n3.nabble.com/


14.2 I think I’ve found a security problem! What should I do?

If you think you’ve found a security problem with Baruwa, please send a message to andrew@topdog.za.net




                                                                                                              35
Baruwa Documentation, Release 1.0.0




36                                    Chapter 14. Getting Help
                                                                                                  CHAPTER 15




                                               Contributing to Baruwa


There are so many ways to help Baruwa’s development,
    • Blog about it.
    • Report bugs and request features
    • Submit patches for new and fixed behaviour
    • Join the mailing lists and share ideas
    • Donate to the project
    • Documentation
    • Translation


15.1 Reporting bugs

Please use the Github issue tracking             system   to    report   bugs   and   request   new      features   at
https://github.com/akissa/baruwa/issues


15.2 Submitting patches

Baruwa source code is maintained in a git repository at Github http://github.com/akissa/baruwa Please submit
your patches to the mailing list and send me a pull request on Github.


15.3 Documentation

The documentation is part of the source, clone the repo make the changes and submit the patches to the mailing
list and send me a pull request on Github.
You can also contribute tips and sightings on the baruwa wiki at Github https://github.com/akissa/baruwa/wiki


15.4 Donations

Donations are appreciated please           use   the   Pledge     system    which     accepts   paypal     payments
http://pledgie.com/campaigns/12056



                                                                                                                    37
Baruwa Documentation, Release 1.0.0



15.5 Translation

Clone the source code from Github, create a new language if it does not exist, translate and test then send me a
pull request on Github




38                                                                   Chapter 15. Contributing to Baruwa
                                                      CHAPTER 16




                                                  Upgrading



16.1 1.0.1

This is a minor upgrade with no schema changes.
   • Backup your settings.py then upgrade.
   • Restore the settings.py.




                                                              39
Baruwa Documentation, Release 1.0.0




40                                    Chapter 16. Upgrading
                                                                                       CHAPTER 17




                                                Older documentation


Previous versions of documentation can be found online at http://www.baruwa.org/old/




                                                                                               41

								
To top