Setting Up a Gateway Server

This guide explains how to install and configure a gateway server that can communicate with Itential Cloud for Automation as well as gateway clients to a Linux server.

Distribution

This guide assumes a Linux distribution that supports systemd services (i.e., RedHat-based or Debian-based distributions). The setup would look similar to the figure shown below.

Figure 1: Gateway Server Setup

Download Gateway Server Installer

Depending on your package manager, both .deb and .rpm installers are available for the initial configuration of a gateway server. Go to the Downloads page within the Itential Cloud portal to download your particular server installer.
 
Figure 2: Downloads IAG5

Initial Server Setup

Copy the gateway executable onto your server. This can be done with a similar scp command as shown below.

scp /path/to/installer <your-user>@<server-hostname-or-ip>:/tmp

Use SSH to connect to your server and navigate to the installer file.

Installer Packages

Debian Install

If you are using apt as your package manager and, therefore, using the debian installer, execute the following:

sudo apt install ./iagctl-1.0.0-<arch>.deb

RPM Install

If your Linux distribution uses rpm packages, execute the following:

sudo dnf localinstall ./iagctl-1.0.0-amd64.rpm

Configuration After Installation

For either installer (rpm or debian), to give your user the proper permissions to view the files that were just added, execute the following:

sudo usermod -aG itential-admins $USER

Log out of the system and then back in to ensure the group changes take effect.

You should now have a running iagctl systemd service. Run the following command to confirm:

sudo systemctl status iagctl

Tail the logs to confirm the gateway has booted properly. You can run the following:

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

Alternatively, utilize the systemd journal.

journalctl -fu iagctl.service

The output should look similar to what is shown below:

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

You should now have a running gateway server.

Connecting to Itential Cloud for Automation

Next, you will need to configure the connection to Itential Cloud for Automation.

Configure Public/Private Certificates

To authenticate your gateway server with Itential Cloud for Automation, you will need to provide a public/private certificate pair.

For this tutorial we will generate and use a private key and self-signed certificate. On your Linux server, run the following command - don't forget to replace YOUR_HOSTNAME with the FQDN of your server:

sudo openssl req -x509 -newkey rsa:4096 \
               -keyout /etc/gateway/certificates/commander-key.pem \
               -out /etc/gateway/certificates/commander.pem \
               -days 365 -nodes \
               -subj "/CN=YOUR_HOSTNAME" \
               -addext "basicConstraints=CA:FALSE" \
               -addext "keyUsage=digitalSignature,keyEncipherment" \
               -addext "extendedKeyUsage=serverAuth"

This will generate a private key file and certificate file in these locations:

/etc/gateway/certificates/commander-key.pem
/etc/gateway/certificates/commander.pem

You also need to ensure the GATEWAY_APPLICATION_CLUSTER_ID is set to whatever value you prefer to identify the gateway cluster. This ID is very important and will be used to identify the gateway within Itential Cloud for Automation.

Lastly, update GATEWAY_COMMANDER_ENABLED to be true and the GATEWAY_COMMANDER_HOST variable to point at your Itential Cloud for Automation instance.

Locate the value for GATEWAY_COMMANDER_HOST within the Gateway panel of the Itential Cloud for Automation UI as shown in Figure 2.

Figure 3: Gateway Commander Host

The locations of these configuration variables within /etc/gateway/gateway.conf are shown below.

[application]
cluster_id = 'cluster_1'

[commander]
certificate_file = '/etc/gateway/certificates/commander.pem'
private_key_file = '/etc/gateway/certificates/commander-key.pem'
enabled = true
host = <your-automation-gateway-services-host>

There is no need to restart the gateway to have this new configuration take effect. The public certificate needs to be added to Itential Cloud for Automation before you attempt to connect. Adding the public certificate is covered in the next section.

Add Certificates to Itential Cloud for Automation

Copy your public key at GATEWAY_COMMANDER_CERTIFICATE_FILE to your local machine using a run command similar to what is shown below.

scp <your-user>@<server-hostname-or-ip>:/etc/gateway/certificates/commander.pem .

Next, log into Itential Cloud for Automation and navigate to the Gateways workspace in the UI.

Click Upload Certificate. Select the certificate that you just copied from your IAG server.

Figure 4: Upload Gateway Certificate

When prompted, verify that everything looks correct with the certificate and then click Trust This Certificate. The certificate can be used with as many Gateways as needed.

Add Gateway to Itential Cloud for Automation

Next, while still on the Gateways page, click Add Gateway.

