Skip to Content

Turn your connections into holiday cash with our new Customer Referral Program! Learn more

✕

Install a Jitterbit private API gateway on Linux

Overview

This page explains how to install, configure, and test a private API gateway.

Important

EMEA customers with restricted network environments should use API gateway version 11.40 or later due to an environment domain change.

System requirements

This section gives the minimum requirements for an API gateway host.

Hardware

CPU Intel x86_64 (amd64) quad-core, 8 GB memory.
Disk 50 GB, NTFS (Windows), ext2, ext4, xfs (Linux), 50 MB/s transfer speed.
Network High-speed internet connection.

Important

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.

Operating systems

OS Version ≤11.36 11.37 11.38 11.39 ≥11.40
Linux Red Hat Enterprise Linux 8
Red Hat Enterprise Linux 9
Amazon Linux AMI 2
Amazon Linux 2023
Ubuntu 20.04 LTS
Ubuntu 24.04 LTS
Docker

Note

Distributions not listed here may work but are not supported.

Network

  • 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.

    The certificate should consist of two files: a CRT file (.crt) for the signed certificate, and KEY (.key) for the private key. These 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.

    Tip

    Free SSL certificates are available from providers such as Let's Encrypt.

  • SSH connectivity.

Accounts

Your Harmony must have a role with Admin permission. (Agent Install permission alone is not sufficient.)

Recommendations

When setting up your API gateway host, you should follow the recommended points:

  • Do not share the host with other non-system applications.

  • Configure the host for optimal performance.

  • Install the following additional packages for your host type:

    • Red Hat Enterprise Linux (RHEL): If cloud-based, use a Compute node, with the following package groups:

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

    • Debian, Ubuntu: Use a default installation, and select the following additional packages:

      • OpenSSH.

  • Network: Open port 443 (HTTPS). You can use the following commands to do this:

    firewall-cmd --zone=public --add-port=443/tcp --permanent
firewall-cmd --reload

    ufw allow 443/tcp

Install and configure a private API gateway

To install and configure a private API gateway, follow these steps using an account with root privileges:

  1. Download one of the following private API gateway software packages from the Harmony Portal Downloads page, then copy it to your API gateway host:

    • Linux RPM: The .rpm package file, for installing on Red Hat or Amazon Linux.

    • Linux Debian: The .deb package file, for installing on Debian or Ubuntu Linux.

  2. Run these commands for your combination of operating system and gateway version, replacing x.x.x.x (.deb) or x.x.x-x (.rpm) with the downloaded version number:

    yum update
yum install jitterbit-api-gateway-x.x.x-x.x86_64.rpm

    yum update
yum install https://dl.fedoraproject.org/pub/epel/epel-release-latest-8.noarch.rpm
yum install jitterbit-api-gateway-x.x.x-x.x86_64.rpm

    apt-get update
apt-get install libzzip-dev libyaml-dev
apt --fix-broken install
apt install python
dpkg --install jitterbit-api-gateway-x.x.x.x.amd64.deb

    apt-get update
apt-get -y install libgeoip-dev
apt --fix-broken install
ln -s /usr/bin/python2.7 /usr/bin/python
dpkg --install jitterbit-api-gateway-x.x.x.x.amd64.deb

    apt-get update
apt-get install libzzip-dev libyaml-dev libpcre3
apt --fix-broken install
dpkg --install jitterbit-api-gateway-x.x.x.x.amd64.deb

  3. Copy and rename your certificate files using the following commands:

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

  4. Add the certificate files to the Jitterbit Java KeyStore.

  5. Run the following command, then respond to the questions:

    jitterbit-api-gateway-config

    Tip

    For help on the jitterbit-api-gateway-config command, run it with the --help option.

    Important notes

    • The information you provide is stored in the /usr/local/openresty/nginx/conf/onpremise/gatewayconfig.yaml file. In this file, your Harmony username and password are encrypted, but the proxy server username and password are base64 encoded only. You should ensure this file has the appropriate permissions to prevent other users reading these values.

    • 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 with an Administrator role. This user is not associated with an email address, cannot log in to the Harmony portal, and is for the API gateway 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 are asked the following additional question:

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

      If you answer N, the existing user credentials are used. If you answer Y, a new user is created.

    • API gateway users are shown on the Management Console User Management page in the form <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.

    Example output 
    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)?
. . .

  6. You can now access your organization's APIs via 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. The following is an example of a test 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>

    A successful private API gateway startup looks similar to the following:

    Example startup 
    . . .
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

Test the private API gateway

To test the gateway, follow these steps:

  1. Set up a valid API Manager API in the organization associated with the private API gateway, and an API Manager API service URL in the format https://JBExample123456.jitterbit.net/Development/1/customer.

  2. Test the API. If it is working correctly, use it to test a private API URL by replacing the Jitterbit domain and subdomains with your own, retaining the same path. (If it is a proxy configuration, append ?debug to the URL.)

    Example

    If your subdomain is mysubdomain and domain is example, the base URL becomes mysubdomain.example.com, and you would change the API service URL https://JBExample123456.jitterbit.net/Development/1/customer to the private API URL https://mysubdomain.example.com/Development/1/customer. To test a proxy private API URL https://mysubdomain.example.com/Development/1/customer, use https://mysubdomain.example.com/Development/1/customer?debug. If successful, the output is Proxy enabled: PROXY_URI, where PROXY_URI is the value provided during configuration.

Private API gateway self-test

To run a gateway self-test, use the --test option for the jitterbit-api-gateway-config command. After a successful login, it automatically runs a series of tests to ensure proper configuration. These include importing a built-in project and API, and calling the API through the gateway. (An API URL must be available in your subscription for the self-test to be successful.)

Note

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

Upgrade a private API gateway

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

    Tip

    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.

  2. Create a backup of the private API gateway configuration file /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. Follow the install steps. (The commands to upgrade a private API gateway are the same as for installation.)

  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. (Optional) Run jitterbit-api-gateway-config to make additional configuration changes. You can do this if you are using new configuration settings that are available in a later version of the private API gateway.

  7. Run this command to restart the private API gateway:

    jitterbit-api-gateway-config -s restart

Uninstall a private API gateway

To uninstall a private API gateway, run these commands:

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

apt-get remove jitterbit-api-gateway
apt-get purge jitterbit-api-gateway
rm -rf /usr/local/jitterbit-api-gateway/
rm -rf /usr/local/openresty/
rm -rf /usr/local/hostedfiles/

jitterbit-api-gateway-config command

The jitterbit-api-gateway-config command lets you manage a Jitterbit private API gateway.

Synopsis

jitterbit-api-gateway-config [OPTIONS]

Options

  • -h, --help: Show a help message and exit.

  • -u USER, --user=USER: Jitterbit Harmony user name.

  • -p PASSWORD, --password=PASSWORD: Jitterbit Harmony password.

  • -o ORGANIZATION_ID, --organizationId=ORGANIZATION_ID: Jitterbit Harmony organization ID.

  • -e ServiceUrl, --serviceUrl=ServiceUrl: Jitterbit Services URL.

  • -s COMMAND, --server=COMMAND: Valid values for COMMAND:

    • start: Start the gateway.

    • stop: Stop the gateway.

    • restart: Restart the gateway.

  • -d, --dns: Interactively configure DNS servers.

  • --proxyEnabled=true | false: Enable (true) or disable (false) a proxy.

  • --proxyUri=PROXY_URI: Proxy server URI.

  • --proxyUser=PROXY_USER: Proxy server username.

  • --proxyPassword=PROXY_PASSWORD: Proxy server password.

  • -t, --test: Run self tests.

  • --debug: Enable debug output for self-tests.

  • --noColor: Disable terminal text colors.