IAG RPM/DEB installation

  • Updated on Jun 6, 2025
  • Published on Jun 6, 2025
Prev Next

The following walkthrough demonstrates how to:

  • Install and configure an Itential Automation Gateway (IAG) server
  • Create and configure a gateway cluster in Gateway Manager
  • Connect to your gateway server from a gateway client

The following procedures demonstrate how to install Itential Automation Gateway (IAG) binary as a client-server and connect it to Gateway Manager.

Prerequisites

Before starting, ensure you have:

  • Access to Itential's software repository
  • OpenSSL installed
  • A Linux environment in which you can install either RPM or DEB installer packages

Step 1: Install your gateway server

  1. Download the .deb or .rpm Itential Automation Gateway IAG installer package.

Itential recommends downloading the latest version of IAG.

If you did not download the package directly onto your Linux server, copy it there now. The following example uses the scp command to copy the package to the server.

scp /path/to/installer <your-user>@<server-hostname-or-ip>:/tmp
  1. Install the gateway server using the package manager for your Linux distribution.
Note

The following examples install version 5.1.0 of Itential Automation Gateway (IAG).

Update the version and arch to reflect the version you downloaded before running the example installation commands.

Debian installation
If you downloaded the Debian (.deb) installer package, run the following command:

sudo apt install ./iagctl-<5.1.0>-<arch>-server.deb

RPM installation
If you downloaded the RPM (.rpm) installer package, run the following command:

sudo dnf localinstall ./iagctl-<5.1.0>-amd64-server.rpm

Step 2: Verify installation and assign user permissions

  1. Give your user the proper permissions to view the installed files by running the following command:
sudo usermod -aG itential $USER
  1. Log out of the system and then back in to ensure the group changes take effect.
  2. Verify that your gateway server is running by running the following command:
sudo systemctl status iagctl



Optional
Tail the logs to confirm that the gateway has booted properly by running one of the following commands:

tail -n 15 /var/log/gateway/gateway.log

Or

journalctl -fu iagctl.service

Verify that output is similar to the following:

2024-09-27T15:18:39Z INF using configuration file at /etc/gateway/gateway.conf
2024-09-27T15:18:39Z INF using local store database file at gateway.db
2024-09-27T15:18:39Z INF starting gateway server
2024-09-27T15:18:39Z INF working directory is /etc/gateway
2024-09-27T15:18:39Z INF

===================
 CREATED TEMPORARY ADMIN
 username: admin
 password: admin
===================


2024-09-27T15:18:39Z INF starting grpc server on [::]:50051/tcp

Step 3: Gather certificates

To help you get started, the installer provides sample certificates that enable you to test functionality and become familiar with the system. This walkthrough uses these sample certificates to establish secure communication between your gateway cluster and Gateway Manager.

You can also provide your own certificates. For example, you might choose to obtain certificates from a trusted certificate authority for production environments.

To provide your own Gateway Manager certificates, specify the certificate file and private key file with the following configuration variables:

  • GATEWAY_CONNECT_CERTIFICATE_FILE
    • Default location: /etc/gateway/certificates/gw-manager.pem
  • GATEWAY_CONNECT_PRIVATE_KEY_FILE
    • Default location: /etc/gateway/certificates/gw-manager-key.pem

Locate the sample certificates at /etc/gateway/certificates. You will upload the certificate file (/etc/gateway/certificates/gw-manager.pem) to Gateway Manager in Step 5.

When configuring your gateway cluster, you can also provide client-server TLS certificates to establish secure communication between your gateway server and gateway client. The installer provides sample certificates for this use case as well. For more information on generating certificates for secure communication within your gateway cluster, see Gateway cluster TLS.

Step 4: Update server configuration

  1. Open the server configuration file found at /etc/gateway/gateway.conf with the editor of your choice.
  2. Update the configuration under [connect] to reference the certificate files you created in the previous step and update the hosts value to reflect your Gateway Manager instance.
[connect]
certificate_file = '/etc/gateway/certificates/gw-manager.pem'
private_key_file = '/etc/gateway/certificates/gw-manager-key.pem'
enabled = true
hosts = <your-automation-gateway-services-host:port>
  1. Make note of the cluster_id defined under [application]. You will need this value when you create your gateway cluster in Step 6.
[application]
cluster_id = 'cluster_1'
Note

You can update the cluster ID to a string value of your choice, but it must be unique amongst all gateway servers that you connect to Gateway Manager.

The cluster ID defined in your server configuration file must match the cluster ID of the gateway cluster that represents it in Gateway Manager.

Step 5: Upload certificate to Gateway Manager

The Itential Platform must be able to recognize and trust your certificate before your gateway can establish a secure connection. Upload your certificate to Gateway Manager to establish this trust relationship between your gateway cluster, Gateway Manager, and the Platform.

  1. Open Itential Platform in your browser
  2. Select Gateway Manager from the Administration collection in the left-side navigation menu
  3. Upload the certificate:
    1. Navigate to the Certificates tab and click Upload Certificate
    2. Upload the /etc/gateway/certificates/gw-manager.pem file from Step 3
    3. Click Add Certificate

