Reverting from External to Internal Security

Reverting from External to Internal Security

This document describes the procedure necessary to revert to Internal security configuration following accidental mis-configuration of External security in Matillion ETL.

External security misconfiguration can result in being locked out of Matillion, with no way to regain access other than by editing the configuration files on the Matillion server.

The following files need to be edited or checked:

  • /usr/share/emerald/WEB-INF/classes/

  • /usr/share/emerald/WEB-INF/security.fragment

  • /etc/tomcat8/server.xml


  • /etc/tomcat8/tomcat-users.xml



To begin the restore, SSH into the Matillion instance and sudo to root:

sudo -i

Stop Matillion

First of all, stop the Matillion service:

service tomcat8 stop
service tomcat stop

Wait a couple of seconds for the OK box confirming that the service has been stopped.

The file /usr/share/emerald/WEB-INF/classes/ is Matillion-specific and contains a number of authorization parameters.

The file format is UTF-8 text, containing lines with pairs of


The following parameter must be present:


The following parameter should be present:



The file /usr/share/emerald/WEB-INF/security.fragment is used by Tomcat to control access to parts of the Matillion application.

The format is XML.

Ensure that all <role-name> elements have the value Emerald, as shown here:

       <web-resource-name>Emerald Controller</web-resource-name>
       <web-resource-name>Matillion Emerald</web-resource-name>


The file /etc/tomcat8/server.xml/etc/tomcat/server.xml is the main Tomcat configuration file. Security is controlled by means of a Realm, and this needs to be replaced.

Look for the <Realm className="org.apache.catalina.realm.JNDIRealm" …> element and delete it.

Inside the <Engine name="Catalina" defaultHost="localhost"> add a new Realm referencing the user database:

 <Realm className="org.apache.catalina.realm.LockOutRealm">
   <Realm className="org.apache.catalina.realm.UserDatabaseRealm" resourceName="UserDatabase"/>


The file /etc/tomcat8/tomcat-users.xml is the “user database” referred to in the above server.xml Realm.

The file /etc/tomcat/tomcat-users.xml is the “user database” referred to in the above server.xml Realm.

Ensure that the file has mode 644, and is owned by the tomcat user and group.

The contents should be as follows:

<?xml version='1.0' encoding='utf-8'?>
<tomcat-users xmlns=""
             xsi:schemaLocation=" tomcat-users.xsd"
 <role rolename="Emerald"/>
 <role rolename="API"/>
 <role rolename="Admin"/>
 <user username="ec2-user" password="YourPassword" roles="Emerald,API,Admin"/>

Setting Your Password

You will need to use the sha512 message digest function to generate the hash of your chosen password. For example if you choose "change me" as the password, you can generate the hash value like this:

echo -n "change me" | sha512sum | awk '{print $1}'

Then your entry in tomcat-users.xml would look like this:

<user username="ec2-user" password="94fd04a6099e3e42ee047bad6da61258afd7bc0637af5eae85441345e68cf0a53e839ba17a50ef85c79d9996a3cb555c0c612cd3a0dd6fe7a77ece820480d496" roles="Emerald,API,Admin"/>

You will use the username and password to connect to the Matillion web user interface once the service has been restarted.


Service restart

There are occasional problems with file and directory permissions caused by YUM updates. Matillion have written a shell script to correct them.

Before restarting the service please run:


Now that the configuration files have been repaired, you can restart the Matillion service:

service tomcat8 start
service tomcat start

Wait for a couple of seconds until the OK confirmation box appears. Note that this box means the service is starting but has not yet started.

Monitor the startup progress with the following command:

tail -f /usr/share/tomcat8/logs/catalina.out
tail -f /usr/share/tomcat/logs/catalina.out

After anywhere between 20 seconds and 2 minutes, you should find a message like this:

org.apache.catalina.startup.Catalina.start Server startup in ? ms

You are now ready to reconnect to the Matillion web user interface. Ensure there is no j_security_check suffix in the URL:

You should now be able to log in successfully with your credentials from tomcat-users.xml.