Skip to Content

Install a Jitterbit private API gateway on Linux

Overview

These are the instructions for installing and configuring a private API gateway.

Note

The private API gateway was formerly known as the Jitterbit on-premises API gateway.

Prerequisites

To install a private API gateway, hardware and software must meet these requirements:

  • Linux server running a 64-bit operating system using one of these distributions:

    Note

    It may be possible to use other Linux distributions, but these are not currently supported by Jitterbit. As each distribution of Linux can vary, the instructions for installing the private API gateway on other Linux distributions may be different than described on this page.

  • These are the minimum requirements for hardware and virtual machines for a private API gateway:

    • Quad-core processor

    • 8 GB RAM

    • 50 GB available hard drive space

    • 50 megabytes/second transfer rate on the hard drive

    • High-speed Internet connection

    Caution

    Hard drive speed and space are critical components of the private API gateway, as request and response payloads are stored on the server during API transactions.

  • Optimal configuration of the system and overall environment running the private API gateway.

    Warning

    If not optimally configured, sporadic and unpredictable problems can result from network issues, poor disk I/O, limited or out of memory issues, limited or out of disk space, power failures, or abrupt system restarts.

  • A sub-domain or domain name, pointed to the server (for example, mysubdomain.example.com).

  • A valid SSL certificate for the sub-domain, from a recognized certificate authority:

    • Do not use a self-signed certificate.
    • Certificate should consist of two files: a CRT file (.crt) for the signed certificate and KEY (.key) for the private key.
    • These certificate files should be in the PEM format that an NGINX server can understand.
    • Sometimes the extension of the files are different; often CRT, PEM, and CER extensions are interchangeable.
    • It is also possible that the two files are combined into a single PFX file; in that case, use OpenSSL to extract the two files.
    • Remember to monitor certificate expiration dates!
    • Contact your certificate provider for additional information.
    • Free SSL certificates are available from providers such as Let's Encrypt.

  • As of Harmony version 10.3, by default the private API gateway no longer supports Transport Layer Security (TLS) 1.0 (see TLS version compatibility upgrade). To change this default setting, contact Jitterbit support.

  • To use a proxy configuration, private API gateway version 10.30.1 or later is required.

Install a private API gateway

After confirming the above prerequisites are met, follow these steps to set up a private API gateway:

Step 1: Set up the API gateway machine

  1. Set up a new Linux machine. It is recommended that the machine be dedicated for use by the private API gateway only.

    These additional recommendations depend on the operating system:

    • Red Hat Enterprise Linux (RHEL)

      If installing RHEL for the first time on this machine, we recommend using the Compute Node with these options included:

      • Debugging Tools
      • Hardware Monitoring Utilities
      • Compatibility Libraries
      • Development Tools
      • Security Tools

    • Ubuntu or Debian

      If installing Ubuntu or Debian, install with the defaults and include the OpenSSH server so that you can log in to the machine remotely.

  2. In many Linux environments, the firewall automatically blocks the HTTPS port (443) required for the private API gateway.

    To open the HTTPS port, use these commands as appropriate:

    64-bit RHEL or Amazon Linux AMI
    firewall-cmd --zone=public --add-port=443/tcp --permanent
firewall-cmd --reload

    or

    64-bit Debian or Ubuntu
    ufw allow 443/tcp

  3. Point the sub-domain or domain to the server's IP address.

  4. Confirm that you can SSH into the machine using an SSH client.

Step 2: Install the private API gateway software

To install the private API gateway software, log in to your machine via SSH and run the commands appropriate for your version of Linux. The download link and downloaded file will vary depending on the release and are in your registration information. The download files are also available through the Harmony portal Downloads page. Adjust the paths and filename accordingly:

To install a private API gateway version 10.61 or earlier (on REHL or Amazon Linux AMI) run these commands:

64-bit RHEL or Amazon Linux AMI private API gateway version 10.61 or Earlier
sudo -i

yum update

cd ~

wget https://download.jitterbit.com/xxxx/jitterbit-api-gateway-x.x.x-x.x86_64.rpm

yum install jitterbit-api-gateway-x.x.x-x.x86_64.rpm
To install a private API gateway version 10.62 or later (on REHL or Amazon Linux AMI) run these commands:

64-bit RHEL or Amazon Linux AMI private API gateway version 10.62 or Later
sudo -i

yum update

cd ~

# To install required dependencies:

yum install https://dl.fedoraproject.org/pub/epel/epel-release-latest-8.noarch.rpm

