Skip to Content

Jitterbit private agents on Linux

Introduction

This page shows you how to install and run a private agent on Linux. The Troubleshoot section gives a list of common issues and their solutions.

Install

To install a private agent, follow these steps:

  1. Satisfy the prerequisites.

  2. Download a private agent installation package.

  3. Run the private agent installer.

  4. Configure and start the private agent.

Prerequisites

You must have the following:

  • A host that meets the system requirements.

  • Your Harmony organization name, and Harmony account username and password.

  • The name and ID of a private agent group.

  • An account with root privileges.

The following are optional:

  • Add an agent in the Management Console. If you don't have any unregistered private agents in the agent group, one is automatically created with a name that includes the host's name and IP address.

  • A PostgreSQL database server is installed automatically. To use your own, you must set it up before installing the private agent, and know its name or IP address, its port number, and the details of the database administrator account.

The following are recommended:

Download

To download the private agent software, go to the Harmony Portal Downloads page.

Tip

If you have already added an agent on the Management Console Agents page, click the agent's Download Jitterbit Agent icon.

Download one of the following private agent Linux packages:

  • Linux Debian (x64): The .deb package file, for installing on Debian or Ubuntu Linux as root.

  • Linux RPM: The .rpm package file, for installing on Red Hat Linux as root.

  • Linux Redhat Non-Root (x64): The .tar file, for installing on Red Hat Linux as a non-root user.

Installer

Run the following commands for the downloaded installer type:

As root
apt-get install <PATH>/jitterbit-agent_<VERSION>_amd64.deb
update-alternatives --install /usr/bin/python python /usr/bin/python2 1
As root
yum install <PATH>/jitterbit-agent-<VERSION>.x86_64.rpm

  1. Log in as a non-root user with sudo privileges.

  2. Install required packages:

    sudo dnf install -y unzip

    Note

    This may already be installed on your system, depending on how it was set up.

  3. Create the jitterbit user:

    As non-root user
    sudo useradd --user-group jitterbit --base-dir /opt --groups wheel
sudo passwd jitterbit

  4. Exit the non-root user shell.

  5. Log in as jitterbit.

  6. Create a user systemd service file:

    As jitterbit
    mkdir -p $HOME/.config/systemd/user
cat > $HOME/.config/systemd/user/jitterbit.service <<EOF
[Unit]
Description=Jitterbit private agent
Documentation=https://docs.jitterbit.com/agent/linux/
After=default.target

[Service]
Type=forking
Environment=JITTERBIT_HOME=/opt/jitterbit
Environment=PG_HOME=\${JITTERBIT_HOME}/pgsql
Environment=PG_DATA=\${JITTERBIT_HOME}/DataInterchange/pgsql/data
Environment=LD_LIBRARY_PATH=\${JITTERBIT_HOME}/lib:\${JITTERBIT_HOME}/psql/lib
Environment=PATH=\${JITTERBIT_HOME}/bin:\${JITTERBIT_HOME}/pgsql/bin:/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin
ExecStart=/opt/jitterbit/bin/jitterbit start
ExecStop=/opt/jitterbit/bin/jitterbit stop
TimeoutSec=600

[Install]
WantedBy=default.target
EOF

  7. Reload the systemd daemon, enable the service, and let systemd services run when the user is not logged in:

    As jitterbit
    systemctl --user daemon-reload
systemctl --user enable jitterbit.service
loginctl enable-linger

  8. Set up the shell environment:

    As jitterbit
    mkdir -p $HOME/.bashrc.d
cat >> $HOME/.bashrc.d/jitterbit <<EOF
export JITTERBIT_HOME=/opt/jitterbit
export ODBCINI=\${JITTERBIT_HOME}
export ODBCSYSINI=\${JITTERBIT_HOME}/odbcinst.ini
export PG_HOME=\${JITTERBIT_HOME}/pgsql
export PG_DATA=\${JITTERBIT_HOME}/DataInterchange/pgsql/data
export LD_LIBRARY_PATH=\${JITTERBIT_HOME}/lib:\${JITTERBIT_HOME}/psql/lib
export PATH=\${JITTERBIT_HOME}/bin:\${JITTERBIT_HOME}/pgsql/bin:/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin
EOF
. ./.bashrc

  9. (Optional) Check the environment:

    As jitterbit
    env | grep jitterbit

    The output should look like this:

    PWD=/opt/jitterbit
