Skip to end of metadata
Go to start of metadata

Overview

These are the system requirements and instructions on downloading, installing, configuring, restarting, upgrading, rolling back, and uninstalling the Harmony Private Agent on a Linux system. Prior to installation, we recommend reviewing Agent Groups High Availability and Load Balancing and Private Agents Best Practices Tech Talk.

System Requirements

Best Practices

  • Supported systems: Install the Private Agent on a tested and supported system as listed on this page. For optimal results, we recommend you follow these prerequisites and requirements for the operating system, PostgreSQL database, and hardware.
  • High availability and load balancing: Prior to installation, review the recommendations for high availability (active/active) and load balancing as described in Agent Groups High Availability and Load Balancing.
  • Server installation: For production environments, we recommend installing the Private Agent on a server. Agent installation on a desktop machine is recommended only for development, quality control, or testing environments.
  • Clean installation: Do not install the Private Agent on a server that is already running another database. The agent installs and runs its own PostgreSQL database. Running the agent on a server that is already running an Oracle or SQL Server database may cause performance issues.
  • Same timezone: We recommend that all agents in a Private Agent Group have the same timezone. Because the timezone of configured schedules is dependent upon the Private Agent timezone, schedule runs may be unpredictable if the timezones are different.
  • Uninstalling: Before uninstalling, we recommend you copy the config files and security certificates of your current installation in the event you want to reinstall with the same configuration at a later time.

Operating System Requirements

The Linux version of the Jitterbit Harmony Private Agent requires a 64-bit OS. It is supported for these distributions derived from Debian Linux and Red Hat Enterprise Linux for Intel hardware:

  • Debian 8.10 ("jessie") and 9.4 ("stretch")

  • Ubuntu 14.04 LTS and 16.04 LTS

  • Red Hat Enterprise Linux (CentOS) 6 and 7
  • Amazon Linux AMI
The Harmony Private Agent has not been certified against other similar distributions with Debian or RPM package distributions derived from the Debian and Red Hat distributions. Amazon Linux provides multiple Linux versions, of which only Amazon Linux AMI has been certified. Amazon Linux 2 is not currently supported.

Prerequisite Software Requirements

Required Commands

The jitterbit-agent package can be installed across many versions of Linux distributions; it has very few explicit package dependencies. However, these commands must be available:

Required Commands
python
sed
sudo
tar
unixodbc
unzip

You can test the availability of a command by running the which command.

Required Libraries

Though Jitterbit Harmony Agents are not built natively to run in 64-bit mode on 64-bit distributions, Jitterbit requires running the agent on a 64-bit operating system with the required 32-bit libraries installed.

You will need these 32-bit libraries (they should come as part of even a minimal installation of any supported distribution; these packages may be named differently depending on the distribution):

32-bit Libraries
libc.so.6
libgcc_s.so.1
libm.so.6
librt.so.1
libstdc++.so.6
libuuid.so.1
libz.so.1

Debian-based Systems

To install the required 32-bit libraries and update the required packages on 64-bit Debian or Ubuntu, run this command:

64-bit Debian or Ubuntu
$ sudo apt-get update
$ sudo apt-get install libc6:i386 libgcc1:i386 libstdc++6:i386 libuuid1:i386 zlib1g:i386 libc6 libgcc1 libstdc++6 libuuid1 zlib1g python sed sudo unixodbc unzip tar

RPM-based Systems

If using Amazon Linux AMI, first run this command to update required packages:

Amazon Linux AMI
$ sudo yum -y install libgcc44.i686 libstdc++44.i686

To install the required 32-bit libraries and update the required packages on 64-bit RHEL (CentOS) 6 and 7, or Amazon Linux AMI, run this command:

64-bit RHEL or CentOS
$ sudo yum update
$ sudo yum -y install glibc.i686 libgcc.i686 libstdc++.i686 libuuid.i686 zlib.i686 pam.i686 cyrus-sasl-lib.i686 libicu.i686 python sed sudo unixODBC unzip tar

Troubleshooting

32-bit and Debian Systems: If installing 32-bit libraries fails on Debian systems, you may have to add the repository for 32-bit packages with these commands:

Debian or Ubuntu
$ sudo dpkg --add-architecture i386
$ sudo apt-get update    

GLIBC Errors: If you are unable to install due to "GLIBC_2.14 not found" on certain older systems, edit  /etc/apt/sources.list to add this line:

Debian or Ubuntu
deb http://ftp.debian.org/debian/ jessie main

Then run:

Debian or Ubuntu
$ sudo apt-get update
$ sudo apt-get -t experimental install libc6-dev
$ ldd --version
// check that GLIBC >=2.14

Multilib version problems found: If installing 32-bit libraries fails on RedHat systems with "Error: Multilib version problems found", then you may need to apply upgrades to the operating system (using $ sudo yum update) and try again in order to bring the 64-bit libraries up-to-date with the 32-bit version that you are trying to install.

You may find that installing the development version of the libraries may resolve these errors. Replace the install step listed above for RPM-based systems with:

$ sudo yum update
$ sudo yum -y install libuuid-devel.i686 zlib.i686 pam.i686 cyrus-sasl-lib.i686 libicu.i686 python sed sudo unixODBC unzip tar

Broken or missing dependency: If you have a library with a broken or missing dependency, check for proper links to the source by using the ldd command to return a list of dependencies. For example:

$ ldd /opt/jitterbit/lib/libkonga-zip.so

You can also use the package name to check the installation status of the dependency, using the same naming convention as for installation:

Debian or Ubuntu
$ dpkg -s zlib1g:i386

or

RHEL or CentOS
$ yum list installed libgcc.i686

Required Java Version

The Jitterbit Harmony Agent package is bundled with a 64-bit version of the Java 8 Runtime Environment (JRE) and does not require a separate Java runtime. Jitterbit automatically installs the required Java Runtime Environment specifically for Jitterbit to use so that it does not conflict with other Java installations that may already be installed. As of Harmony 9.8, the version of Java shipped with the Agent is the AdoptOpenJDK JRE. This JRE is licensed as described at the OpenJDK website.

Jitterbit can be configured to use an external JRE. The minimum version is 1.8 (Java 8). To change the Java runtime used by the Jitterbit Harmony Agent, edit the file /etc/sysconfig/jitterbit to use the appropriate version of Java runtime and restart all Jitterbit services.

Unlimited Strength Java Cryptography Extension Requirement

For the agent to securely communicate with resources such as servers, the Java Runtime Environment used by the agent should be using the Java Cryptography Extension (JCE) with Unlimited Strength Jurisdiction Policy Files. If you are using the JRE that is shipped with the agent, it is using JCE with Unlimited Strength Jurisdiction Policy Files.

If you substitute a different JRE for the one shipped with the agent, you will need to replace the policy files included with the JRE with Unlimited Strength Jurisdiction Policy Files, if it is not already using them. To install the Java Cryptography Extension Unlimited Strength Jurisdiction Policy Files:

  1. Go to the Oracle website to download the ZIP file containing Java Cryptography Extension (JCE) Unlimited Strength Jurisdiction Policy Files.
  2. Unpack the ZIP to extract the local_policy.jar and US_export_policy.jar JAR files.
  3. Copy and replace the existing JAR files found in <JITTERBIT_HOME>\jre\lib\security, replacing <JITTERBIT_HOME> with the path to your Private Agent root directory.
  4. Restart the Jitterbit Private Agent.

PostgreSQL Requirements

PostgreSQL is installed as part of the Harmony Private Agent installation. This instance of PostgreSQL is for use only with and by Jitterbit.

  • Do not install PostgreSQL separately prior to installing Jitterbit. The Jitterbit installation automatically installs the 64-bit, 9.6.11 version of PostgreSQL with the PostgreSQL 9.3 ODBC driver. (Jitterbit Agent upgrades do not upgrade an existing PostgreSQL installation to this version; they are left as-is.)
  • Do not have any other databases configured or running on the Jitterbit PostgreSQL instance.
  • Do not use the Jitterbit PostgreSQL database/server as part of any Jitterbit operations and transformations.
  • Do not use Windows compression on the Jitterbit folder, PostgreSQL folder, or temp folder on the machine where Jitterbit is installed and running. Using Windows compression will drastically slow down processing of Jitterbit operations and transformations.
  • PgBouncer may be required for high-load environments. Jitterbit Harmony Windows Agent versions 8.21 and later automatically install PgBouncer. If you already have an existing installation of PgBouncer and experience issues upgrading, please contact support for assistance.