# To download and install the private API gateway:

wget https://download.jitterbit.com/xxxx/jitterbit-api-gateway-x.x.x-x.x86_64.rpm

yum install jitterbit-api-gateway-x.x.x-x.x86_64.rpm
To install a private API gateway version 10.61 or earlier (on Debian or Ubuntu) run these commands:

64-bit Debian or Ubuntu private API gateway version 10.61 or Earlier
sudo -i

cd ~

# To install required dependencies:

apt-get update

apt-get install libzzip-dev

apt-get install libyaml-dev

apt --fix-broken install

apt install python

# To download and install the API gateway:

wget https://download.jitterbit.com/xxxx/jitterbit-api-gateway-x.x.x.x.amd64.deb

dpkg --install jitterbit-api-gateway-x.x.x.x.amd64.deb
To install a private API gateway version 10.62 or later (on Debian or Ubuntu) run these commands:

64-bit Debian or Ubuntu private API gateway version 10.62 or Later
sudo -i

cd ~

# To install required dependencies:

apt-get update

apt-get -y install libgeoip-dev

apt --fix-broken install

ln -s /usr/bin/python2.7 /usr/bin/python

# To download and install the API gateway:

wget https://download.jitterbit.com/xxxx/jitterbit-api-gateway-x.x.x.x.amd64.deb

dpkg --install jitterbit-api-gateway-x.x.x.x.amd64.deb

Step 3: Install the SSL certificate files

The private API gateway requires that the certificate files for the machine be named nginx.crt and nginx.key and must be copied to these locations:

cp ca.crt /usr/local/openresty/nginx/ssl/nginx.crt

cp ca.key /usr/local/openresty/nginx/ssl/nginx.key

Once you have installed the SSL certificate files, they must be added to the Jitterbit Java keystore for your private agent. For more information, see Adding certificates to keystore for private agents.

Step 4: Configure the private API gateway

To complete the installation, run this command as root to configure the private API gateway:

/usr/bin/jitterbit-api-gateway-config

The private API gateway provides help on the command line:

/usr/bin/jitterbit-api-gateway-config --help

# Output:

Usage: jitterbit-api-gateway-config [options]

