Configuration

The configuration, update and management of Baruwa Enterprise Edition systems has been simplified and fully automated using the baruwa-setup utility.

The page describes the configuration of the default standalone system if you are installing a distributed cluster system please refer to Cluster Configuration

StandAlone System

This is the default setup and is used for non clustered setups. All the components are installed on one server. Choose this option if you only want to run one server.

Automated Configuration

Baruwa Enterprise Edition >= 2.0.7 uses an automated wizard based utility called baruwa-setup to configure, update and manage the system. On the first run this utility collects configuration information from the user, performs any required software updates and then configures the system based on the profile selected and the configuration data collected. This simplifies the whole setup and management process so the user does not have to manually edit any configuration files.

The baruwa-setup command is idempotent, meaning it safe to run multiple times and will only make changes if they are required. All future updates and configuration changes to the system should be done using the baruwa-setup command. The utility has a man page that documents all the options available.

A pass phrase is required to secure the authentication information that is collected.

Make sure you choose a strong pass phrase which is easy for you to remember but difficult to guess for others, a long sentence describing a personal experience is a good pass phrase.

To start the configuration process login to the server with the username root and the password you set during installation.

Then issue the baruwa-setup command at the command prompt:

baruwa-setup

The program will ask you to set a passphrase, enter the passphrase and press enter re-enter the same passphrase again to confirm. If the passphrase is accepted the System settings screen below will be displayed.

Warning

Do not loose this passphrase, there is no way to recover it. A reinstallation will be required if you loose the passphrase.

System Settings

This screen configures the basic system settings. The description of the options is as follows:

Option Description
System Type Set this to Standalone
FQDN Hostname This is the Fully qualified domain name This cannot be set to localhost
IP Address The system IP address usually detected
Activation Key Baruwa Enterprise Edition Activation Key
Timezone The system timezone, detected from the system configuration.
Enable clustering Do not check this
Enable Monitoring Check this to enable the Monitoring
../_images/full-system-settings.png

Scanner Settings

This screen sets the email scanner settings, The description of the options is as follows:

Option Description
Organization name
Enter a short identifying name for your organisation
this is used to make the X-Baruwa headers unique for
your organisation Multiple servers within one site
should use an identical value here. It must not
contain any spaces.
Organization full name
Enter the full name of your organisation, this is
used in the signature placed at the bottom of report
messages sent by Baruwa. It can include pretty much
any text you like. You can make the result span
several lines by including “n” sequences in the text.
These will be replaced by line-breaks.
Use Ramdisk
Check this to enable using a RAM disk for mail scanning
This makes scanning more efficient, but it uses 1GB of
RAM. Make sure you provision sufficient RAM.
Store clean mail
Check this if you want to store messages not tagged as
SPAM, Use this option only if it is legal in your country
../_images/full-scanner-settings.png

Management Settings

This screen sets the management account settings, The description of the options is as follows:

Option Description
Username
Administrator username
Password
Administrator password, Only strong passwords will be
accepted use a service such as passwordsgenerators.net
to generate strong passwords
Confirm Password
Renter the Administrator password
Email Address
Administrator email address
../_images/baruwa-settings.png

Management Web Settings

This screen sets the management web interface settings, The description of the options is as follows:

Option Description
Web Hostname
The hostname to be used to access the web interface
Web Aliases
Alternative hostnames to use to access the web
interface. Use a space to separate multiple entries
Load Balancer IP’s
Proxy-Protocol load balancers, space separated IP
Address list
Enable Auth Modules
The external authentication modules to enable
Enable Syslog Logging
Turns on Web logging to syslog
../_images/web-settings.png

Management Web Additional Settings

This screen sets the additional management web interface settings, The description of the options is as follows:

Option Description
Quarantine URL
This is default host url used in quarantine report
links, is overridden by domain settings.
Media URL
This can allow you to host media on a CDN or media
host, leave as default to serve of the same system.
Custom Name
This will replace all occurrences of Baruwa in the web
interface as well.
Custom URL
This creates links to your product page within the web
interface and email reports that are sent out.
../_images/web-additional-settings.png

Management Other Settings

This screen sets other management settings, The description of the options is as follows:

Option Description
Reports Email
The email address used to send out email reports
Send Reports At
The hour at which to send reports, this is localized
to the users location based on their timezone setting
Enable Backups
Enables or disabled the backup system [Baruwa Backups]
Enable Memcache
Enables or disables the Memcached cache system, when
disabled the builtin cache system will be used. The
builtin cache system is more efficient on standalone
systems
Enable SNMP Agent
Enables the SNMP Agent which makes the system status
available via SNMP. This option is ineffective if
monitoring has not been enabled.
../_images/full-mgmt-other-settings-ng.png