Hardware Requirements

These are the minimum requirements for hardware and virtual machines for Jitterbit Harmony Private Agents:

  • Quad-core processor
  • 8 GB RAM
  • 50 GB hard drive space free; this includes space for the software, parallel processing, and temporary storage that can grow quite large while running an operation

  • Minimum of 50 megabytes/second transfer rate on the hard drive
  • High-speed Internet connection
  • A direct hardware installation or an installation on a virtual machine from VMWare, VirtualBox, Amazon AWS, or Rackspace that is configured for the specific requirements outlined above
  • Optimal configuration of the system and overall environment; if not optimally configured, sporadic and unpredictable problems can result from poor disk IO, limited/out of memory, limited/out of disk space, power failures, and/or abrupt system restarts

  • Access to outbound port 443 (HTTPS) to communicate with Harmony. Port 443 is normally allowed by corporate server firewalls.

  • Access to specified inbound ports as needed;  generally, inbound ports do not need to be opened

It is recommended that the Jitterbit API platform be used for inbound messages or data. Where a Private Agent is used to receive a message directly (such as an outbound message from Salesforce) in lieu of the Jitterbit API platform, then the inbound ports 443 (with SSL) or 46909 (HTTPS) could be opened. Custom ports may be used for specific requirements if they are redefined in the Private Agent configuration and are allowed by any corporate firewall.

Download Agent

These instructions on downloading a Linux Private Agent assume you have already created an Agent Group and Private Agent(s) for your organization within the Management Console. Refer to Agents > Agent Groups and Agents > Agents for more information.

  1. Log in to the Jitterbit Harmony Portal and go to the Management Console > Agents > Agent Groups
  2. In the upper portion of the screen, select the Agent Group row. The lower half of the screen should now list the Available Agents within the selected Agent Group.
  3. In the lower portion of the screen, select the agent row. Then click the Action dropdown on the far right and select Download for Linux RPM or Download for Linux DEB depending on your needs.
  4. The Linux agent executable can be downloaded once, stored locally, and reused to install any additional Private Agents as they are added.

Install Agent

All installation commands require root access. It is recommended that the installation be performed using a command line, as the installation generates important messages.

Debian-based Systems

These instructions are for Debian-based systems, including Ubuntu:

  1.  Use this dpkg command to install the Debian package:

    Debian or Ubuntu
    $ sudo dpkg --install jitterbit-agent_<VERSION>_i386.deb

    If the command fails due to missing dependencies, the Jitterbit Harmony Agent package will be installed but not configured. Make sure all dependencies are satisfied (as described above), purge the package, and install it again:

    Debian or Ubuntu
    $ sudo dpkg --purge jitterbit-agent
    $ sudo dpkg --install jitterbit-agent_<VERSION>_i386.deb
  2. The Jitterbit Harmony Agent is installed in /opt/jitterbitThis location cannot be changed.
  3. Upon successful installation, the name of the installed package is:

    jitterbit-agent

RPM-based Systems

