Für ein einfache und schnelle Installation siehe auch: Kurzanleitung zur Installation

The information and procedures described in this installation guide refer to Benno MailArchiv release version 2.x.

This installation guide for the email archiving solution Benno MailArchiv describes all the necessary steps to be performed sequentially for the proper installation of the Benno MailArchiv application on a server system. This installation guide is valid exclusively for software version Benno MailArchiv 2.x.

Die strikte Anwendung dieser detaillierten Installationsanleitung ist insbes. die Errichtung einer Lösung zur rechtssicheren bzw. GoBD-konforme Archivierung aller handels- und steuerrechtlich relevanten E-Mails nach deutschem Recht erforderlich. Diese Installationsanleitung ist Bestandteil der Verfahrensdokumentation zur gesetzeskonformen E-Mail-Archivierung, soweit eine solche implementiert wird.

IMPORTANT NOTE:

Wir weisen hiermit ausdrücklich daraufhin, dass eine GoBD-konforme bzw. rechtssichere Archivierung aller handels- und steuerrechtlich relevanten E-Mails nicht alleine durch die Beachtung und technisch korrekte Umsetzung der hier dargelegten Installationsschritte erreicht werden kann! Jegliche Softwareprodukte zur E-Mail Archivierung (wie Benno MailArchiv und alle anderen) stellen gemäß GoBD nur einen Teil der Lösung einer gesetzes- bzw. GoBD-konformen E-Mail-Archivierung dar, und sind nicht die Lösung selbst!

To set up email archiving that meets the requirements of the German Generally Accepted Accounting Principles (GoBD), further non-technical and organizational measures beyond the software itself are absolutely necessary. Specifically, suitable procedural documentation that complies with the GoBD requirements must be created. This procedural documentation will not be discussed further in this installation guide or in this wiki.

Eine geeignete Verfahrensdokumentation kann nur durch qualifizierte Beratung und ausschließlich kunden-individuell erstellt werden. Bei Fragen hierzu wenden Sie sich gerne an unsere Benno MailArchiv Certified Partner oder direkt an uns.

Both our Certified Partners and we ourselves provide qualified support in creating the process documentation and taking into account all other relevant aspects of the GoBD.

More detailed and further information can be found in our two white papers:

White Paper: What does GoBD-compliant mean?

White Paper: Legal Aspects of Legally Compliant Email Archiving

For further questions, please contact us by email at: support@benno-mailarchiv.de

Diese Installationsanleitung beschreibt, wie Benno MailArchiv 2.x in einer typischen Single-Mandanten Konfiguration eingerichtet wird. Die Einrichtung und Verwaltung einer Multi-Mandanten Konfiguration wird hier beschrieben. Bei Bedarf steht Ihnen unser Professional Services-Team für weitere Einzelheiten hierzu gerne zur Verfügung.

Benno MailArchiv requires the Linux operating system to run. Additionally, Benno MailArchiv requires Java as a runtime environment. The Benno MailArchiv WebApp requires PHP as a runtime environment. Perl is required for command-line user management. All related details are explained below.

