User Tools

Site Tools


Ready to Run Installation for Linux

A few simple tasks are required in order to get the replicator agent running.

The ready-to-run agent is a zipped file that makes it possible to run the agent without the usual installation process. Setting up the configuration for agent will instead be done on ServiceNow through the Ready to Run UI page. It is recommended to have the configuration set and downloaded from ServiceNow before unzipping the agent.

Note: This is not the standard installer, which can be read Agent Installation. This is for the “Ready to Run” to simplify the install. It will require the config to be imported rather than being generated by the installer.


First off, you should have received a download such as the following (per your version):

Contact if you have not received this file.

This is the file we will use to install the agent.

You may use the browser to download directly and copy the file over. You could also use the wget command line utility. Here is an example of using wget:


perspectium@ip-10-221-138-246:~$ wget


--2018-03-12 12:21:36--
Resolving (
Connecting to (||:443... connected.
HTTP request sent, awaiting response... 200 OK
Length: 79435435 (76M) [application/zip]
Saving to: ‘’

Perspectium_Replica 100%[===================>]  75.75M  27.0MB/s    in 2.8s    

2018-03-12 12:21:39 (27.0 MB/s) - ‘’ saved [79435435/79435435]

This should give you a versioned This is the file we will use to install the agent.

Agent Requirements

These are the requirements needed to ensure that your agent can be executed properly and has the ability to be upgraded in the future.


System Requirements
Memory 8GB minimum
Processor Cores 4 minimum
Hard Disk Space 100GB minimum
Network Interface GigE

Network Access

The Replicator agent requires only outbound access to the Perspectium cloud and the ServiceNow instance.

Perspectium products require that your firewall settings allow traffic to and from your Perspectium MBS. This can be through any one of the following three ports: AMQP, AMQPS, or HTTPS. You will specify which protocol you will be using through the URL of the <message_connection>.

The Agent also requires that your firewall settings allow traffic to and from your ServiceNow instance. To test this access you can consult this page.

Network Requirements
AMQPS Outbound Port TCP/5671 outbound to your Perspectium MBS (amqps://
AMQP Outbound Port TCP/5672 outbound to your Perspectium MBS (amqp://
HTTPS Outbound Port TCP/443 outbound to your Perspectium MBS (
HTTPS Outbound Port TCP/443 outbound to your ServiceNow instance


Both 32 and 64 bit versions of Java are supported. The Java version must be Java 8 or higher. As of the Fluorine release, Java versions 9 and 10 are supported. It's strongly recommended that you use a server type JVM instead of a client or desktop version.

A 32 bit version of Java is required if you're running the agent on a Windows server for Agent versions under 3.24.0.

You can determine that Java is in your current path and the version by issuing the following command from the command prompt:

java -version

If you don't see something like the following then please contact your system administrator for help.

java version "1.8.0_181"

Make note of the path to Java. One way to determine the path to Java on most linux distros is to issue the following command:

which java

On Windows this is typically located in “C:\Program Files \Java\…”

On either windows/linux the installer will generally find the path to the java installation and auto-fill this for you.

Verify that Java is in your PATH system (environment) variable as some installations of Java may not add it properly. If it is not there, add the path of the JRE's bin direct as indicated here.

Supported Databases

Database Version
Oracle 11g, 12c Release 1: 12.1 -
SQL Server (MSSQL) 2012, 2016 recommended
MySQL 5.6 - 8.0 supported in Europium
SAP Hana SPS 12
Amazon Redshift 4.0-4.1
Amazon Aurora (MySQL compatible) N/A
IBM DB2 11
HP Vertica 8.0 - 9.21
PostgreSQL 42.2.6
Snowflake 3.9

NOTE: Perspectium uses the newest version of each of the associated JDBC drivers, which are included with the install.

NOTE: Perspectium strongly recommends placing the Agent on the same local area network as the database server.

Supported Operating Systems

The following OS versions are supported by the Replicator Agent:

OS Version
Windows Professional & Home 7 - 10
Windows Server 2012 - 2016
Linux Ubuntu 14.04 and 16.04

Installing the Agent

Creating the perspectium user

Before we start the installation, it is recommended to create a user called perspectium and install the agent as that user.

ubuntu@ip-10-221-138-246:~$ sudo adduser perspectium
Adding user `perspectium' ...
Adding new group `perspectium' (1001) ...
Adding new user `perspectium' (1001) with group `perspectium' ...
Creating home directory `/home/perspectium' ...
Copying files from `/etc/skel' ...
Enter new UNIX password: 
Retype new UNIX password: 
passwd: password updated successfully
Changing the user information for perspectium
Enter the new value, or press ENTER for the default
	Full Name []: Perspectium
	Room Number []: 
	Work Phone []: 
	Home Phone []: 
	Other []: 
Is the information correct? [Y/n] Y

Next, login or sudo to the perspectium user and copy or download the ready-to-run agent file into it. See Download.


Ready-to-Run agent is made to be usable once downloaded. Be sure to have the configuration files from Ready-to-Run already downloaded and ready so that the agent may have the necessary configurations. It is recommended to unzip this in the Perspectium user's directory or somewhere reasonable.

The process for setting up the ready-to-run agent is made to be simple. The idea is:

  - move the zipped folder to the desired directory
  - unzip
  - move ready-to-run config files to their respective jaz folders

Below is an example of the steps above

perspectium@ip-10-221-138-246:~$ mv /path/to/directory
perspectium@ip-10-221-138-246:~$ cd /path/to/directory
perspectium@ip-10-221-138-246:~$ unzip Perspectium_Replicator_Agent
perspectium@ip-10-221-138-246:~$ ls

perspectium@ip-10-221-138-246:~$ cd /path/to/ready-to-run
perspectium@ip-10-221-138-246:~$ cp -r /bin/* /path/to/directory/Perspectium_Replicator_Agent/bin
perspectium@ip-10-221-138-246:~$ cp -r /conf/* /path/to/directory/Perspectium_Replicator_Agent/conf

Validating Your Configuration

After the initial set up, you can look at your configuration within the agent.xml file of the conf directory. Here you will see a generic task set up with the credentials you have just input. You can either run it now, however, it is recommended to run our tool to test and validate your current connections. It will run through your Message Bus Connections, Database Connections, and Instance Connections (to ServiceNow or elsewhere) as you have prescribed.

Following these connections it will notify you which pieces failed as well as other diagnostic information about your current configuration. To see how to run this test see here.

Installation as a Daemon

Since we want the Replicator agent to run all the time, we'll make sure that it is automatically started when the computer is started. We will first want to verify a few components by performing a couple of tasks.


First, let's check that our agent is not currently running by issuing the command:

bin/ status

This should output:

Name        : example_agent
Installed   : false
Running     : false

In order to make sure that the replicator agent will run we can issue this command to validate the configuration:

bash bin/validateConfiguration

You may want to test run the Agent by running it in the foreground before installing it as a Daemon. This will run the Agent within the command window. Once you close the window the Agent will stop. We recommend you to stop the Agent by typing (CTRL + C).

Start the agent by typing

bin/ start

And you should see a message similar to the following:

INFO  - main - ClassUtil - Perspectium Version: Argon_3270
INFO  - main - ReplicatorAgent - The Replicator example version: Argon_3270 is starting configuration file processing.
INFO  - main - ReplicatorAgent - Platform: 1.8.0_131 Mac OS X 10.11.6 x86_64 Processors: 4 Total Memory: 1289M Free Memory: 100M Maximum Memory: 1908M
INFO  - main - ResourceConsumption - CPU Usage: 2.01 JVM Free Memory: 100.41M Heap Memory used: 28.56M peak threads: 10

Before proceeding to the installation, it is advisable to share out a couple of test records into your database in order to ensure that the agent is subscribing to the data as expected.


Once the above step has been completed with no problems, we can go ahead with the Agent service installation. If the Agent is still running from the command type CTRL + C.

Finally, to install the agent as a service, we use the following command:


Running as a Service

To ensure that the installer has successfully set up the agent as a service, let's check the status of the agent.

Running the status command again should now return this:

Name        : example_agent
Installed   : true
Running     : true

Then, we can start it (if Running is false):

sudo bin/

… or stop it:

sudo bin/

Upgrading the Agent

Argon or newer versions

If you are upgrading a previously installed agent to a newer release, you will need to stop the currently running agent. Once the agent is stopped, you may proceed to run the install procedure described above. Note that if you generated an automatic installation script with your previous installation, you can run the installer from the command line and pass the automatic installation file as a parameter. Doing so will cause the installer to run and use all the settings you specified in the previous installation. You will not be prompted for this information.

To run the installer with an auto installation script, open a command window and change to the directory where the new installer jar file resides. Next you should locate the auto installation script from your previous install. It is usually in the top directory of the agent installation and if you accepted the default name will be called “auto-install.xml”.

Once you know the location, copy and paste the auto-intall.xml into the same folder or directory as the perspectium-replicator-installer.jar. Now you can run the following command making sure to use the correct name of the installer jar file:

java -jar perspectium-replicator-installer.jar auto-install.xml
replicator_ready_to_run_agent_installation_linux.txt · Last modified: 2018/03/13 16:22 by vinhn