These instructions are for RPM-based systems such as Red Hat or CentOS:

  1. Change to the download directory, then download and install the Jitterbit public key to verify the RPM packages:

    RHEL or CentOS
    $ wget http://download.jitterbit.com/utils/JITTERBIT-RPM-GPG-KEY
    RHEL or CentOS 6
    $ sudo rpm --import JITTERBIT-RPM-GPG-KEY
    RHEL or CentOS 7
    $ sudo rpmkeys --import JITTERBIT-RPM-GPG-KEY
  2. Verify the integrity of the downloaded RPM package (optional):

    RHEL or CentOS 6
    $ rpm --checksig jitterbit-agent-<VERSION>.i386.rpm
    RHEL or CentOS 7
    $ rpmkeys --checksig jitterbit-agent-<VERSION>.i386.rpm
  3. Use this yum command to install the RPM package. All package dependencies will be automatically downloaded and installed:

    RHEL or CentOS
    $ sudo yum install jitterbit-agent-<VERSION>.i386.rpm
  4. The default installation prefix used is /opt, which installs Jitterbit Harmony Agent in /opt/jitterbit. It is not recommended to change this; however, to install with another prefix (such as /usr/local) use the --prefix option of the rpm command:

    RHEL or CentOS
    $ sudo rpm -Uvh --prefix=/usr/local jitterbit-agent-<VERSION>.i386.rpm

    NOTE:  If you choose to change the default installation location, you must specify the same prefix when upgrading the Jitterbit Harmony Agent.

  5. Upon successful installation, the name of the installed package is:

    jitterbit-agent

Configure Agent

Jitterbit Harmony Agents cannot be started without completing the configuration step. Starting the Jitterbit Harmony Agent without configuring will result in this error:

NOTE: Agent credentials have not been configured.
Run the Jitterbit configuration tool /opt/jitterbit/bin/jitterbit-config

Before running the configuration script, you must ensure that the corresponding Private Agent and the Agent Group have been created using the Jitterbit Harmony Management Console. The configuration script will provide you with a list of agents you can configure against. If you have not already set these up, see the documentation on Agents > Agent Groups and Agents > Agents.

Run the script jitterbit-config and enter the required information at the prompt:

$ sudo jitterbit-config

