- 15 Nov 2024
-
DarkLight
-
PDF
Setting Up a Gateway Server
- Updated on 15 Nov 2024
-
DarkLight
-
PDF
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.
The installer generated and placed example certificates that will function at:
/etc/gateway/certificates/commander.pem
Private key certificates are located at:
/etc/gateway/certificates/commander-key.pem
Commander
is the name of the Itential service that handles connections to gateways.
You have the option to generate your own keys, if desired. If you do so, be sure to update the GATEWAY_COMMANDER_CERTIFICATE_FILE
and GATEWAY_COMMANDER_PRIVATE_KEY_FILE
configuration variables.
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>
➡ More information on gateway configuration variables can be found here.
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.
➡ More information on application modes can be found here.
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
➡ More information on login can be found here.
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:
-
Extract the
tar
file contents from the terminal usingtar -zxvf iagctl-x.y.z_darwin_arch.tar.gz
.a. Replace
x.y.z
andarch
per the version you downloaded. -
Run the newly extracted executable using
./iagctl
. -
A popup warning of a security error will display. Click
Cancel
within the popup. -
Navigate to
System Settings
&rarr:Privacy and Security
. -
Scroll to
Security
and clickAllow Anyway
where it says"iagctl" was blocked from use...
. -
Provide your password or fingerprint.
-
Copy the file to your bin directory so that it is in your path, e.g.
mv ./iagctl /usr/local/bin/iagctl
. -
Open your terminal and run
iagctl
. -
Click
Open
in the popup that appears. -
You can now run gateway anywhere by running
iagctl
.
Linux Client Install
If running the gateway client on a Linux machine:
-
Extract the
tar
file contents from the terminal usingtar -zxvf iagctl-x.y.z_linux_arch.tar.gz
.a. Replace
x.y.z
andarch
per the version you downloaded. -
Run the newly extracted executable using
./iagctl
. -
Copy the file to your bin directory so that it is in your path, e.g.
mv ./iagctl /usr/local/bin/iagctl
. -
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.