--- title: "Install the DataSync Agent" canonical: "https://docs.perspectium.com/space/Iodine/1704475/Install%20the%20DataSync%20Agent" format: markdown --- You can install the DataSync Agent on supported Windows and Linux devices. You can obtain the Perspectium DataSync Agent install files by   contacting Perspectium Support . Before getting started with the DataSync Agent, check to make sure your environment meets the base   agent requirements . Install the DataSync Agent through Agent Installer Prerequisites Make sure that the device you are installing the DataSync Agent on meets these basic requirements . You will also need to request the Agent Installer from Perspectium Support . To install the agent through the agent installer, follow these steps: Open the Agent Installer .jar file. If you didn't receive this file, you can request one from Perspectium Support . A pop-up may appear indicating that the Agent Installer file can't be opened because it is from an unidentified developer. If this happens, click OK to close the pop-up and then navigate to  System Preferences >  Security & Privacy . Under the  General tab, locate the section beginning with  Allow apps downloaded from: and click  Open Anyway . Then, click  Open in the resulting pop-up to open the Agent Installer wizard. Check the box to accept the terms of the Perspectium End User License Agreement . Then, click  Next . Choose a directory to install the DataSync Agent files in. If you specify a new directory, that directory will first be created and then populated with the Agent files. Then, click Next . Choose the directory where your Java JDK/JRE is installed. In most cases, you can use the directory defined in JAVA_HOME. Otherwise, choose the other option and then click  Next to specify the JDK/JRE directory you want to use. After you finish choosing the JDK/JRE, click  Next .   NOTE : Your JDK/JRE must be version 1.8.0 or higher. Type a name for your DataSync Agent; e.g., datasyncforservicenow_to_mysql. Then, choose an option from the  DataSync Type dropdown: Finally, click  Next to proceed to the next step. On the resulting page, enter the following to allow your DataSync Agent to authenticate when connecting to the Perspectium Integration Mesh: Then, click  Next to continue to the next step. On the resulting page, enter the following information to allow your DataSync Agent to connect to and authenticate with your ServiceNow instance and database server: Then, click  Next to continue to the next step. On the Summary and Review  screen, wait for the processes to finish running and then click  Next . Then, on the Perform External Processes  screen, wait for the processes to complete and then click Next . Finally, on the  Installation Finished screen, click  Done to finish installation of your DataSync Agent.   NOTE :  Optionally, you can  Generate an automatic installation script on this screen and then choose a directory to save your install script in. This script can then be run on another device to install a DataSync Agent with the same settings you've specified here. The following system files will be installed within the  bin/perspectium_data directory and used for temporary storage/caching when your DataSync for ServiceNow Agent is running: psp.in .agent.errors psp.in .messageset psp.out.servicenow. INSTANCE_NAME   (where  INSTANCE_NAME   is from your https:// INSTANCE_NAME . service-now.com URL) psp.in .servicenow TableStatsPublisher A perspectium.log  file will also be installed that contains important log messages for your DataSync for ServiceNow Agent. For more information, see monitoring DataSync Agent logs .   NOTE : If the files listed above exceed 1 GB in size, you may delete these files to improve your DataSync Agent performance. (Optional) After installing your DataSync for ServiceNow Agent, it is highly recommend to confirm that you Agent is configured correctly by running the Agent validateConfiguration tool. To run the validateConfiguration tool on a Linux device, open a terminal window and change your current directory to the directory where you   installed your Agent in Step #3 . Then, execute the following command: bin/validateConfiguration start To run the validateConfiguration tool on a Windows device, navigate to the  bin directory that was installed within the main Agent directory that was specified in  Step #3 . Then, double-click to run the  validateConfiguration .bat file. The tool will attempt to connect to the Perspectium Integration Mesh, your ServiceNow instance (if configured, to test fetching a schema) and to your database, logging if it was successful making these connections or any failures that may occur. Contact  support@perspectium.com if you have questions on the connection failures. ↑ Go to top of page Install the DataSync Agent with a custom Java Runtime Environment  To ensure you have the latest version of Java, instead of using a custom JRE provided by Perspectium, it is recommend you install a JRE. See Adoptium for JREs based on OpenJDK. This is best for instances where you do not want to install the full Oracle JDK to run the DataSync Agent. With Perspectium's optimized JRE, it will include only the necessary java packages for installing and running the Agent. Prerequisites Make sure that the device you are installing the DataSync Agent on meets these basic requirements . You will also need to request the Agent Installer and the c ustom JRE from Perspectium Support . To install the agent with a custom JRE, follow these steps: Linux Environment  In your terminal, enter the following: gedit ~/.bashrc Then, add the following (this is the path of the custom JRE acquired from Perspectium Support ):  JAVA_HOME=/YourPath/customJreLinux For example:  ... #Export JAVA_HOME=/home/PSP/customJreLinux export PATH=$PATH:$JAVA_HOME/bin Save changes.  In your terminal, enter the following to refresh the environment variables:  source ~/.bashrc Then, run the agent installer by entering the following:  YourPath/customJreLinux/bin/java -jar YourPath/perspectium-datasync-installer-6.0.0.jar A pop-up may appear indicating that the Agent Installer file can't be opened because it is from an unidentified developer. If this happens, click OK to close the pop-up and then navigate to  System Preferences >  Security & Privacy . Under the  General tab, locate the section beginning with  Allow apps downloaded from: and click  Open Anyway . Then, click  Open in the resulting pop-up to open the Agent Installer wizard. Check the box to accept the terms of the Perspectium End User License Agreement . Then, click  Next . Choose a directory to install the DataSync Agent files in. If you specify a new directory, that directory will first be created and then populated with the Agent files. Then, click Next . Choose the option Use the directory defined in JAVA_HOME ..., then click Next . Follow the rest of Steps 5-12 from the Install the DataSync Agent through Agent Installer. Windows Environment On the Windows taskbar, right-click the   Windows   icon and select   System . Under   Related Settings , click   Advanced . Click  Environment Variables . Edit variable JAVA_HOME to be the path of JRE: C:\YourPath\customJreWindows.  If variable PATH has an entry for the java directory, edit PATH to also be path of JRE (if there is no java entry in PATH, skip this step). Open the Agent Installer .jar file. If you didn't receive this file, you can request one from Perspectium Support . A pop-up may appear indicating that the Agent Installer file can't be opened because it is from an unidentified developer. If this happens, click OK to close the pop-up and then navigate to  System Preferences >  Security & Privacy . Under the  General tab, locate the section beginning with  Allow apps downloaded from: and click  Open Anyway . Then, click  Open in the resulting pop-up to open the Agent Installer wizard. Check the box to accept the terms of the Perspectium End User License Agreement . Then, click  Next . Choose a directory to install the DataSync Agent files in. If you specify a new directory, that directory will first be created and then populated with the Agent files. Then, click Next . Choose the option Use the directory defined in JAVA_HOME ..., then click Next . Follow the rest of Steps 5-12 from the Install the DataSync Agent through Agent Installer. ↑ Go to top of page Install the DataSync Agent through Command Line The following is for Linux only. Prerequisites  First, you should  have received a download such as the following (per your version): perspectium-replicator-installer-VERSION.jar This is the file we will use to run the agent installer. Contact   support@perspectium.com   if you have not received this file.  You may use the browser to download directly and copy the file over.  Then, check the  DataSync Agent Requirements  to see if your system is compatible.  To install the DataSync Agent through the command line, follow these steps: 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 To run the installer from a linux console using a GUI, type the following (per your version): java -jar ./perspectium-replicator-installer-VERSION.jar 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 Press 1 to continue, 2 to quit, 3 to redisplay Press 1 to continue. You will be presented with the   End User License Agreement . Press   Enter   to continue until the end of the agreement. (There are about 20 pages of the EULA). 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. ... Press Enter to continue, X to exit ... 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. Afterwards, you will be asked for the installation destination, this is where the agent files will be copied. Press   Enter   to select the default or type in a new one.  Keep the directory within the home of the   perspectium   user. Select target path [/home/perspectium/Perspectium DataSync Agent] Then, 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.  Enter the supplied hostname and press Enter to continue. Enter the information for accessing the Perspectium Cloud Server: Server: [] server10.perspectium.com Then, 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.  Decryption Key: [Some decryption key here] 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 ] (Optional)  After successful installation of the agent, you have the 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. You can execute the auto-install.xml by running the following command: java -jar perspectium-replicator-installer.jar auto-install.xml (Optional)  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 . If you are using Java 14 or Java 15 with the Iodine 7.0.5 or older , remove the wrapper.jar and wrapperApp.jar files from the lib folder of the agent directory and import the new wrapper.jar and wrapperApp.jar files provided by Perspectium Support.   NOTE : Iodine 7.0.6 and newer versions do not have to do this step. Execute the following command within the lib folder of the agent directory to remove the files: rm wrapper.jar rm wrapperApp.jar Then, e xecute the following command to add the new files: mv wrapper.jar /Perspectium_DataSync_Agent/lib mv wrapperApp.jar /Perspectium_DataSync_Agent/lib ↑ Go to top of page Next steps Start or stop the DataSync Agent