1.3 Installation Instructions

From Enkive Wiki

Jump to: navigation, search

Contents

Installation Instructions for System Administrators

Prerequisites

The recommended configuration of Enkive uses Java, MongoDB, Indri, Postfix, Jsvc, and SWIG.

Currently the only supported storage backend and search indexing services supported are MongoDB and Indri. Alfresco is no longer supported.

Java

Enkive is written primarily in Java. You will need the Java Development Kit (JDK) for Standard Edition version 6 or later. The Java Runtime Environment (JRE) without the JDK is not sufficient to run Enkive.

Your operating system may already have Java installed, or it may provide an easy way to install it. Alternatively you can download it from Oracle. Oracle also provides installation instructions.

Note the installation directory, which we will refer to as $JAVA_HOME. After installation, the following (among other items) should be installed:

  • Executable file $JAVA_HOME/bin/javac
  • File $JAVA_HOME/lib/tools.jar

Jsvc

Jsvc is also required to launch Enkive as a daemon.

You can download Jsvc from its project page. Download the native source package (e.g., commons-daemon-X.Y.ZZ-native-src.tar.gz where "X.Y.ZZ" is the version number).

Enkive 1.3 and later versions are only compatible with Jsvc 1.0.12 and later.

Compile as they suggest:

./configure --with-java=$JAVA_HOME
make

That will make the binary. They provide excellent instructions.

SWIG

SWIG provides a bridge between Enkive and Indri. On Debian-type systems, you can install it with the commands below.

apt-get install swig zlib1g zlib1g-dev

On Red Hat-like systems, you can install with:

yum install swig zlib zlib-devel

Otherwise, download SWIG from its project page and install accordingly.

Indri

Indri provides Enkive with the core text indexing and searching capabilities. You can read about Indri on its project page.

You can download Indri from SourceForge. We recommend using Indri 5.4 or later.

First choose where you would like to install it (e.g., /opt/indri); we'll refer to this place as $INDRI_HOME.

./configure --prefix=$INDRI_HOME --enable-java --with-javahome=$JAVA_HOME
make
make install

Keep track of the location you used for $INDRI_HOME.

MongoDB

You can download binaries for MongoDB. We recommend you use more recent versions of MongoDB as they've made improvements in speed and data security. The version at the time of this writing is 2.4.3.

MongoDB does not ship with a standard Linux init script. You can download one here, edit it to indicate where you installed MongoDB, and save it as /etc/init.d/mongodb .

After installation is finished, MongoDB should be started.

[sudo] /etc/init.d/mongodb start

Postfix

The Postfix mailserver is used to reliably queue mail for delivery into Enkive. Other mail servers could be used to deliver mail to Enkive, but as of the writing of these installation instructions, only Postfix is supported.

It should be noted that this method assumes a copy of the message (as opposed to the only instance of the message) is received by postfix, as Enkive will consume the message and not send it back for delivery.

Enkive Socket Filter

We provide the enkive-socket-filter (in $ENKIVE_HOME/support/filters/postfix/enkive-socket-filter), which is a small C program that we configure Postfix to use to send the messages into Enkive. Even if you use a mail server other than Postfix, you might still be able to use the enkive-socket-filter with that mail server, although that is well beyond the scope of this document.

To build enkive-socket-filter, issue the command from $ENKIVE_HOME/support/filters/postfix/enkive-socket-filter:

make

That will generate the executable dist/enkive-socket-filter. Put that executable at your preferred location; we'll now refer to that location as $ENKIVE_SOCKET_FILTER_HOME.

Back to Postfix

For a quick setup, place the following code in postfix's master.cf. Replace $ENKIVE_SOCKET_FILTER_HOME with the location you placed the enkive-socket-filter.

smtp      inet  n       -       n       -       -      smtpd
        -o content_filter=filter:dummy

filter    unix  -       n       n       -       -      pipe
          flags=Rq user=nobody null_sender=
          argv=$ENKIVE_SOCKET_FILTER_HOME/enkive-socket-filter localhost 2527 ${sender} ${recipient}

This setup will send every message that comes through the postfix queue to Enkive. IMPORTANT: messages that are received by this postfix get sent to Enkive but do not get delivered to users. If you do not understand this statement and its implications, please seek the help of someone who does.

Configure Enkive

Configurable Settings

Enkive Filters

Enkive provides a fairly flexible system for filtering messages received. Currently the filtering system only provides for deciding whether or not to accept or reject messages. However it does provide filtering capabilities on many different types of message headers. Filter settings are set in $ENKIVE_HOME/config/enkive-filters.xml :

<filters
        xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
        xsi:noNamespaceSchemaLocation="enkive-filters.xsd">
        <defaultAction>Allow</defaultAction>
        <filter enabled="true">
                <action>deny</action>
                <header>X-Spam-Flag</header>
                <value type="string" comparison="matches">YES</value>
        </filter>
        <filter enabled="true">
                <action>deny</action>
                <header>From</header>
                <value type="address" comparison="matches">reject@reject.com</value>
        </filter>