Search Index Settings

This screen sets search index settings, The description of the options is as follows:

Option Description
Enable Search
Enables Search functionality
Enable wildcard indexing
Enables Search wildcard indexing, Setting this to true
will generate very large index files.
../_images/full-search-index-ng.png

MTA Settings

This screen sets mta settings, The description of the options is as follows:

Option Description
Mail Hostname
The mail server hostname
Message Size Limit
The max message size to accept
DKIM Selector
Sets the DKIM selector name, used to configure DKIM
signing.
Load Balancer IP’s
Proxy-Protocol load balancers, space separated IP
Address list
Enable SMTP Time Rejection
Enable SMTP rejection of messages which either match
Anti-Virus signatures or exhibit definite SPAM like
charactaristics at SMTP Time without queueing or
logging the message.
Log Load Balancer Connections
Log Load Balancer connections to the MTA log
../_images/full-mta-settings1.png

MTA Additional Settings

This screen sets MTA additional settings, The description of the options is as follows:

Option Description
Enable Syslog Logging
Turns on MTA logging to syslog
Enable Subject Blocklist
Enable the blocking by subject functionality
Enable Anonymizer
Enable the Anonymizer functionality
Enable Global Signatures
Enable Global Signatures
Enable SPF Checks
Enable SPF checking functionality
Enable Reputation Protection
Enables functionality to block abusive outbound
SMTP requests
Enable RBLs
Select the SMTP time DNSBL’s to enable
Enable Reply-To Checks
Enable Empty Reply-To Checks
Enable DMARC Reports
Enable DMARC Reports
../_images/full-mta-settings2.png

MTA More Settings

This screen sets MTA more settings, The description of the options is as follows:

Option Description
Enable SMTP callbacks
Enable SMTP Callback verification for senders who do
not have reverse DNS records configured.
Enable DANE
Enable the DANE protocol support.
Spamhaus Technology DQS Key
The key for enabling Spamhaus Data Query Service (DQS). This is recommended
but optional.
Abusix Mail Intelligence Key
The key for enabling Abusix Mail Intelligence. This is recommended
but optional.
Add Sender Header
Enable the adding of a Sender header to inbound messages
in cases where the envelope address is not the same as
the header “From:” address. This aids users in
identifying address forgery.
Disable Legacy SMTP TLS protocols
Disable the legacy SMTP TLS protocol versions TLS1.0 and
TLS1.1. Setting this option may prevent you from
receiving or sending mail to systems that do not yet
support TLS1.2 and above.
../_images/full-mta-settings3.png

Anti Virus Settings

This screen sets anti virus settings, The description of the options is as follows:

Option Description
Enable Sane Signatures
ClamAV Unofficial Sane signatures to enable
Block Macros
Block documents that contain macros
../_images/av-settings.png

Message Sniffer Settings

This screen sets message sniffer settings, The description of the options is as follows:

Option Description
License ID
Message Sniffer License ID This is emailed to you when
you purchase a subscription
Authentication ID
Message Sniffer Authentication ID This is emailed to
you when you purchase a subscription
../_images/snf-settings.png

MaxMind Settings

This screen sets the MaxMind Settings, The description of the options is as follows:

Option Description
MaxMind Account ID The MaxMind Account ID, refer to How do i get a Maxmind Account ID and License Key ?
MaxMind License Key The MaxMind License Key, refer to How do i get a Maxmind Account ID and License Key ?
../_images/maxmind.png

SSL/TLS Settings

The Baruwa web interface MUST ran over SSL/TLS, other services such as SMTP AUTH only work over SSL/TLS as well. So you need to either purchase a valid SSL certificate or have baruwa-setup automatically request a CertBot certificate or generate a non recognised Builtin certificate for you.

If you do not have a CA issued certificate and do not intend on purchasing one the leave the I have a CA issued Certificate unchecked.

Certbot certificate

The issuance of a CertBot certificate is based on an automated check that verifies that the hostnames specified are under your control. Baruwa performs a precheck to verify that the hostnames resolve to a public IP address on the host itself. If this check fails then the Certbot certificate will not be requested. This check will fail if your public IP address is on another device and you are forwarding connections to a private address on your Baruwa system. To work around that you need to create a check file:

touch /etc/baruwa/acme.enable

For the validation process to succeed, Certbot systems need to be able to connect to port 80 on your system, ensure that that is allowed on your network devices.

