1.4 Installation Instructions

From Enkive Wiki

(Redirected from Installation Instructions)
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 7. The Java Runtime Environment (JRE) without the JDK is not sufficient to run Enkive.

(Please note: Java version 8 causes problems with the Indri compilation. We recommend sticking with version 7 at this time.)

Your operating system may already have Java installed, or it may provide an easy way to install it (e.g.: OpenJDK). 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.4 is only compatible with Jsvc 1.0.12 and later. Version 1.0.15 is recommended.

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 Ubuntu or Debian systems, you can install it with the command 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. The current version is Indri 5.8. We do not recommend using an Indri release prior to 5.4.

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.

Warning: All Indri releases have issues compiling with Java 8. We recommend sticking with Java 7 in the mean time.


MongoDB

Note: Enkive releases 1.4.2 and earlier have not been tested with the recent (as of February 2015) MongoDB 3.0.x release. Only MongoDB 2.6 and 2.4 have been tested.

Please refer to http://docs.mongodb.org/v2.6/installation/ for instructions on how to install MongoDB. The MongoDB website provides instructions on how to configure your system to use their package repositories (for Red Hat- and Debian-like systems).

We recommend you use more recent versions in the MongoDB package repositories over the older versions in the Ubuntu, Debian, and Red Hat package repositories as they've made improvements in speed and data security.

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>

You will need to restart Enkive after changing passwords.

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.


Disable check for updates

Beginning with Enkive 1.4 RC1, Enkive will check for new updates on start. To disable this feature, add this line to $ENKIVE_HOME/config/enkive.properties:

enkive.administration.checkForUpdates=false


Attachments document store location is configurable

Important! If you are upgrading from 1.4 to 1.4.2 or 1.4.1, the document store path must remain the same as it was in version 1.4. This is a known bug and will be fixed in release 1.4.3. See the installation HOWTO or the upgrade instructions for a way around this.

Beginning with Enkive 1.4, email attachments are now stored in $ENKIVE_HOME/data/docstore/. This location is now configurable in Enkive 1.4.1 at $ENKIVE_HOME/config/enkive.properties. Look for the section:

# BASE DATA DIRECTORY
# This is where all components store their data.  It defaults to ENKIVE_HOME/data
# enkive.dataBase=data



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