User Tools

Site Tools


replicator_agent_installation

Agent Installation

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

Download

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

perspectium-replicator-installer-VERSION.jar

Contact support@perspectium.com if you have not received this file.

This is the file we will use to run the agent installer.

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/3.1.9/perspectium-replicator-installer.zip .
--2015-03-16 12:54:13--  https://depot.perspectium.com/downloads/agents/3.1.9/perspectium-replicator-installer.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: 44127657 (42M) [application/zip]
Saving to: `perspectium-replicator-installer-version.jar'

100%[=====================================================================================================================>] 44,127,657  19.2M/s   in 2.2s    

2015-03-16 12:54:15 (19.2 MB/s) - `perspectium-replicator-installer-version.jar' saved [44127657/44127657]

This should give you a versioned perspectium-replicator-installer.jar. This is the file we will use to run the agent installer.


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

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://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

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.

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 12c Release 1: 12.1.0.2+
SQL Server (MSSQL) 2012+, 2016 recommended
MySQL 5.7.22+ 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+
PostgreSQL 42.1.4
Snowflake 2.5+

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+
Windows Server 12+
Linux Redhat/AIX All

Settings

You should make note of the following settings before starting the installation. The installer will prompt you for them:

General Installer Settings
Installation Path The directory you wish to install to
Java Path java -version
Perspectium Cloud Server, User, and Password contact support@perspectium.com if you did not receive these
Agent Name A name for your agent as provided by Perspectium or as desired
Carbon Queue Name A specified queue for your agent to subscribe to as provided by Perspectium or as desired
Decryption Key The Encryption Key you specified in the Properties page of the Perspectium ServiceNow Application
SQL Replicator Settings
ServiceNow Instance, User and Password ex: yourinstance.service-now.com someuser somepassword
Database Server, Port, User, Password, Database Name Settings to connect to your database

The instance user name/ID cannot be an SSO user, it must be a local user that is given the 'perspectium' role and can invoke a processor.

File Replicator Settings
FileName The file you wish to replicate
Directory Replicator Settings
Directory The directory you wish to share from

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
ubuntu@ip-10-221-138-246:~$ 

Next, login or sudo to the perspectium user and copy or download the agent installation file into it. See Download. If your download is currently zipped, you can use the following command to unzip it.

perspectium@ip-10-221-138-246:~/Perspectium_Replicator$ unzip perspectium-replicator-installer.zip 
Archive:  ../perspectium-replicator-installer.zip
  inflating: perspectium-replicator-installer.jar  

Running the Installer

To run the installer from a linux console using a GUI, type the following (per your version):

java -jar ./perspectium-replicator-installer-version.jar

You will be prompted to enter in the following

  1. Acceptance of the EULA
  2. Target Path for installation
  3. Java Path
  4. Perspectium MBS Credentials
  5. Agent Name (ServiceName for the daemon)
  6. Type of Replicator (Database type, file, etc…)
  7. Database Credentials
  8. Decryption Key, Max Reads, Polling Interval

If you make a mistake you can modify these in the agent.xml file afterwards.

The following is an example of the installation script when run in console mode (no GUI) using the “-console” switch

perspectium@ip-10-221-138-246:~/Perspectium_Replicator$ java -jar perspectium-replicator-installer.jar -console
Mar 16, 2015 2:01:17 PM INFO: Logging initialized at level 'INFO'
Mar 16, 2015 2:01:17 PM INFO: Commandline arguments: 
Mar 16, 2015 2:01:18 PM INFO: Detected platform: ubuntu_linux,version=3.2.0-40-virtual,arch=x64,symbolicName=null,javaVersion=1.7.0_25
Welcome to the installation of Perspectium Replicator Agent 3.1.9!
This software is developed by: 
 - Perspectium Corporation <support@perspectium.com>

Press 1 to continue, 2 to quit, 3 to redisplay

Press 1 to continue. You will now be presented with the End User License Agreement.

SOFTWARE AS A SERVICE (“SAAS “) TERMS OF SERVICE FOR END-USERS
THE SERVICE PROVIDERS (DEFINED BELOW) ARE WILLING TO GRANT YOU RIGHTS
TO ESTABLISH AN ACCOUNT AND TO USE THE WEB SERVICES (DEFINED BELOW)
ONLY UPON THE CONDITION THAT YOU ACCEPT ALL OF THE TERMS CONTAINED IN
THIS AGREEMENT. PLEASE READ THE SERVICE AGREEMENT CAREFULLY. BY
CLICKING ON "I ACCEPT", YOU WILL INDICATE YOUR AGREEMENT WITH THEM. IF
YOU ARE ENTERING INTO THIS AGREEMENT ON BEHALF OF A COMPANY OR OTHER
LEGAL ENTITY OR PERSON, YOUR ACCEPTANCE REPRESENTS THAT YOU HAVE THE
AUTHORITY TO BIND SUCH ENTITY OR PERSON TO THESE TERMS. IF YOU DO NOT
AGREE WITH THESE TERMS, OR IF YOU DO NOT HAVE THE AUTHORITY TO BIND
YOUR ENTITY OR PERSON, THEN THE SERVICE PROVIDERS ARE UNWILLING TO
GRANT YOU RIGHTS TO ACCESS AND USE THE WEB SERVICES.
SAAS TERMS OF SERVICE AGREEMENT Effective Date as of first day Perspectium
services commence.
1. Definitions.
    1.1. Parties.
        1.1.1. This is an agreement by and among the originator of the Web Services
        (the Primary Service Provider), the party that offered and sold you the Web
        Services (the ‚Secondary Service Provider, which will be Perspectium or a
        Perspectium authorized reseller), and you.
        1.1.2. Both the Primary Service Provider and the Secondary Service Provider
        will be referred to collectively as the Service Provider, and both will have full

Press Enter to continue, X to exit

Press Enter to continue until the end of the agreement. There are about 20 pages of this document.

...
40. Miscellaneous. This Agreement constitutes the entire understanding of the parties with
respect to the subject matter of this Agreement and merges all prior communications,
understandings, and agreements. This Agreement may be modified only by a written
agreement signed by the parties. The failure of either party to enforce at any time any
of the provisions hereof shall not be a waiver of such provision, or any other provision,
or of the right of such party thereafter to enforce any provision hereof. The application
the United Nations Convention of Contracts for the International Sale of Goods is
expressly excluded. This license is written in English, and English is its controlling

Press Enter to continue, X to exit

Press 1 to accept, 2 to reject, 3 to redisplay

Press 1 to accept the agreement. You will now be asked for the installation destination, this is where the agent files will be copied.

If you have a previous agent already installed in the destination directory, it will be overridden.

Select target path [/home/perspectium/Perspectium Replicator Agent]

You may press Enter to select the default or type in a new one. Please keep the directory within the home of the perspectium user. Next, the installer will scan your path for a suitable JDK or JRE and suggest the path for it.

Please choose the directory of your installed Java JDK or JRE (version 1.7.0 or higher)

[/usr/lib/jvm/java-7-openjdk-amd64/jre] 

If this is the right JDK or JRE (See Agent Requirements ), press Enter to select or enter a different path. You will now be asked to supply the Perspectium Cloud Server host name.

Enter the information for accessing the Perspectium Cloud Server:

Server: [] 
server10.perspectium.com

Carbon
Enter the supplied hostname and press enter to continue. Next, enter the user, password, name of the agent and specified queue.

User: [demo] 

Password: [demo] 


Enter the information for your agent:
Name: [] 
demo_agent

Queue Name: [psp.out.replicator.yourqueue]
psp.out.replicator.demo_agent

You will now be asked to select the type of agent to install. Depending on which type, additional information may be required. For example you may be asked for database credentials for subscribing to ServiceNow and writing to a local database.

Type:
0  [x] MySQL Replicator
1  [ ] MSSQL Replicator
2  [ ] Oracle Replicator
3  [ ] File Replicator
4  [ ] Directory Replicator
input selection: 

After entering the agent type information, you will now be prompted for the decryption key, maximum number of records to read and the interval between reads. The decryption key should be the same as the encryption key you would have set, e.g. in ServiceNow. See Encryption.

Decryption Key: [The cow jumped over the moon] 

Max Reads: [4000] 

Polling Interval (sec): [30] 

The installer will now complete its task and copy the files to the target directory, you should see the following output.

[ Starting to unpack ]
[ Processing package: core (1/2) ]
[ Processing package:  (2/2) ]
[ Unpacking finished ]
[ Starting processing ]
Starting process Update wrapper.conf (1/3)
Updating wrapper.conf...
wrapper.conf configuration complete.
Starting process Update license.txt (2/3)
Updating license.txt...
license.txt configuration complete.
Starting process Update config.xml (3/3)
Updating config.xml...
config.xml configuration complete.
Installation was successful
application installed on /home/perspectium/Perspectium Replicator Agent
[ Writing the uninstaller data ... ]
[ Console installation done ]

Generating an automatic installation script

After successful installation of the agent, the user is given an option to generate an automatic install script on the last panel of the agent installer. This is useful to install an agent on another machine using the same settings.

Executing the auto-install

You can execute the auto-install.xml by running the following command:

java -jar perspectium-replicator-installer.jar auto-install.xml

Note: The user must copy and paste the created auto-install.xml along with the perspectium-replicator-installer.jar in the same folder or directory and issue the command stated above.

This will use the credentials and directory locations you used in the initial install. If you would like to change the directory where the Agent will be installed you can modify the auto-install.xml file.


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.

Validation

First, let's check that our 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 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/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 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:

bin/installDaemon.sh

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 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):

sudo bin/startDaemon.sh

… or stop it:

sudo bin/stopDaemon.sh

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_agent_installation.txt · Last modified: 2018/05/14 15:15 by billy