If your server is behind the Public IP address and you are using port forwarding, you need to setup hairpin/loopback NAT as well otherwise the validation will fail.

Certbot certificates are only issued to systems of the Standalone System, Web and Mail System and Web Interface System profiles.

Certbot certificates are issued only to the web hostname, web aliases and the mail hostname. Cluster members names are not included in the certificate.

Support for CertBot certificates was added in BaruwaOS 6.8, refer to the ACME TLS Certificates section of the release notes for more information.

Note

It is currently not possible to issue or syncronize certificates in a cluster that uses the same hostname. If you are operating a cluster you should either purchase a Commercial CA issued certificate or use Builtin certificates.

Commercial CA issued certificate

Note

We have partnered with the SSLShop to bring you discounted SSL certificate pricing. RapidSSL CA signed certificates can be purchased at discounted pricing using the Discount coupon “BARUWA” from http://www.sslshop.co.za

If you have a SSL certificate that is issued by a recognised CA and would like Baruwa to use it, install it prior to running baruwa-setup. Please NOTE that you need certificates that cover the web hostname and aliases, and the mail hostname. Please check I have a CA issued Certificate.

The preferred location to install certificates and keys on the server is under /etc/pki. You need to create a directory structure under that and store your certificate under it.

The following example creates a baruwa directory under /etc/pki and stores the certificates and keys there:

mkdir -p /etc/pki/baruwa/{certs,private}

Create the following files

  • /etc/pki/baruwa/certs/baruwa.pem with the contents of your SSL certificate
  • /etc/pki/baruwa/private/baruwa.key with the contents of your SSL private key

If your SSL certificate is signed using an intermediate certificate, you need to append the intermediate certificate to the file /etc/pki/baruwa/certs/baruwa.pem. The server certificate must appear before the intermediate certificate in the combined file.

You need to create additional certificate pairs if your web hostname and mail hostname are not the same.

If you have a wildcard certificate with all your names being subdomains of that domain to which the certificate is issued then you can simply create one pair.

Builtin certificate

The certificate that baruwa-setup generates contains all the relevant system names. The downside to the builtin certificates is that they are signed by the BaruwaCA meaning they will not be recognized by browsers and will generate unknown CA errors in browsers.

../_images/tls1-settings.png

If you left I have a CA issued Certificate unchecked you will be presented with the following screen. You need to fill in the details which are used to create a CA from which the certificate will be issued. The description of the options is as follows:

Option Description
Organization
OpenSSL CA Name
Email Address
OpenSSL email address
Country
OpenSSL country code
Province
OpenSSL province
City
OpenSSL city
../_images/tls2-settings.png

If you checked I have a CA issued Certificate you will be presented with the following screen, you need to specify the locations of your certificates and keys. The description of the options is as follows:

Note

Do not use the hostname of the server to name the certificates or private keys, use the naming convention recommended above.

Option Description
Web Certificate The location of the web certificate file in PEM format
Web Private Key The location of the web private key file in PEM format
Mail Certificate The location of the mail certificate file in PEM format
Mail Private Key The location of the mail private key file in PEM format
../_images/tls3.png

Setup Running

The baruwa-setup program will now ran the setup processes to configure the system. The processes include updating all the packages on the system. If a newer version of baruwa-setup is downloaded and installed, the process will reload the baruwa-setup command. When this happens a notification message with a 30 second countdown timer will be displayed and the baruwa-setup command will reload and display the initial (System Settings) screen. If this happens simply press the next button or the F12 key until you get to the Setup Running screen again.

At this point there is nothing left for you to do until the setup is complete. The program will update the screen with status information as well as logging it to /var/log/messages. If an error occurs the error information will be displayed until you press the enter button and the program will exit.

Warning

If an error occurs while running setup, DO NOT REINSTALL the system copy the error and contact support.

../_images/setup.png

Setup Complete

When the setup is complete the following screen will be displayed simply press enter and the program will exit

../_images/setup-complete.png

To ensure that all the settings are correctly applied reboot the server from the command line using the command:

reboot

Post Configuration

Now that the installation and setup are complete, you need to finalize the setup by Adding a Scanning Node, Adding an Organization, Adding a Domain and Adding an Account. This is done through the management web interface.

The exact sequence to follow is:

  • Add the Node
  • Add an Organization
  • Add a Domain to the Organization
  • Add a delivery server for the Domain
  • Add a Domain Administrator Account for the organization
  • Edit the Organization and assign Domain Administrator to the organization
  • Add any user accounts to the Domain if not using external authentication

Review the DNS, Administrators guide, Email Protection Best Practices and Advanced configuration sections for other configuration and setup options available.