Complete the form fields as shown below. Ensure the Cluster ID field aligns with the GATEWAY_APPLICATION_CLUSTER_ID configuration variable that was set earlier.

Figure 5: Add Gateway Form

When prompted to add a certificate, select Yes.

From the dropdown, select the certificate that was just uploaded and then click Save.

Figure 6: Select Certificate

Next, add the gateway to the appropriate groups within the UI. Any users that are added from a particular group will be able to perform the actions based on whatever roles they are assigned on that gateway. If a user is not in a group that is associated with that gateway, they will not be able to perform any actions on it.

Your gateway is now added within the Itential Cloud for Automation UI.

Restart the Gateway to Connect

Now that the gateway is configured in Itential Cloud for Automation with a certificate for authentication, you can restart the service so that the new configuration variables you set earlier will take effect.

sudo systemctl restart iagctl.service

Check if the gateway was able to successfully connect via its log.

cat /var/log/gateway/gateway.log | grep "connected to commander"

You should see a log that resembles the following:

INF connected to commander at <your-commander-hostname>:443

You should now have a successful connection from the gateway to Itential Cloud for Automation.

Setting Up a Gateway Client

With your gateway server running, you will now need to be able to send requests to it from a gateway client. You can connect from a gateway client that lives on another machine; however, for simplicity, you can initially make requests locally from the same machine.

To locally run gateway in client mode, you can override the GATEWAY_APPLICATION_MODE configuration variable for the active shell session on the server machine by running:

export GATEWAY_APPLICATION_MODE=client

With this set, any iagctl commands that run on your current shell session will be run in client mode. This means the gateway executable will send requests to the server via API calls for many of the commands.

Notice that GATEWAY_CLIENT_HOST is set to localhost within your configuration file. This means that all API calls will be made to the server that is currently running on the same machine.

Perform the initial login into the client by calling the iagctl executable. The server and client can both call the same executable without issues.

/opt/gateway/iagctl login admin

You will be prompted for an initial password. On first login, that password is always be set to admin. Type admin and press Enter.

You will then be prompted for a new password. Enter a secure password longer than 8 characters that will be used for your admin accounts and follow the rest of the prompts. You should now be logged in.

By default, this session will last one day. You can modify the session length by editing the GATEWAY_SERVER_API_KEY_EXPIRATION configuration variable.

If you ever forget the admin password that was just set, then ssh to the server and run the following while in server mode:

/opt/gateway/iagctl server --recover-admin-user

You can now test any command from your client. For example, when you run:

/opt/gateway/iagctl get services

You should receive an empty response that resembles the following given that you do not have any services yet.

NAME    DESCRIPTION   TYPE    TAGS

You can now add services, repositories, decorators, and whatever other resources you would like on the gateway from this client.

Refer to the help menu via CLI command for more information on creating resources.

/opt/gateway/iagctl create repository --help
/opt/gateway/iagctl create service python-script --help
/opt/gateway/iagctl create service ansible-playbook --help
/opt/gateway/iagctl create service opentofu-plan --help

As you create services on the server, you should see them begin to populate as Automations within the Itential Cloud for Automation UI.

(Optional) Export the Executable Directory to the System Path

The command shown below can be executed to add iagctl to your system path. This allows you to simply run iagctl instead of the full path of /opt/gateway/iagctl on your server instance. This command can also be added to the bottom of a user's .bashrc to ensure that PATH is updated at the start of every shell session.

export PATH=/opt/gateway:$PATH

Setting Up a Gateway Client on a Separate Machine

If preferred, you have the option to run commands against the gateway server from your own machine or some other machine that is not the server itself. To do this, you will need to install the gateway executable and then correctly configure it as a client that points to the gateway server.

Download the IAG 5 Binary executable for your particular OS/architecture from the Downloads page within Itential Cloud where you downloaded the server installer.

Verify the file is on the appropriate machine.

Mac Client Install

If running the gateway client on a Mac:

1. Extract the tar file contents from the terminal using tar -zxvf iagctl-x.y.z_darwin_arch.tar.gz.

   a. Replace x.y.z and arch per the version you downloaded.

2. Run the newly extracted executable using ./iagctl.

3. A popup warning of a security error will display. Click Cancel within the popup.

4. Navigate to System Settings &rarr: Privacy and Security.

5. Scroll to Security and click Allow Anyway where it says "iagctl" was blocked from use....

6. Provide your password or fingerprint.

7. Copy the file to your bin directory so that it is in your path, e.g. mv ./iagctl /usr/local/bin/iagctl.

8. Open your terminal and run iagctl.

9. Click Open in the popup that appears.

