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 email@example.com 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 https://depot.perspectium.com/downloads/agents/Bismuth-314159265/Perspectium_Replicator-linux_jaz.zip
--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)... 184.108.40.206 Connecting to depot.perspectium.com (depot.perspectium.com)|220.127.116.11|: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. This is the file we will use to install the agent.
These are the requirements needed to ensure that your agent can be executed properly and has the ability to be upgraded in the future.
|Processor Cores||4 minimum|
|Hard Disk Space||100GB minimum|
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.
|AMQPS Outbound Port||TCP/5671 outbound to your Perspectium MBS (amqps://example.perspectium.net)|
|AMQP Outbound Port||TCP/5672 outbound to your Perspectium MBS (amqp://example.perspectium.net)|
|HTTPS Outbound Port||TCP/443 outbound to your Perspectium MBS (https://example.perspectium.net)|
|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:
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:
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.
|Oracle||11g, 12c Release 1: 12.1 - 18.104.22.168.0|
|SQL Server (MSSQL)||2012, 2016 recommended|
|MySQL||5.6 - 8.0 supported in Europium|
|SAP Hana||SPS 12|
|Amazon Aurora (MySQL compatible)||N/A|
|HP Vertica||8.0 - 9.21|
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.
The following OS versions are supported by the Replicator Agent:
|Windows Professional & Home||7 - 10|
|Windows Server||2012 - 2016|
|Linux Ubuntu||14.04 and 16.04|
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 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 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 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
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.
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:
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:
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
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 agent.sh command type CTRL + C.
Finally, to install the agent as a service, we use the following command:
To ensure that the installer has successfully set up the agent as a service, let's check the status of the agent.
Running the agent.sh status command again should now return this:
Name : example_agent Installed : true Running : true
Then, we can start it (if Running is false):
… or stop it:
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