LOGNAME=jitterbit
HOME=/opt/jitterbit
PG_HOME=/opt/jitterbit/pgsql
PG_DATA=/opt/jitterbit/DataInterchange/pgsql/data
JITTERBIT_HOME=/opt/jitterbit
ODBCINI=/opt/jitterbit/odbcinst.ini
USER=jitterbit
LD_LIBRARY_PATH=/opt/jitterbit/lib:/opt/jitterbit/psql/lib
ODBCSYSINI=/opt/jitterbit
PATH=/opt/jitterbit/bin:/opt/jitterbit/pgsql/bin:/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin
MAIL=/var/spool/mail/jitterbit

    Important

    The highlighted values are important, especially JITTERBIT_HOME, which must always be /opt/jitterbit.

  10. Unpack the downloaded tar file:

    As jitterbit
    tar -C /opt -xf <PATH>/jitterbit-agent-<VERSION>.x86_64.tar
    • <PATH>: The path to the downloaded .tar file, in a directory with read permissions for the jitterbit user.

  11. Run the installer:

    As jitterbit
    $HOME/scripts/install.sh

Important

You must now configure the private agent.

Configure

To configure, register, and restart a private agent on Linux, follow these steps:

  1. Run this command:

    As root
    jitterbit-config
    As root
    jitterbit-config
    As jitterbit
    jitterbit-config

    At the following prompt, enter y:

    Warning: this tool requires root privileges.
Hint: Use sudo or log on as the root user.
Do you want to continue as the current user? [y/n]:

  2. (Optional) To let the agent communicate via a proxy server, add the required options.

  3. When prompted, enter your Harmony account username and password, and select the options corresponding to your organization, agent group, and agent.

  4. Run this command:

    As root
    jitterbit restart
    As root
    jitterbit restart
    As jitterbit
    jitterbit restart

Upgrade

You must stop and restart an agent for minor (11.x to 11.y, or 10.x to 10.y) and major (10 to 11) version upgrades. Major version upgrades also require a complete uninstall and reinstall, and a full synchronization of environments.

Tip

To minimize the impact of agent downtime on your integration projects, you should have more than one agent in the agent group.

To upgrade a private agent on Linux, follow these steps:

  1. Download an installer package.

  2. If the agent is still processing operations, drain pause it.

    Or, if you are sure nothing is running on the agent, drain stop it.

  3. Monitor the agent log file. Continue when all operations have completed processing.

  4. Make backup copies of the following files:

    Location File
    /opt/jitterbit/ jitterbit.conf
    /opt/jitterbit/ JdbcDrivers.conf
    /opt/jitterbit/Resources/ jitterbit-agent-config.properties
    /opt/jitterbit/apache/conf/ httpd.conf
    /opt/jitterbit/apache/conf/ *.crt
    /opt/jitterbit/apache/conf/ *.key
    /opt/jitterbit/apache/conf/extra/ *.conf
    /opt/jitterbit/jre/lib/security/ cacerts

  5. Run the following command for the downloaded installer type:

    As root
    apt-get upgrade <PATH>/jitterbit-agent_<VERSION>_amd64.deb
    As root
    yum upgrade <PATH>/jitterbit-agent-<VERSION>.x86_64.rpm
    As jitterbit
    tar -C /opt -xf /<PATH>/jitterbit-agent-<VERSION>.x86_64.tar
    • <PATH>: The path to the downloaded .tar file, in a directory with read permissions for the jitterbit user.

  6. Compare the following files with your backup copies and restore any changed settings:

    Location File
    /opt/jitterbit/ jitterbit.conf
    /opt/jitterbit/ JdbcDrivers.conf
    /opt/jitterbit/Resources/ jitterbit-agent-config.properties
    /opt/jitterbit/apache/conf/ httpd.conf
    /opt/jitterbit/apache/conf/extra/ *.conf
    /opt/jitterbit/jre/lib/security/ cacerts

  7. If you have backup .crt or .key files that are not already in /opt/jitterbit/apache/conf/, copy them to that location.

  8. (Optional) During the environment synchronization period, agents won't accept integration project operations for processing. You can minimize the impact of this downtime with a rolling upgrade approach.

    To do this, open jitterbit-agent-config.properties file for editing, and add or set the property agent.starting.standby=true. (This keeps the agent in Starting status and prevents it from processing operations until the property value is set to false.)

  9. Restart the agent:

    As root
    jitterbit restart
    As root
    jitterbit restart
    As jitterbit
    jitterbit restart

  10. (Optional) If you are doing a rolling upgrade with the property value agent.starting.standby=true, and before upgrading another agent in the same group, monitor the agent log file for the following message:

    Agent synchronization for environment <123456> and agent group ID <987654> completed at ...

    This message indicates that the agent has completed environment synchronization. When it appears, edit jitterbit-agent-config.properties again, delete the property agent.starting.standby (or set it to false), then restart the agent.

