Download

First off, you should have received a download such as Perspectium_Replicator-linux_jaz.zip or similar, depending on your version. Contact support@perspectium.com if you have not received this file - this is the file you need to install the agent.

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

command:

perspectium@ip-10-221-138-246:~$ wget https://depot.perspectium.com/downloads/agents/Bismuth-314159265/Perspectium_Replicator-linux_jaz.zip

output:

--2018-03-12 12:21:36--  https://depot.perspectium.com/downloads/agents/Bismuth-314159265/Perspectium_Replicator-linux_jaz.zip
Resolving depot.perspectium.com (depot.perspectium.com)... 54.241.252.46
Connecting to depot.perspectium.com (depot.perspectium.com)|54.241.252.46|:443... connected.
HTTP request sent, awaiting response... 200 OK
Length: 79435435 (76M) [application/zip]
Saving to: ‘Perspectium_Replicator-linux_jaz.zip’

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

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

This should give you a versioned perspectium-replicator-linux_jaz.zip 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

Network Access

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.

Java

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.

Supported Databases

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:

Installing the Agent

Creating the Perspectium user

Before you start the installation, we recommend you 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
ubuntu@ip-10-221-138-246:~$ 

Next, login or sudo to the perspectium user and copy or download the ready-to-run agent file into it (see previous instructions on this page).

Installation

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 Perspectium_Replicator-linux_jaz.zip /path/to/directory
perspectium@ip-10-221-138-246:~$ cd /path/to/directory
perspectium@ip-10-221-138-246:~$ unzip Perspectium_Replicator-linux_jaz.zip Perspectium_Replicator_Agent
perspectium@ip-10-221-138-246:~$ ls

Archive:  
        ../bin
        ../conf
        ../extlib
        ../jars
        ../lib
        ../logs
        
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.

Installation as a Daemon

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

Validation

First, check that your agent is not currently running by issuing the command:

bin/agent.sh status

This should output:

Name        : example_agent
Installed   : false
Running     : false

In order to make sure that the replicator agent will run, you 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/agent.sh 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.

Installation

Once you have completed the above step with no problems, you can go ahead with the Agent service installation. If the Agent is still running from the agent.sh command, type CTRL + C.

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

bin/installDaemon.sh

Running as a Service

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

Running the agent.sh status command again should now return this:

Name        : example_agent
Installed   : true
Running     : true

If Running is false, you can start it:

sudo bin/startDaemon.sh

…or stop it:

sudo bin/stopDaemon.sh

Upgrading the Agent

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