Benno MailArchiv arbeitet auch auf relativ kleiner Hardware mit erstaunlicher Geschwindigkeit. Um ein geeigenetes Hardware-Sizing vozunehmen, sind die individuellen Voraussetzungen und Gegebenheiten zu prüfen. Einen Anhaltspunkt für die Performance kann dieser Blog-Beitrag geben. Hier wurden willkürlich E-Mails auf einem älteren Notebook archiviert und volltext-indexiert. Mit einem durchschnittlichen Durchsatz von 13,5 E-Mails pro Sekunde. Die Hardwareanforderungen für Benno MailArchiv sind im Wesentlichen von folgenden Parametern abhängig: Anzahl zu archivierender Mails je Zeiteinheit (bspw. Mailaufkommen bzw. gewünschter Durchsatz pro Minute) Durchschnittliche Anzahl und Größe der E-Mails Komprimierbarkeit der Attachements (JPEG-Bilder, ZIP-Dateien usw. sind bereits komprimierte Datendateien; Office-Dokumente und Textdateien lassen sich i.d.R. wesentlich besser komprimieren) Anzahl und Intensität gleichzeitiger Zugriffe auf die WebApp usw. Als Faustregel können folgende Mindestanforderungen gelten: CPU DualCore oder QuadCore RAM 4 GB Festplattenspeicher: nach Bedarf (Technologie beliebig (lokale HDDs, NAS, SAN o.ä.)

Benno MailArchiv 2.x ist für folgende Betriebssysteme freigegeben: Debian GNU/Linux (das jeweilige stable Release) Univention Corporate Server (UCS), ab Version 4.x.

Ubuntu Server wird in der LTS-Version 14.04, 16.04 und 18.04 unterstützt. Erläuterungen zur Installation unter Ubuntu finden Sie hier.

Auf Nachfrage: SuSE Linux Enterprise Server (SLES) RedHat Enterprise Linux (RHEL).

The Benno MailArchiv backend and the REST interface require a Java environment to operate. This requires a current OpenJDK version on the server.

Laufzeitumgebung für die Benno MailArchiv WebApp Das Benno MailArchiv Frontend ist über PHP, HTML-Templates mit Cascading Style Sheets (CSS) realisiert. Zum Betrieb werden eine aktuelle PHP-Version sowie ein Web-Server benötigt.

Benno MailArchiv 2.x consists of the components named in the graphic above. These components are divided into the following installation packages:

• Core: benno-core, benno-lib
• Backend: benno-archive
• REST interface: benno-rest, benno-rest-lib
• WebApp: benno-web

The benno-lib package contains libraries for the basic installation of Benno MailArchiv.

The benno-core package provides the basic functions for Benno MailArchiv. benno-core is required for both archiving and querying the archive via the REST interface.

The benno-archive package includes the import functions for emails into the archive. benno-archive manages the spool directory (default: /srv/benno/inbox). All *.eml files found there are automatically imported, archived, and then (after successful completion of the archiving operation) deleted from the spool directory.

The benno-rest-lib package provides libraries for the REST interface of Benno MailArchiv.

The benno-rest package includes the REST interface of Benno MailArchiv.

Die Benno MailArchiv-Pakete stehen im Download-Bereich der Web-Site von Benno MailArchiv zur Verfügung.

The download area is freely accessible. The software can be downloaded at any time. Use of Benno MailArchiv is subject to our applicable license terms. Without a valid license key, the functionality of Benno MailArchiv is limited.

During installation, a valid license key must be requested from LWsystems (see details below). The license key entitles the user to use the software permanently and without time restrictions. Within the (typically one-year) software maintenance period, the latest package versions of Benno MailArchiv 2.x can be installed at any time. If newer releases of the software are installed on an existing server without valid software maintenance, the system reverts to demo mode (limited functionality) until either a new license key valid for the release is installed or an older release version compatible with the license key's maintenance period is installed.

To install Benno MailArchiv on Debian, Ubuntu or UCS, the package management of the respective distribution can be used.

Benno MailArchiv steht als App im Appcenter von Univention zur Verfügung und kann direkt über die Weboberfläche der UMC installiert werden.

Zur Installation von Benno MailArchiv muss dem Linux-System lediglich eine weitere Paketquelle hinzugefügt werden. Hierzu muss mit einem Texteditor am Ende der Datei /etc/apt/sources.list folgende Zeile hinzugefügt werden:

deb http://www.benno-mailarchiv.de/download/debian /

Debian-based systems use GNU Privacy Guard (GPG) to verify the authenticity of package sources. The following commands add the Benno MailArchiv package source key to your system:

wget -O - http://www.benno-mailarchiv.de/download/debian/benno.asc | apt-key add -

After adding the Benno MailArchiv package source to the system and the signature key to the package manager, the package lists must now be updated with the following command: `apt-get update`. Afterwards, Benno MailArchiv can be installed via the Debian/Ubuntu/UCS package manager

apt-get install benno-archive benno-rest benno-web

Im Zuge der Installation werden automatisch die beiden Benutzer benno und bennorest angelegt. Das Benno MailArchiv Backend (Archivierung) läuft mit dem Benutzer benno, während der Benno Rest-Daemon mit dem Benutzerkonto bennorest läuft.

Ab Debian 9 und Ubuntu 16.04 muss zusätzlich das Paket php-mbstring installiert werden.

apt-get install php-mbstring systemctl stop apache2 systemctl start apache2

Die Beschreibung für die Installation auf beliebigen Linux-Distributionen finden sie unter Installation aus TGZ-Paketen.

To commission Benno MailArchiv in a typical single-tenant environment, the following configuration settings must be made. The basic configuration of Benno MailArchiv is performed via the following configuration files: /etc/benno/benno.xml and /etc/benno-web/benno.conf

Benno MailArchiv wird im Zuge der Installation von Haus aus so installiert und eingerichtet, dass sofortige Betriebsbereitschaft vorliegt. Es ist lediglich eine Konfigurationseinstellung vorzunehmen, um Benno MailArchiv zu starten: Die Datei /etc/benno-web/rest.conf erstellen und hier eine Zeile der Form SHARED_SECRET = IhrPasswort eingragen. Bitte tragen Sie als Shared Secret eine mindestens 20 Zeichen lange Zeichenkette mit zufälligen Zahlen und Buchstaben Ihrer Wahl ein. Das Shared Secret darf keine deutschen Umlaute (ä, ö, ü, Ä, Ö, Ü, ß) und Sonderzeichen enthalten!

You can create the file by entering the following commands in the console:

echo 'verySecretAndSecurePassword' > /etc/benno/rest.secret history -c chown benno.benno /etc/benno/rest.secret chmod 0440 /etc/benno/rest.secret

Tragen Sie exakt das gleiche Shared Secret anschließend mit dem Prefix SHARED_SECRET = in die Datei /etc/benno-web/rest.conf ein.

echo 'SHARED_SECRET = wholeSecretAndSecurePassword' > /etc/benno-web/rest.conf history -c chgrp www-data /etc/benno-web/rest.conf chmod 0440 /etc/benno-web/rest.conf

Nachdem Sie das Shared Secret eingerichtet haben, muss der Benno REST-Daemon gestartet werden, damit ein Zugriff über die WebApp möglich ist: /etc/init.d/benno-rest start

The start of the REST daemon is logged in the file /var/log/benno/rest.log :

2012-03-21 13:42:19,848 INFO Starting Jetty server from file /etc/benno/jetty.xml 

If the shared secret has not been set, the following error message will be logged:

2012-03-21 13:42:19,952 FATAL Shared secret in /etc/benno/benno.xml not set. 

Wichtiger Hinweis: Wenn sich die Shared Secrets in den beiden Dateien unterscheiden, startet zwar der REST-Daemon ohne Fehlermeldung, aber es ist kein Zugriff von der WebApp auf den Server möglich! In der WebApp erscheint dann die Fehlermeldung „Fehler bei der Abfrage des Benno MailArchiv Servers“

Nach Import der ersten E-Mail steht die volle Funktionalität des Systems für einen Zeitraum von 60 Tagen auch ohne Lizenzdatei zur Verfügung (Demo-Modus). Nach Ablauf des Demo-Zeitraums bzw. ohne gültiges Lizenzfile werden auch weiterhin E-Mails archiviert. Ist der Demo-Modus abgelaufen und keine gültige Lizenz installiert, ist der Zugriff auf die archivierten Mails (Suche und Anzeige) über die WebApp nur möglich, wenn Sie in der Datei /etc/benno-web/benno.conf die Benutzerberechtigungen deaktivieren. Hierdurch wird Benno MailArchiv in den Community Edition Modus umgeschaltet. Achtung! Mit der Deaktivierung dieser Berechtigungen in der Konfigurationsdatei können ALLE Benutzer ALLE E-Mails im Archiv lesen!

Bitte beachten Sie, dass eine kommerzielle Nutzung der WebApp in der Community Edition lizenzrechtlich ausgeschlossen ist und einen Bruch der Lizenzbedingungen darstellt! Details zur Lizenzierung sind im Abschnitt „Lizenzen in Benno MailArchiv“ hier erläutert).