Uninstall

To uninstall a private agent on Linux, follow these steps:

  1. Stop the agent.

  2. (Optional) Make backup copies of the following files:

    Location File
    /opt/jitterbit/ jitterbit.conf
    /opt/jitterbit/ JdbcDrivers.conf
    /opt/jitterbit/Resources/ jitterbit-agent-config.properties
    /opt/jitterbit/apache/conf/ httpd.conf
    /opt/jitterbit/apache/conf/ *.crt
    /opt/jitterbit/apache/conf/ *.key
    /opt/jitterbit/apache/conf/extra/ *.conf
    /opt/jitterbit/jre/lib/security/ cacerts

  3. To remove the installation files (including PostgreSQL and its data directory), the service startup file, and the jitterbit user account, run these commands:

    As root
    apt-get remove --autoremove jitterbit-agent
userdel --remove --force jitterbit
    As root
    yum remove jitterbit-agent
userdel --remove --force jitterbit
    As a non-root user other than 'jitterbit'
    sudo userdel --remove --force jitterbit

Manage

You can start, stop, and show the status of a private agent with the jitterbit command. You can also use the Management Console to stop an agent remotely, but can only restart it again in a terminal on the host. Except for non-root installations, you can also restart the agent by restarting the host.

Note

Agents started with automatic registration may automatically de-register when stopped.

Start

Private agents installed from a .deb or .rpm package file start automatically with the host. For non-root .tar file installations, you must add a system script to start the agent, or start it manually.

Note

It can take several minutes for a private agent to complete synchronization and be in running status.

To start a private agent on Linux, run this command:

As root
jitterbit start
As root
jitterbit start
As jitterbit
jitterbit start

Stop

There are three ways to stop a private agent, each differing in how running operations are treated:

  • Drain pause: the agent rejects new operations, and allows running operations to continue to completion.

  • Drain stop: the agent rejects new operations, and allows running operations to continue to completion up to a period set by the parameter agent.drainstop.api.wait (by default, 180 seconds).

  • Hard stop: the agent rejects new operations and terminates running operations.

    Caution

    Hard stopping a private agent can result in data loss.

Drain pause

To drain pause a private agent on Linux, run the following command:

As root
jitterbit-utils --drain-pause
As root
jitterbit-utils --drain-pause
As jitterbit
jitterbit-utils --drain-pause

In the Management Console, the status is shown as Stopping.

To resume a paused agent on Linux, use the Start command.

Drain stop

To drain stop a private agent on Linux, use either of these options:

  • From the Harmony Portal menu, select Management Console > Agents. From the Action column of the agent to be stopped, select Action > Drain Stop, then click OK in the confirmation dialog.

  • Run the following command:

    As root
    jitterbit-utils --drain-stop
    As root
    jitterbit-utils --drain-stop
    As jitterbit
    jitterbit-utils --drain-stop

Hard stop

To hard stop a private agent on Linux, run this command:

As root
jitterbit stop
As root
jitterbit stop
As jitterbit
jitterbit stop

Warning

Hard stopping a private agent can result in data loss.

Status

To see the agent's status, use either of these options:

  • From the Harmony Portal menu, select Management Console > Agents.

  • Run this command:

    As root
    jitterbit status
    As root
    jitterbit status
    As jitterbit
    jitterbit status

Troubleshoot

These sections in the Troubleshoot page may help when troubleshooting private agent installations on Linux: