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 instance through User Configuration in the top right corner of the screen.

Admin_User Configuration

Admin_User Configuration

There are three types of security options available for user configurations.

  • None
  • Internal
  • External

When selecting External, the Matillion ETL instance will link to an existing directory server. For example: OpenLDAP (Lightweight Directory Access Protocol) or Microsoft Active Directory.

Please Note

Opting to use External security will prevent existing users configured in Internal security from logging in.

External User Configuration

External User Configuration

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 Matillion users can revert to Internal security configuration by editing following files and confirm the information is correct in the respective files.

Important Information

This guide use the examples using tomcat8 version of the server.

Please follow the steps mentioned below to revert to the internal security.

Move Sudo to root

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

sudo -i
Sudo to root

Sudo to root

Stop Matillion

First of all, stop the Matillion service:

service tomcat8 stop
service tomcat stop
Stop tomcat service

Stop tomcat service

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:


Please ensure that the parameters should be same as mentioned above, if not then change them as shown below:

 Change to Parameters

Change to Parameters


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.

Please 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>
role-name with value Emerald

role-name" with value Emerald


The file /etc/tomcat8/server.xml or /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.

Realm - properties

Realm - properties

Once deleted, in server.xml file and inside the <Engine defaultHost="localhost" name="Catalina"> add a new Realm referencing the user database:

<Realm className="org.apache.catalina.realm.LockOutRealm">
<Realm className="org.apache.catalina.realm.UserDatabaseRealm"><CredentialHandler algorithm="SHA-512" className="org.apache.catalina.realm.MessageDigestCredentialHandler"/></Realm></Realm>
Realm - properties-08

"Realm - properties-08


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 permission mode 644, and is owned by the tomcat : tomcat.



Please Note

The command you could use to get the information is as follows:

chmod 644 tomcat-users.xml
chown tomcat:tomcat tomcat.users.xml

Setting Your Password

In order to setup the password, you need to go to cat tomcat-users.xml. 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,ProjectAdmin,API,Admin"/>
cat tomcat-users content

"cat tomcat-users content"

Encrypting 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 or encrypt the hash value using the following command:

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"/>
Encrypt Password

"Encrypt Password"

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:

Run YUM updates

"Run YUM updates"

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

service tomcat8 start
service tomcat start
Start the server

"Start the server"

Monitor the startup progress with the following command:

tail -f /var/log/tomcat8/catalina.out

tail -f /var/log/tomcat8/catalina.out

Catalina Logs

"Catalina Logs"

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.

Login to Matillion

"Login to Matillion"