To put Benno MailArchiv into regular operating mode, a valid license is required. The license file is a file containing various information, including the actual license key.

A valid license file can be obtained at any time via the web form (see below). To order the license file, proceed as follows:

To do this, execute the following command:

benno-client --instance-id

This command outputs the system's instance ID, which you specify when requesting a license.

Nutzen Sie das folgende Webformular, um ein gültiges Lizenzfile für Ihre Benno MailArchiv Installation zu erhalten: https://www.benno-mailarchiv.de/lizenz. Das Lizenzfile wird Ihnen per E-Mail zugesendet.

If the email containing the license file has been archived by the Benno MailArchiv system, the license will be automatically recognized the next time the Benno REST Demon is restarted.

Alternativ kann die anhängende Lizenzdatei benno.lic auch auf dem Benno MailArchiv System gespeichert werden.

Copy the license file to /etc/benno/benno.lic and, if necessary, ensure that the file access rights are as follows:

-rw-r--r-- 1 root root 145 Jun 27 2:24 pm /etc/benno/benno.lic 

Von einem Windows-Rechner können Sie die Lizenz per putty installieren.

After you have configured the license file, the Benno REST daemon must be restarted for the license to be activated: /etc/init.d/benno-rest restart. Please check the file /var/log/benno/rest.log to see if the license was recognized correctly. The log file should then contain the following entry:

2012-03-21 13:44:25,183 INFO License in /etc/benno/benno.lic is valid 

If the license file is missing or unreadable, the following error message will be logged:

2012-03-21 13:44:25,183 INFO Cannot check license file: /etc/benno/benno.lic (No such file or directory) 

If the license check fails for other reasons, the following error message will be logged:

2012-03-21 13:44:25,183 WARN License error LICENSE CHECK FAILED 

Benno MailArchiv is now installed and ready to use.

What are the next steps?

• Import emails into the archive
• Log in to the web app and search for emails

Die korrekte Namensauflösung des Hosts, auf dem Benno MailArchiv betrieben wird, ist essentielle Voraussetzung für den Betrieb bzw. die Lizenzierung. Sollten Sie bei der Ermittlung der Informationen für die Bestellung des Lizenzkeys Probleme haben, liegen diese i.d.R. an folgenden Umständen, die einfach gelöst werden können: In der Datei /etc/hosts löst eine IP-Adresse „127.x.x.x“ auf den Hostnamen des Benno-Servers auf (für die IP-Adresse 127.x.x.x (Loopback) kann kein funktionierender Lizenzkey erstellt werden) Der Hostname und der FQDN des Benno-Servers sind in der Datei /etc/hosts nicht oder nicht richtig eingetragen Bitte prüfen Sie, ob der Hostname Ihres Servers in der Datei /etc/hosts korrekt eingerichtet ist. Folgendes Beispiel zeigt, wie eine korrekte Konfiguration beispielhaft aussieht

127.0.0.1 localhost 123.456.78.90 benno.kundendomain.intern benno

Unmittelbar nachdem Sie die Konfiguration in der Datei /etc/hosts auf die richtigen Werte Ihrer Installation eingestellt und die Datei gespeichert haben, können Sie die Namensauflösung mit dem Aufruf

/etc/init.d/benno-rest info 

prüfen. Ist alles richtig, gehen Sie zum vorherigen Schritt („Einspielen des Lizenzfiles“) zurück. Andernfalls schicken Sie die exakte Ausgabe des Kommandos bitte per E-Mail an die Adresse support@benno-mailarchiv.de.

To get Benno MailArchiv up and running, no configuration settings need to be changed after installation! Benno MailArchiv is ready to use immediately after installation. The emails to be archived must be copied to the directory /srv/benno/inbox. They must be readable by the user "benno". Benno MailArchiv requires a valid license file and the configuration of the shared secret to secure server communication between the core and REST (see the previous sections) to start.