Options:
 -h, --help            show this help message and exit
 -u USER, --user=USER  Your Harmony user name (normally your email
                       address)
 -p PASSWORD, --password=PASSWORD
                       Your Harmony password
 -o ORGANIZATION_ID, --organizationId=ORGANIZATION_ID
                       Provide your Organization Id if you have more than one
                       organization
 -e ServiceUrl, --serviceUrl=ServiceUrl
                       Your Jitterbit Services URL (e.g.
                       https://services.jitterbit.net/apis
 -s NGINX_SERVER, --server=NGINX_SERVER
                       Valid values:   start   stop   restart
 -d, --dns             interactively config dns servers
 --proxyEnabled=PROXY_ENABLED
                       Enable (true) or disable (false) a proxy
 --proxyUri=PROXY_URI  When proxy is enabled, the Uri for your proxy server.
                       e.g. http://192.168.1.100:808
 --proxyUser=PROXY_USER
                       Proxy server username
 --proxyPassword=PROXY_PASSWORD
                       Proxy server password
 -t, --test            Run self tests
 --debug               Debug output for Self Tests
 --noColor             Turn off terminal text colors

You can either provide all of the required information on the command line or, by starting the command without any options, enter into an interactive session that prepares the private API gateway configuration file and then offers to start the gateway. The entered configuration is captured in the private API gateway configuration file /usr/local/openresty/nginx/conf/onpremise/gatewayconfig.yaml.

When configuring a private API gateway, the Harmony username and password must be associated with a member of a role with Admin permission. Agent Install permission is not sufficient. In the private API gateway configuration file, the Harmony username and password fields are stored as encrypted, while the proxy server username and password are stored as Base64-encoded. This is to prevent the proxy credentials from being exposed in clear text and is not intended to provide a high level of security. Please make sure the configuration file is stored in a secure manner.

The first time you configure a private API gateway using Harmony credentials, a new, separate API gateway user with a non-expiring password is automatically created in the organization as a member of the Administrator role. This user is not associated with an email address and cannot log in to the Harmony portal; this user is for API gateway purposes only. The credentials for this user are added to the gatewayconfig.yaml file.

Since API gateway version 11.32, if you reconfigure the gateway, you will see an additional question:

Would you like to generate a new Gateway credentials and overwrite existing ones? (y/N):

If you answer N (or press return for the default response), the existing user credentials are used. If you answer Y, a new user is created.

These API gateway users are displayed on the Management Console User Management page and are in the format of <GatewayUser>_<orgID>_<ID>. If the same user reconfigures the gateway in the same organization, the name of the gateway user is appended with an underscore and incremented number such as _1.

Output from the configuration utility is similar to the following. When prompted, enter the required information, such as your Harmony username and password, Harmony region, proxy information (if proxy configuration is to be enabled), services URL (if different than the default), organization ID (if different than the default for that account), and desired configuration for DNS:

Jitterbit Private Gateway Configuration

Enter your Harmony user name:
Enter your Harmony password:
Are you an NA, EMEA or APAC customer (Enter one, NA , EMEA, or APAC):

Would you like to enable a proxy (Y/N)?
Enter your proxy server uri (e.g. http://192.168.1.100:808):
Enter your proxy username:
Enter your proxy password:

Connecting to Harmony...
NOTE: Default Jitterbit Services URL for NA customers is https://services.jitterbit.net/apis
NOTE: Default Jitterbit Services URL for EMEA customers is https://services.jitterbit.eu/apis
NOTE: Default Jitterbit Services URL for APAC customers is https://services.jitterbit.cc/apis

Enter Jitterbit Services URL (press enter for default):
Enter your Jitterbit Organization ID (press enter for default):
Creating Private Gateway User...

Here is the content of the DNS file that will be used for the API gateway:
The file is located here: /usr/local/openresty/nginx/conf/dnsservers.conf
resolver 127.0.1.1 valid=300s ipv6=off;

Here are the nameservers from /etc/resolve.conf:
nameserver 127.0.1.1

Would you like to use the resolv.conf DNS nameservers rather than the default nginx DNS servers? (Y/N)?

Would you like to manually add the DNS server the API gateway DNS configuration (Y/N)?
Please enter IP address or domain name. Press enter to finish:

Gateway Configuration file modified.

If you have an SSL Certificate, copy the SSL Certificate file to
    /usr/local/openresty/nginx/ssl/nginx.crt
and the SSL Certificate key file to
    /usr/local/openresty/nginx/ssl/nginx.key

Would you like the Gateway Server started? (Y/N)?
. . .

If you answer Y to the last question, the private API gateway should start running.

If the installation was successful, you can now access the organization's APIs using the private API gateway. No further configuration is necessary; all APIs in the organization should now be accessible using the private API gateway.

Note

In addition to accessing the organization's APIs with your private API URLs, you are still able to use Jitterbit URLs. To block access of the Jitterbit URLs, an operation can first confirm that an URL is from the private API gateway and cancel if not. Here is an example of testing in the NA region (for EMEA and APAC regions, substitute jitterbit.eu or jitterbit.cc as appropriate):

<trans>
if( index($jitterbit.api.request.headers.fulluri,'jitterbit.net') >0,
    $jitterbit.api.response = 'Public API gateway not permitted';
    CancelOperationChain($jitterbit.api.response);
)
</trans>

For assistance, contact Jitterbit support.

A successful private API gateway startup looks similar to this:

. . .
nginx: [alert] [lua] startup.lua:0: ():
       ____  ___  __   __    ___
   | |  |   |  |__  |__) |__) |  |
\__/ |  |   |  |___ |  \ |__) |  |
           API gateway

Version: x.x.x.x
Build Date: 20XX/XX/XX 00:00

Loading Libraries...
Libraries loaded successfully!

Loading configuration...
Configuration file:  /usr/local/openresty/nginx/conf/onpremise/gatewayconfig.yaml
Configuration file successfully loaded, parsing values...

************************************************************

InfluxDB output not configured.
Loggly output not configured.
ELK output not configured.

Configuration parsing successful!

Doing startup checks...

Checks completed, no errors.

------------------------------------------------------------

Jitterbit Services URL: https://services.jitterbit.net/apis
Gateway will login as: gatewayuser
Organization ID set to: 123456

Current Time: 20XX-XX-XX 00:00:00
Gateway Startup Successful!

Gateway server started

Step 5: Test the private API gateway

Once the private API gateway is installed, it should be tested to ensure it is functioning as expected.

When testing the private API gateway, you must have a valid API Manager API in the organization associated with the private API gateway.

Test the API using an API Manager API service URL in this format:

https://JBExample123456.jitterbit.net/Development/1/customer

If the API is working properly, it can be used to test a private API URL.