</filters>

The <defaultAction> tag determines the action to take if no filter cases apply to it. Allowed values are 'accept' and 'deny'.

The <filter> tag defines a new enkive filter. the "enabled" attribute defines whether or not enkive should enforce the filter. The <action> tag defines whether or not enkive should allow or deny a message if it meets that filters criteria. If a message meets a certain filter criteria, the action to take with that filter is compared with the default action, if the actions differ, the action set in the filter is taken. Using the example above the default action is to allow messages; if a message comes through that meets the 'x-spam-flag=YES' filter, that message would be rejected, because the action for that filter is to deny.

The <header> tag defines the header on which to filter. The field can be any string, allowing for filtering on any header. The field must match the case of the message header.

The <value> tag defines the value to compare a message headers value against. Valid 'type' attributes are 'integer', 'float', 'date', 'string', and 'address'. Valid comparisons for 'integer', 'float', and 'date' are 'is_greater_than', 'is_less_than', 'matches', and 'does_not_match'. Valid comparisons for addresses and string are 'contains', 'does_not_contain', 'matches', and 'does_not_match'.

Additional information can be found at Enkive_Message_Filtering.

Configure Enkive Daemon for Start Up

A Linux init script is included with the download in $ENKIVE_HOME/scripts/enkive.

There are some variables that are set near the top of the init script that need to be given correct values for your installation. Edit your copy of the init script and set these variables appropriately.

Also the script will need executable permissions, so from within the scripts directory issue the command:

chmod a+x ./enkive

The Enkive init script should be placed in the /etc/init.d/ directory (or wherever start-up files on your particular operating system go).

Proxy Enkive Web Interface through Apache

If you are using Apache with mod_proxy as your web server, you can configure Apache to proxy to the Jetty web server that's part of Enkive by modifying your httpd.conf file to include:

ProxyPass /ediscovery http://localhost:8888/ediscovery
ProxyPassReverse /ediscovery http://localhost:8888/ediscovery

Configuring Apache in general or any other web server is well beyond the scope of this document.

User Authentication and Authorization

Enkive user authentication and authorization can be done in one of four ways:

  1. via the users.properties file
  2. via an existing LDAP server
  3. via an existing Active Directory server
  4. a combination of two or more of the above

You will select one of the three authentication methods by editing the file

$ENKIVE_HOME/config/resources/authentication/authentication-service.xml

and uncommenting one of the three imports and commenting the other two. You will then edit the corresponding .xml file listed as the resource for the one import you leave uncommented. See below for details.

Enkive cares about two possible roles for users known as ENKIVE_USER and ENKIVE_ADMIN. The role ENKIVE_USER gives a user access to his/her own archived email. The role ENKIVE_ADMIN gives a user access to any archived email messages along with special administrative functionality.

Note: depending on the authentication method used below, you may need to prefix references to the role(s) with ROLE_. Please read the instructions for your authentication method of choice carefully.

Authenticating via users.properties

This file can be found at:

$ENKIVE_HOME/config/users.properties

This file is a standard Spring Security users file. The default file that ships with enkive has one user configured:

enkive=a795c3b4d817cf86580446a1f665cfd82284429d,ROLE_ENKIVE_ADMIN,ROLE_ENKIVE_USER,enabled

Each line in this file has the following form:

username=sha1-hash,role1,role2,enabled/disabled

The text before the "=", enkive, is the username. The first field after the "=" is the SHA1 hash of the default password enkive.

The next one or two fields are user roles. ROLE_ENKIVE_ADMIN gives unrestricted access to the Enkive archive; you will likely only give this to some users. All users should have the ROLE_ENKIVE_USER attribute. Therefore there will be one or two roles depending on whether or not the user is granted administrative access.

The last field, enabled, enables the user to log in; by changing this to disabled you can temporarily or permanently lock a user out of the archive.

You can add additional users, or edit and remove existing users. To add a user who only has access to a specific email account, the username should be the email address.

SHA1 hashes of passwords can be generated using the command:

echo -ne password | sha1sum

For example, the default SHA1 hash included for the enkive account was determined by running,

prompt> echo -ne enkive | sha1sum
a795c3b4d817cf86580446a1f665cfd82284429d  -
prompt>

Authenticating via LDAP

The LDAP connection is provided by Spring Security and can be configured in:

$ENKIVE_HOME/config/resources/authentication/ldap-authentication.xml

To configure Enkive to use your LDAP server edit the file, look at the example provided inside, and follow the instructions in the comments.

Spring Security allows for quite a bit of flexibility to match various LDAP schema. If the example does not work for you, please read the documentation on the Spring Security LDAP documentation page.

Enkive allows a given authenticated user to be associated with multiple email addresses stored in multiple user entry attributes. That is configured by modifying the ldapEmailAddressAttributeIds property of the LdapUserContextMapper bean.

The Enkive roles are configured via LDAP as groups that the user belongs to. If the user belongs to a group named ENKIVE_USER s/he will be in that role. If the user belongs to a group named ENKIVE_ADMIN s/he will be in that role. The group-search-base attribute of the ldap-authentication-provider element determines where in the schema the groups are searched. You may find it useful to create a subgroup that contains the Enkive-related groups to minimize the groups searched (as shown in the example provided).

The custom Enkive groups you create in LDAP should be of the objectclass: groupofUniquenames.

Authenticating via Active Directory

The Active Directory authentication service is provided by Spring Security and can be configured in:

$ENKIVE_HOME/config/resources/authentication/ad-authentication.xml

To configure Enkive to use your Active Directory server, edit the file, look at the example provided inside, and follow the instructions in the comments.

Spring Security is built on the standard Active Directory schema. If the example does not work for you, please read the documentation on the Spring Security LDAP documentation page.

Enkive allows a given authenticated user to be associated with multiple email addresses stored in multiple user entry attributes. That is configured by modifying the ldapEmailAddressAttributeIds property of the AdUserContextMapper bean.

The Enkive roles are configured in Active Directory as groups that the user belongs to. If the user belongs to a group named ROLE_ENKIVE_USER s/he will be in that role. If the user belongs to a group named ROLE_ENKIVE_ADMIN s/he will be in that role.

Users can log in to an Active Directory-connected Enkive with either their User Principal Name (e.g.: joe@DOMAIN.COM) or their sAMAccountName (e.g.: joe).

Combining Multiple Authentication Strategies

Some sites like to use both file authentication and LDAP authentication. That's possible, although there's a little more work involved in configuring it. Essentially you would have to combine the common configuration elements from the two strategies. But you would only have a single authentication-manager block in which you would place multiple authentication providers.

For example, in our testing environment, the following authentication-service.xml file allows both file- and LDAP-authentication.

 <b:beans xmlns="http://www.springframework.org/schema/security"
          xmlns:b="http://www.springframework.org/schema/beans"
          xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
          xsi:schemaLocation="http://www.springframework.org/schema/beans 
                              http://www.springframework.org/schema/beans/spring-beans-3.0.xsd
                              http://www.springframework.org/schema/security 
                              http://www.springframework.org/schema/security/spring-security-3.1.xsd">
 
     <http use-expressions="true" auto-config="false">
         <intercept-url pattern="/**" access="isAuthenticated()" />
         <form-login />
     </http>
 
     <b:bean id="EmailAddressNormalizer"
             class="com.linuxbox.enkive.normalization.CaseEmailAddressNormalizer" />
 
     <ldap-server url="ldap://10.1.1.129:389/dc=elderwand,dc=jk" />
 
     <b:bean id="UserDetailsService"
             class="com.linuxbox.enkive.authentication.EnkivePropFileUserDetailsContextMapper">
         <b:property name="properties" value="classpath:linuxbox-users.properties" />
         <b:property name="userAddresses" value="classpath:addresses.properties" />
         <b:property name="defaultDomain" value="enron.com" />
         <b:property name="emailAddressNormalizer" ref="EmailAddressNormalizer" />
     </b:bean>
 
     <b:bean id="LdapUserContextMapper"
             class="com.linuxbox.enkive.authentication.ldap.EnkiveLdapUserDetailsContextMapper"
             scope="singleton">
         <b:property name="ldapEmailAddressAttributeIds" value="mail,zimbraMailDeliveryAddress" />
         <b:property name="emailAddressNormalizer" ref="EmailAddressNormalizer" />
     </b:bean>
 
     <authentication-manager alias="authenticationManager">
         <authentication-provider user-service-ref="UserDetailsService">
             <password-encoder hash="sha" />
         </authentication-provider>
         <ldap-authentication-provider
             user-dn-pattern="uid={0},ou=people"
             user-context-mapper-ref="LdapUserContextMapper"
             group-search-base="ou=EnkiveRoles,ou=groups" />
     </authentication-manager>
 
 </b:beans>

IMAP Access

To enable IMAP access to the archive, please consult the IMAP Access Feature page.

Other Properties

Other properties can be configured in the $ENKIVE_HOME/config/enkive.properties file.

In-line comments about the attributes can be found in the $ENKIVE_HOME/config/default/enkive.properties, however, this file should not be edited. All modifications to these properties should be made in $ENKIVE_HOME/config/enkive.properties.

Logging is provided by log4j and can be configured in the standard way by modifying the $ENKIVE_HOME/config/log4j.properties file.

Starting Enkive

Enkive can now be started using the init script that was modified earlier by running

/etc/init.d/enkive start

The Enkive E-Discovery front-end can now be accessed on http://localhost:8888/ediscovery, and the back-end is ready for archiving.

If you run into trouble starting Enkive, please see our Trouble Starting Enkive page.

Personal tools