Step 6: Create a gateway cluster

After uploading your certificate, create a gateway cluster. This tells the Itential Platform that your gateway is trusted and can be used to run automation tasks.

  1. Navigate to the Gateways tab in Gateway Manager
  2. Click Add Gateway Cluster
  3. Set the gateway cluster ID to match the GATEWAY_APPLICATION_CLUSTER_ID defined in your configuration file in Step 1. If you did not modify the cluster ID from the sample configuration file provided in Step 1, enter cluster_1.
  4. (Optional) Enter a description
  5. Under Access, add at least one authorization group to your gateway cluster.
  6. Click Add

Step 7: Enable your gateway

Gateways are disabled at creation and must be manually enabled. To enable your gateway cluster, you need to connect the certificate that you uploaded in Step 5 to your new gateway cluster. This step completes the trust chain between your gateway and the Itential Platform, allowing them to communicate securely.

  1. Navigate to the Gateways tab in Gateway Manager.
  2. Select your newly created gateway cluster to view the gateway details.
  3. Under Linked Certificates, click the Link toggle to associate the certificate you uploaded in Step 5 with your gateway cluster.
  4. Select Enabled from the status dropdown menu to enable your gateway.
Note

Your gateway will remain Disconnected until you restart your gateway server.

Step 8: Restart your gateway server

Now that you've configured and registered your gateway, you need to restart the server to ensure the updated configuration variables take effect.

  1. Restart your gateway server by running the following command:
sudo systemctl restart iagctl.service
  1. Verify that the gateway server successfully connected to Gateway Manager by running the following command:
cat /var/log/gateway/gateway.log | grep "received initial message from gateway manager"

Verify that you see a successful connection log similar to the following:

INF received initial message from gateway manager

Step 9: Setup your gateway client

You can connect to your gateway server from a local client on the same machine as your server, or, you can install the gateway client on a separate machine.

Local client

The gateway client and server can use the same binary, enabling you to download, install, and maintain a single program file that can perform both roles.

The gateway application mode configuration setting lets you configure whether iagctl acts as a server, client, or other modes when executed. The server that manages connections to Gateway Manager has a 'GATEWAY_APPLICATION_MODE' of 'server'. To send requests to your server, set the application mode to 'client'.

  1. To run your gateway in client mode locally, run the following command:
export GATEWAY_APPLICATION_MODE=client
  1. Add iagctl to your system path.
export PATH=/opt/gateway:$PATH
  1. Log in as an admin:
    1. Run iagctl login admin
    2. Enter admin when prompted for the initial password.
    3. Create a new password when prompted. Your password must be longer than 8 characters.
    4. Follow the remaining prompts to finish logging in.

Install and configure a separate client

Install gateway client

Install a gateway client on a separate machine to manage the resources on your gateway server.

Download the IAG binary executable for your particular operating system from the Itential software repository.

Mac installation

  1. Navigate to your Downloads folder and extract the archive. Before running the following command, update x.y.z and arch to reflect the version you downloaded.
tar -zxvf iagctl-x.y.z_darwin_arch.tar.gz
  1. Run the extracted executable:
./iagctl
  1. When a security warning appears, click Cancel.
  2. Navigate to your System Settings and select Privacy and Security.
  3. Under Security, select Allow Anyways where it says "iagctl was blocked from use".
  4. Provide your password or fingerprint to confirm.
  5. Copy the file to your bin directory:
mv ./iagctl /usr/local/bin/iagctl



Linux installation

  1. Navigate to your Downloads folder and extract the archive. Before running the following command, update x.y.z and arch to reflect the version you downloaded.
tar -zxvf iagctl-x.y.z_linux_arch.tar.gz
  1. Run the extracted executable:
./iagctl
  1. Copy the file to your bin directory:
mv ./iagctl /usr/local/bin/iagctl

You can now run IAG from anywhere using the iagctl command.

Create client configuration file

Configure your gateway client to connect to your gateway server.

  1. Create a gateway.conf file at ~/.gateway.d/gateway.conf with the following properties:
Important

Replace the host value to point to your gateway server.

To disable TLS (if you're not using the optional client-server TLS certificates from Step 3):

  1. Set use_tls to false under the [client] section
  2. Disable TLS on your server by setting use_tls to false under the [server] section in /etc/gateway/gateway.conf
  3. Restart your server

To enable TLS (if you want to use the client-server TLS certificates from Step 3):

  • Copy the client certificates and CA certificates to your machine
  • Ensure use_tls is set to true in both client and server configurations
[application]
ca_certificate_file  = ~/.gateway.d/certificates/ca.pem
mode                 = client
#working_dir         = ~/.gateway.d

[client]
certificate_file  = ~/.gateway.d/certificates/client.pem
host              = <gateway-server-hostname>
#port             = 50051
private_key_file  = ~/.gateway.d/certificates/client-key.pem
use_tls           = true

[log]
#level = INFO
  1. Run the following command to verify your configuration:
iagctl version --show-config

If you are unable to verify your configuration, run iagctl --verbose and look for a log similar to the following:

INF using configuration file at /path/to/gateway.conf