Using your subdomain and domain, replace the Jitterbit domain and subdomain, retaining the same path.

Using the subdomain (mysubdomain) and domain (example) such as mysubdomain.example.com, the API service URL would be changed to this private API URL:

https://mysubdomain.example.com/Development/1/customer

To test that a proxy configuration is working, append ?debug to the URL:

https://mysubdomain.example.com/Development/1/customer?debug

The output is displayed:

Proxy enabled: {proxyUri}

Where {proxyUri} is the value provided during configuration.

Private API gateway self-test

The private API gateway includes a self-test, accessible using the --test option on the command line.

After a successful login, the self-test runs through a series of automatic tests that include importing a built-in project and API and then calling the API through the gateway to ensure proper configuration.

The API is created with the SSL only option enabled, meaning access to the private API gateway URL will be tested over HTTPS only. To allow access over HTTP, you can disable the SSL only option in the API configuration after the test API is created.

An API URL must be available in your subscription for the self-test to be successful.

Restart a private API gateway

You may need to stop, start, or restart the private API gateway to make additional configuration changes, upgrade, or troubleshoot. To do so, use the configuration utility and these options:

# Stop the private API gateway:
/usr/bin/jitterbit-api-gateway-config -s stop

# Start the private API gateway:
/usr/bin/jitterbit-api-gateway-config -s start

# Restart the private API gateway:
/usr/bin/jitterbit-api-gateway-config -s restart

# Private API gateway Configuration help:
/usr/bin/jitterbit-api-gateway-config -h

# Configure the private API gateway:
/usr/bin/jitterbit-api-gateway-config

# Testing the private API gateway by using its self-test:
/usr/bin/jitterbit-api-gateway-config --test

Upgrade a private API gateway

To find the version of the private API gateway currently running on your machine use this command:

/usr/bin/jitterbit-api-gateway-config --version

The output is displayed:

Version: x.x.x.x
Build Date: 20XX/XX/XX 00:00

Upgrading a private API gateway to a later version can be done without uninstalling the prior gateway version, even when upgrading from a 10.x to an 11.x version.

To upgrade a private API gateway to a later version follow these steps:

  1. Download the latest version of the private API gateway software through the Downloads page. If required, older versions of the software can be obtained from Jitterbit support.

  2. Create a backup of the existing private API gateway configuration file. The private API gateway configuration file is located in this directory:

    /usr/local/openresty/nginx/conf/onpremise/gatewayconfig.yaml

  3. When upgrading from a private API gateway version 10.61 or earlier, create a backup of the SSL certificate files. The private API gateway SSL certificate files are located in these directories:

    /usr/local/openresty/nginx/ssl/nginx.crt
/usr/local/openresty/nginx/ssl/nginx.key

    Note

    For private API gateway version 10.62 or later, it is not necessary to make a backup of or to copy the SSL certificate files. These files are retained during an upgrade.

  4. The commands used to upgrade a private API gateway are the same as those used during initial installation. Follow the instructions for Step 2: Install the private API gateway software.

  5. Copy the backup of the private API gateway configuration file and SSL certificate files (if applicable) to the new private API gateway installation.

  6. Optionally, run the command line configuration tool to make additional configuration changes. You may want to do this if you are using new configuration settings that are available in a later version of the private API gateway software.

    /usr/bin/jitterbit-api-gateway-config

    For all configuration options, see Step 4: Configure the private API gateway.

  7. Restart the private API gateway:

    /usr/bin/jitterbit-api-gateway-config -s restart

Note

After an upgrade, the private API gateway configuration file may encounter errors on newer versions of the private API gateway. In these cases, ensure step 5 of the upgrade is successful.

Uninstall a private API gateway

Use this command to uninstall a private API gateway on RPM-based Linux distributions:

RHEL or Amazon Linux AMI 2
yum remove jitterbit-api-gateway

Use this command to uninstall a private API gateway on Debian-based Linux distributions:

Debian or Ubuntu
apt-get remove jitterbit-api-gateway

To complete the uninstall, run these commands:

For Debian-based Linux distributions using private API gateway version 10.62 or later, run this command:

apt-get purge jitterbit-api-gateway

For RPM-based Linux distributions using private API gateway version 10.62 or later, run this command:

yum remove jitterbit-api-gateway

For both RPM- and Debian-based Linux distributions (all private API gateway versions), run these commands:

rm -rf /usr/local/jitterbit-api-gateway/
rm -rf /usr/local/openresty/
rm -rf /usr/local/hostedfiles/