You will need this information:

  1. Your Jitterbit Harmony credentials (the email address and password you use to log in to https://login.jitterbit.com).

    CAUTION: If your organization and account uses single sign-on (SSO), your normal SSO credentials will not work. You must use Harmony credentials to install Private Agent(s). See the section Install Private Agent with Harmony Credentials in Setting Up SSO in Jitterbit for more information.
  2. The name of the organization that you are installing the agent for.

    NOTE: You must be an Administrator in the organization. See Organizations for more information.
  3. The name of the Agent Group that the agent will be assigned to.
  4. The name of the agent that you are installing as. 

    NOTE: The script will display the list of agents that are not running.

Here is an example of running the configuration script:

jitterbit-config
Please enter your Jitterbit Harmony user name
This is the email that you used to register on the Jitterbit Harmony platform
Enter your Jitterbit Harmony user name: john.doe@example.com
You entered: john.doe@example.com
Please enter your Jitterbit Harmony password: 
There is only one organization available
Do you want to use 'Example, Inc' [y/n]: y
Select agent group:
[1] Agent Group 1
[2] Agent Group 2
Please select an agent group [1-2]: 1
You selected: Agent Group 1
Select agent:
[1] Linux Agent 1
[2] Linux Agent 2
Please select an agent [1-2]: 2
You selected: Linux Agent 2

Agent successfully configured
Restart your agent for the changes to take effect

As noted in the script, you must restart the agent in order for the configuration to take effect. This is covered in the next section, Restart Agent.

Advanced Configuration Options

Using SELinux

The Jitterbit Harmony Agent installation process will add a SELinux configuration that allows Jitterbit Harmony Agent to be installed on SELinux kernels. However, it may interfere with the Jitterbit Harmony Agent database (PostgreSQL). If you are unable to successfully install and configure the Jitterbit Harmony Agent, you must disable SELinux.

Use this command to verify if SELinux is enabled:

$ /usr/sbin/sestatus

To disable SELinux you must edit the /etc/sysconfig/selinux file to read SELINUX=disabled and restart your system.

Configuring PostgreSQL

Jitterbit Harmony Agent includes a PostgreSQL database bundled with the installation. The database instance is created during the installation and is configured to run on port 46914.

You can configure the Jitterbit Harmony Agent to be configured against a separate PostgreSQL database by running the configuration script with the -c option:

$ sudo /opt/jitterbit/bin/jitterbit-config -c

You will need the PostgreSQL configuration. When configuring the PostgreSQL database, an ODBC driver PostgreSQL-jitterbit is installed. It is recommended to use this driver and not default to the PostgreSQL driver included with the Linux distribution.

Reconfiguring Jitterbit Harmony Agent

You can configure an existing Jitterbit Harmony Agent to run as a different agent (such as in a different Agent Group). To do this, you must stop the services, reinitialize the Jitterbit Harmony Agent database, and run the configuration script again. Use these commands in this particular sequence (note that all the commands must be run as root):

$ sudo jitterbit stop
$ sudo jitterbit initdb
$ sudo jitterbit-config
$ sudo jitterbit start

Once the Jitterbit Harmony Agent is restarted, it is automatically synchronized to be able to process all operations serviced by the new Agent Group.

Adding Certificates to Jitterbit Agent Keystore

Jitterbit Agents use standard HTTPS to communicate securely over the internet. All Jitterbit Agents are installed with a trusted keystore containing all of the certificates that are needed to communicate securely.

A new certificate may be added by the user to the Jitterbit Agent keystore. The ability to add a new certificate is important if a Jitterbit Agent is configured to use a proxy server. Any certificates originating from the proxy server that need to be included in the Jitterbit Agent keystore may be added to allow the Jitterbit Agent to communicate securely through the proxy server. 

For configuring the Jitterbit Harmony Agent to use a proxy server, please see Enabling Proxy for Private Agents.

  • Java KeyStore (JKS): Jitterbit Agents use the standard Java KeyStore (JKS) repository bundled with Java as the repository of all certificates. The keystore is named "cacerts" and by default is located at: 

    /opt/jitterbit/jre/lib/security/cacerts
  • Default Password: The default password for the Jitterbit Agent keystore is the default password for any JKS, which is "changeit".  It is recommended that you change the password using this command, replacing <new_storepass> with the new password:

    $ sudo /opt/jitterbit/jre/bin/keytool -storepasswd -new <new_storepass> -keystore /opt/jitterbit/jre/lib/security/cacerts
  • List of Certificates: This command will list all of the certificates in the Jitterbit Agent's keystore:

    $ sudo /opt/jitterbit/jre/bin/keytool -list -keystore /opt/jitterbit/jre/lib/security/cacerts
  • Add a New Certificate: Use this command to add a new certificate to the Jitterbit Agent's keystore, substituting for <alias> and <certfile>:

    $ sudo /opt/jitterbit/jre/bin/keytool -importcert -trustcacerts -alias <alias> -file <certfile> -keystore /opt/jitterbit/jre/lib/security/cacerts
  • Configure a Jitterbit Agent to Not Accept All Certificates By Default: When installing a Jitterbit Agent using a proxy server, you can configure the agent to accept all certificates by default. This will speed up the installation and development processes. We recommend that before deploying an agent to production that these steps be performed:

    1. Add the list of certificates originating from the proxy server using the command above to add a new certificate.
    2. Configure the Jitterbit Agent to validate against the list of certificates in its keystore:

      $ sudo jitterbit-utils --verify-proxy-cert

Restart Agent

Restarting agent services is required whenever you have made changes to your agent configuration. Restarting the agent can also be a good troubleshooting step if you are experiencing issues, which may be resolved upon restarting. You must restart the Agent any time the configuration script is run or changes to the configuration file (/opt/jitterbit/jitterbit.conf) are made.

Though the agent can be stopped and then restarted directly from the machine where the Private Agent is installed, it is best if it is first stopped from the Management Console using the "Drain Stop" command, and then restarted using a command on the Private Agent machine itself.

The "Drain Stop" command will wait for a period of time to complete existing operations and refuse to accept new ones. Long-running operations may be canceled instead of completing. Once stopped, the agent can only be restarted manually from the Private Agent machine directly.

  1. From the Management Console, select Drain Stop from the menu for the Agent. The agent will then stop. You may need to refresh the webpage to see an updated status.
  2. If the Agent does not stop or respond to the Management Console, you can stop the Agent using:

    $ sudo jitterbit stop
  3. The agent can then be restarted from the machine where the Private Agent is installed by using:

    $ sudo jitterbit start

Once the Private Agent is started successfully, the status of the agent in the Jitterbit Harmony Management Console (Menu > Agents) will be "Running." Note that it can take more than a minute for the Jitterbit Harmony Agent to start up and register with Jitterbit Harmony. You can also check the status of the Agent locally.

Starting the Services at System Startup

The Jitterbit Harmony Agent package will attempt to configure your system to automatically start the Jitterbit Harmony Agent on system boot and uses SysV-style initialization, which is generally supported on all distributions.

If your system does not use SysV-style initialization, you can add the command /opt/jitterbit/bin/jitterbit start toward the end of your startup script. You can also add the command /opt/jitterbit/bin/jitterbit stop to the shutdown script.

Agent Status

You can check the status of the Agent on the machine by running the status option of the jitterbit command:

$ sudo jitterbit status
JitterbitProcessEngine is running with PID XXX
JitterbitScheduler is running with PID XXX
JitterbitFileCleanup is running with PID XXX
All services are running

Upgrade Agent

Upgrading the Private Agent package on Linux can be performed by using the same commands used during initial installation. You do not need to run the configuration script when upgrading an existing Jitterbit Harmony Agent.

A Private Agent takes a very short time to upgrade—on the order of three minutes—depending on the server. If having any outage is a concern, you can use high availability (two or more agents) and have no downtime. If your current subscription does not have additional agents available for this, contact your Customer Success Manager (CSM) for assistance.

  1. Back up your config files and security certificates (optional; see Uninstall Agent below).
  2. Install the new version of the agent (see Install Agent above).
  3. To use your backup files (optional):
    1. Stop agent services (see Restart Agent above).
    2. Place your saved config files and security certificates in the installation directory.
    3. Start agent services (see Restart Agent above).
NOTE: If you changed the default installation prefix on RPM-based systems, you must specify the same prefix when upgrading the Jitterbit Harmony Agent.

Roll Back Agent

It is not expected to be required to revert to a previous version of a Private Agent. However, should it be required, these are the steps:

  1. Back up your config files and security certificates (optional; see Uninstall Agent below).
  2. Uninstall the agent (see Uninstall Agent below).
  3. Remove all Jitterbit-related files (see Uninstall Agent below).
  4. Install the selected version of the agent (see Install Agent above).
  5. To use your backup files (optional):
    1. Stop agent services (see Restart Agent above).
    2. Place your saved config files and security certificates in the installation directory.
    3. Start agent services (see Restart Agent above).

Uninstall Agent

Before uninstalling, it is recommended to copy the config files and security certificates for your current installation in case you want to reinstall with the same configuration in the future. These are typically located at:

Files
/opt/jitterbit/jitterbit.conf
/opt/jitterbit/apache/conf/httpd.conf
/opt/jitterbit/JdbcDrivers.conf
Directories
/opt/jitterbit/apache/conf/extra/
/opt/jitterbit/apache/conf/ssl.crt/
/opt/jitterbit/apache/conf/ssl.key/
NOTE: To be able to use your backup files in a future installation, you must stop services while you move the files over, then restart services once completed (see Restart Agent).

Debian-based Systems

Use this dpkg command to uninstall the Jitterbit Harmony Agent:

Debian or Ubuntu
$ sudo dpkg --remove jitterbit-agent

 You can also use this apt-get command to uninstall the Jitterbit Harmony Agent:

Debian or Ubuntu
$ sudo apt-get remove jitterbit-agent

RPM-based Systems

Use this yum command to uninstall the Jitterbit Harmony Agent:

RHEL or CentOS
$ yum remove jitterbit-agent

You can also use this rpm command to uninstall the Jitterbit Harmony Agent:

RHEL or CentOS
$ rpm --erase jitterbit-agent

Removing All Jitterbit-related Files

The uninstall will remove the files installed during the installation. The /opt/jitterbit directory is not automatically erased, and may include log files and application files generated when running operations. Also, the Jitterbit Harmony Agent database is not erased automatically. To completely remove all Jitterbit-related files, use these two commands:

$ sudo rm -rf /opt/jitterbit
$ sudo rm -rf /tmp/jitterbit
On This Page

Related Topics

Last updated:  Jul 26, 2019

  • No labels