Beim Import sehr großer E-Mail-Mengen (bspw. ab ca. 20.000 E-Mails pro Tag und mehr) kann die Java-VM nach längerer Laufzeit nahezu 100% einer CPU belegen. Nach geraumer Zeit werden dann keine keine E-Mails mehr importiert. Im Logfile werden Meldungen in Zusammenhang mit „OutOfMemoryError“ ausgegeben, bspw.: „2012-07-19 08:58:34,419 ERROR de.lwsystems.mailarchive.mailservice.DirectoryWatchService: java.lang.OutOfMemoryError: Java heap space“ Sollte diese Situation auftreten, kann sie einfach durch Zuordnung von mehr Speicher an den benno-archive Dienst behoben werden. Die maximale Speichergröße, die die Java VM alloziert, wird mit der Option „-Xmx“ eingestellt. Mit dem Parameter „-Xmx2500m“ wird dieser Wert bspw. auf 2.500 MB gesetzt. Der Wert kann in der Datei „/etc/default/benno-archive“ in der Variable JAVA_OPTIONS eingestellt werden:

START_ARCHIVE=yes
JAVA_OPTIONS=' -server -Xmx2500m '
DAEMON_ADDRESS='127.0.0.1'
DAEMON_PORT='2555'
DAEMON_ARGS='-c /etc/benno/benno.xml'
USER=benno

The space after the value must also be specified.

Die Konfiguration weiterer Mandanten in Benno MailArchiv erfolgt in der Konfigurationsdatei /etc/benno/benno.xml. Je Mandant ist innerhalb der Struktur configuredarchives eine eigene XML-Struktur containerarchive … /containerarchive mit den Parametern und Daten des jeweiligen Mandanten einzurichten.

In Benno MailArchiv 2.0, the command-line tool benno-useradmin is available for managing users in single-tenant installations. This program allows you to manage users in the local user database. To use benno-useradmin, the packages perl libdbi-perl libdbd-sqlite2-perl are required. The command is part of the benno-web package. When installed on Debian, Ubuntu, or UCS, the aforementioned dependent packages are installed automatically.

Statt der Benno MailArchiv internen Benutzerdatenbank kann die Benutzerverwaltung auch über ein bestehendes LDAP-Directory vorgenommen werden. Für die LDAP-Anbindung steht ein separates Software-Modul zur Verfügung, dass in Benno MailArchiv 2.0.1 zum Standardumfang gehören wird. Die entsprechende Installations- bzw. Konfigurationsanleitung finden Sie hier. Die Anbindung an ODBC-Datenbanken statt LDAP ist ebenfalls möglich. Bitte sprechen Sie uns diesbzgl. bedarfsweise an.

The command-line tool benno-useradmin is currently intended for single-tenant installations of Benno MailArchiv. Multi-tenant installations are primarily related to the use and operation of the Benno MailArchiv Hosting Edition. Experience has shown that these often require individual connections to the respective provisioning or management environment of the hosting provider/ISP, which we implement individually and on a project-specific basis.

The benno-useradmin command can be called with the following parameters:

benno-useradmin [-h] [-l] [-u <username>] [-d|-E] [-D] [-p <password>]
  [-n <name>] [-e <email1,email2, ...>] -C [<container>]
 
  -c <file>          config file (default /etc/benno-web/benno.conf)
  -l                 list all users
 
  -u <username>      username (shows user data if no other options given)
 
 
Add or change user data
  -p <password>      password of the user
  -n <name>          display name of the user
  -e <email,email>   comma separated list of email addresses ('' deletes all)
  -C <container>     container name (default BennoContainer)
 
  -d                 disable user
  -E                 enable user
  -D                 delete user
  -h                 this help
  -v                 print version number

benno-useradmin -u k.klaasen -p completely secret -n “Klaas Klaasen” -e “k.klaasen@firma.com, klaas.klaasen@firma.com”  

benno-useradmin -u k.klaasen -p newpw 

benno-useradmin -u k.klaasen -e 'k.klaasen@firma.com, k.klaasen@firma2.com

Attention! The email addresses will always be completely replaced.

benno-useradmin -u k.klaasen 

benno-useradmin -u k.klaasen -D

Der Zugriff auf die WebApp erfolgt über folgenden URI:

http://benno-server/benno 

The default user is "admin". Please set this user's password before first accessing the system and create corresponding user accounts with appropriate permissions.

benno-useradmin -u admin -p SICHERSPASSWORT 

Standard path for the data and services of Benno MailArchiv.

This is the so-called "spool directory" of Benno MailArchiv. Emails to be archived must be placed individually (one email per file) in this directory. Benno MailArchiv picks up the files individually from here and processes them. After successful processing (archiving and indexing), the mail files are deleted from the directory. Emails to be archived must have the file extension .eml. Emails from all clients can be stored here. Benno MailArchiv automatically distributes the emails into the archives of the different clients based on the configuration settings in the file /etc/benno/benno.xml.

This is the standard directory for storing the various archives and their respective search indexes.

This is the installation directory of the Benno MailArchiv WebApp.

This is the installation directory for the program components of Benno MailArchiv (excluding the Benno MailArchiv WebApp).

The configuration settings for the Benno MailArchiv backend are located in the directory /etc/benno. The configuration files are listed and described below.

Contains the configuration settings for the packages benno-archive and benno-rest. In particular, the various clients and their respective settings, such as file paths, etc., are managed here.

Contains configuration settings for logging and the different log levels of benno-archive. Here you can configure the level of detail with which the various archive operations are logged. Logging can be configured at the following levels: TRACE, DEBUG, INFO, WARN, ERROR, FATAL

Contains configuration settings for logging and the different log levels of benno-rest. Here you can configure the level of detail with which the various query operations to the archive are logged. Logging can be configured at the following levels: TRACE, DEBUG, INFO, WARN, ERROR, FATAL

This is the license file for the Benno MailArchiv installation. It contains the license key type (Standard Edition, Hosting Edition, Evaluation, etc.), the FQDN hostname, the server's IP address, and the expiration date of the current maintenance period. Last but not least, the license key itself is included.

Contains configuration settings for the benno-rest embedded HTTP server. No configuration settings need to be made in this file.

Contains information about the startup configuration of benno-archive, e.g., whether the service should be started automatically when the server starts.

Contains information about the startup configuration of benno-rest, e.g., whether the service should be started automatically when the server starts.

The configuration for the Benno MailArchiv WebApp is located in the directory /etc/benno-web/benno.conf. The configuration files are explained below.

Includes the PHP files of the Bennno MailArchiv WebApp.

Includes the templates of the HTMLfrontend of the Bennno MailArchiv WebApp.

Includes the configuration files for the web frontend (see below).

Contains permission configurations for the components of the Benno MailArchiv WebApp. Do not make any changes to this file!

Die Datei benno.conf enthält die Konfigurationseinstellungen der Benno MailArchiv WebApp sowie das Shared Secret zur abgesicherten Kommunikation mit dem Backend.

In der WebApp können E-Mails jederzeit an eine beliebige Mailadresse weitergeleitet werden. Durch Klick auf die Schaltfläche „Mail weiterleiten“ kann die E-Mail an eine frei definierbare E-Mailadresse weitergeleitet werden. Standardmäßig wird die Mail mit dem Absender-Envelope benno@localhost versendet. Viele Mailserver bzw. MTAs MTA keine E-Mails von Absendern an, deren Domain kein FQDN ist, so dass Mails mit diesem Envelope häufig nicht bei externen Empfängern (also Empfängern außerhalb der eigenen Maildomäne) ankommen. Um E-Mails zuverlässig auch nach Extern weiterzuleiten, sollte der Wert der Einstellung MAIL_FROM geändert werden:

Default: MAIL_FROM = benno@localhost

Adapted (for example): MAIL_FROM = benno@musterfirma.de

Der Versand der E-Mail erfolgt durch den auf dem Archivierungssystem installierten MTA. Unter Debian / Ubuntu bietet es sich an, hier Postfix zu installieren. Im Konfigurationsdialog wird die Option „Satellite System“ ausgewählt. Im nächsten Schritt wird hier der Smarthost abgefragt, der als Relay für die weitergeleitete E-Mail dient.

• Importing emails into the archive