10. You can now run gateway anywhere by running iagctl.

Linux Client Install

If running the gateway client on a Linux machine:

1. Extract the tar file contents from the terminal using tar -zxvf iagctl-x.y.z_linux_arch.tar.gz.

   a. Replace x.y.z and arch per the version you downloaded.

2. Run the newly extracted executable using ./iagctl.

3. Copy the file to your bin directory so that it is in your path, e.g. mv ./iagctl /usr/local/bin/iagctl.

4. You can now run gateway anywhere by running iagctl.

Configuring the Gateway Client

Once the gateway client executable is installed, you need to properly configure it to connect to the gateway
server.

Configuration files can be in multiple places as outlined on the Configuration page, but for this example it is placed here:

vi ~/.gateway.d/gateway.conf

Paste in the following contents.

[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

The most relevant configurations are present in the example. Descriptions of each configuration variable as well as additional variables are available here. Any variable that is commented out is left as the default.

Update the GATEWAY_CLIENT_HOST variable to point at your particular gateway server.

Ensure the GATEWAY_APPLICATION_MODE is set to client.

Additionally, there are multiple TLS configurations. This example config file sets up gateway to use "Client to Server Authentication", often referred to as mTLS. This is because the server has GATEWAY_SERVER_CLIENT_CERT_AUTH set to true. With that, the following certificates need to be be set on the gateway client:

• GATEWAY_APPLICATION_CA_CERTIFICATE_FILE
• GATEWAY_CLIENT_CERTIFICATE_FILE
• GATEWAY_CLIENT_PRIVATE_KEY_FILE

For convenience, the gateway server installer generated an example CA certificate, as well as an example public/private pair for the client that was signed by the same CA. You can copy them to your machine with the following commands:

mkdir ~/.gateway.d/certificates
scp <your-user>@<server-hostname-or-ip>:/etc/gateway/certificates/ca.pem ~/.gateway.d/certificates
scp <your-user>@<server-hostname-or-ip>:/etc/gateway/certificates/client.pem ~/.gateway.d/certificates
scp <your-user>@<server-hostname-or-ip>:/etc/gateway/certificates/client-key.pem ~/.gateway.d/certificates

Verify the configuration is loaded by running:

iagctl version --show-config

If there are any issues loading the config, run iagctl --verbose and look for a log that resembles INF using configuration file at /path/to/gateway.conf.

Once the gateway client is correctly configured, you will need to login.

Run the following command from the client and then enter the password you set earlier.

iagctl login admin

If you have any issues connecting, try adding the --verbose flag to get more troubleshooting information. Lowering the GATEWAY_LOG_LEVEL to DEBUG inside the configuration file can also be helpful.

If you receive an error similar to what is shown below, you will need to regenerate a server certificate with the proper SANS for the IP/Hostname you are trying to connect to.

Error: rpc error: code = Unavailable desc = connection error: desc = "transport: authentication handshake failed:
tls: failed to verify certificate: x509: certificate is valid for 127.0.0.1, not 4.81.240.89"

Itential has provided a utility that can regenerate the certificate for you on the server, if needed. Many organizations, however, may opt to use their own certificate generation tools for all certificates. Run the commands below on your server to load in a new certificate using an optional certificate utility.

export GATEWAY_APPLICATION_MODE=server
/opt/gateway/iagctl --config /etc/gateway/gateway.conf cert-gen server \
    --output /etc/gateway/certificates \
    --country "US" \
    --locality "Atlanta" \
    --org "Itential" \
    --ou "Automation" \
    --state "Georgia" \
    --cn <server-hostname-or-ip> \
    --sans "localhost,127.0.0.1,<server-hostname-or-ip>" \
    --expiry 730 \
    --key-algo rsa \
    --key-size 2048
systemctl restart iagctl.service

Once you have logged in, you can run any commands against your gateway server. Try running the example command shown below.

iagctl get services

TLS Configuration

The certificates provided by the installer allow a user to get started with a secure connection. It is important to understand that any of the provided certificates, especially the private keys (i.e., any file auto-generated with -key in the name per Itential convention) should be stored securely. Take great care to ensure they are not exposed.

Server administrators may opt to generate their own certificates and handle the TLS on their own, which is certainly permissible.

If a TLS connection is desired, but a simpler approach that does not require a CA file is needed, the configuration variable GATEWAY_SERVER_CLIENT_CERT_AUTH can be set to false on the server, which removes the requirement for mTLS.

By setting the variable to false, only matching public/private key sets need to be shared between the client and server. No CA certificate would be required and the keys do not need to be signed by a CA.