Itential Docs & Guides | Drive Automation for Modern Networks

Once Itential Automation Gateway is installed and configured, use the information in this guide to change the default password, get started with the API and set your security keys.

Default User Name: admin@itential.
Default Password: admin.

You must first login to obtain the authorization token and then paste the token into the change password curl command.

An example curl script is provided below.

$ curl -X POST --header 'Content-Type: application/json' --header 'Accept: application/json' -d '{ "password": "admin", "username": "admin@itential" }' 'http://localhost:8083/api/v1.0/login'
{"token": "NTAuMjczOTA4MTYwNDM5OTY2"}

curl -X POST --header 'Authorization: <COPY TOKEN VALUE FROM PREVIOUS CMD HERE>' --header 'Content-Type: application/json' --header 'Accept: application/json' -d '{
   "new_password": "super-secure-password",
   "old_password": "admin"
 }' 'http://localhost:8083/api/v1.0/account/admin%40itential/change_password'

Log In to Automation Gateway

Log in to the Automation Gateway UI running at https://servername:8443.
The username will be admin@itential.
The password will be the <super-secure-password> that was selected in the previous step.

Getting Started with the API

For a complete API reference, use the API Documentation link in the Automation Gateway UI. This page allows you to browse and interact with the Automation Gateway API.

Add a Device

If an existing Ansible Inventory is not already configured, you can add a new device to Automation Gateway using the API. The following is an example curl script to add a device.

curl -X POST --header 'Content-Type: application/json' --header 'Accept: application/json' -d '{ "password": "admin", "username": "admin@itential" }' 'http://localhost:8083/api/v1.0/login'
{"token": "NTAuMjczOTA4MTYwNDM5OTY2"}

curl -X POST --header 'Authorization: <COPY TOKEN VALUE FROM PREVIOUS CMD HERE>' --header 'Content-Type: application/json' --header 'Accept: application/json' -d '{
   "name": "ios02",
   "variables": {
     "ansible_host": "192.168.32.79",
     "ansible_port": 22,
     "ansible_user": "ios-user",
     "ansible_ssh_private_key_file": "/path/to/key",
     "ansible_network_os": "ios",
     "ansible_connection": "network_cli"
   }
 }' 'https://localhost:8083/api/v1.0/devices'

Get a Device List

Use the following command to get a list of managed devices.

curl -X POST --header 'Content-Type: application/json' --header 'Accept: application/json' -d '{ "password": "admin", "username": "admin@itential" }' 'http://localhost:8083/api/v1.0/login'
{"token": "NTAuMjczOTA4MTYwNDM5OTY2"}

curl -X GET --header 'Authorization: <COPY TOKEN VALUE FROM PREVIOUS CMD HERE>' --header 'Accept: application/json' 'http://localhost:8083/api/v1.0/devices'

Get Configuration for a Device

Use the following command to retrieve the configuration for a managed device.

curl -X POST --header 'Content-Type: application/json' --header 'Accept: application/json' -d '{ "password": "admin", "username": "admin@itential" }' 'http://localhost:8083/api/v1.0/login'
{"token": "NTAuMjczOTA4MTYwNDM5OTY2"}

curl -X POST --header 'Authorization: <COPY TOKEN VALUE FROM PREVIOUS CMD HERE>' --header 'Content-Type: application/json' --header 'Accept: application/json' -d '{
   "hosts": [ "ios01" ],
   "template": "ios_config"
 }' 'https://localhost:8083/api/v1.0/getConfig'

Run a Command on a Device

Use the following command to run a command on a managed device.

curl -X POST --header 'Content-Type: application/json' --header 'Accept: application/json' -d '{ "password": "admin", "username": "admin@itential" }' 'http://localhost:8083/api/v1.0/login'
{"token": "NTAuMjczOTA4MTYwNDM5OTY2"}

curl -X POST --header 'Authorization: <COPY TOKEN VALUE FROM PREVIOUS CMD HERE>' --header 'Content-Type: application/json' --header 'Accept: application/json' -d '{
   "command": [ "show version" ],
   "hosts": [ "ios01" ],
   "template": "ios_command"
 }' 'https://localhost:8083/api/v1.0/runCommand'

Create Keys and Certificates

Use the information in this section to create a private key and certificate requests.

Private Key and Certificate Request

The certificate request must be submitted to a trusted certificate authority (CA) for signing. Your certificate authority should return the following set of files.

Signed certificate
Intermediate CA certificate
Root CA certificate

After the signed certificate is received, the final configuration of a secure Itential instance should occur.

Note: The commands provided in this section should be considered a simple reference implementation. Additional TLS extensions may be added as desired (such as the subject alternate name). Your company's internal procedures or certificate authority's procedures should be consulted for more detailed instructions on creating a certificate request.

Itential can be configured to connect to each of its external systems using TLS certificate-based encryption. Use the following openssl command to create a new private key and certificate request.

sudo mkdir /etc/ssl/keys
sudo openssl req -newkey rsa:2048 -keyout /etc/ssl/keys/itential.key -out /etc/ssl/keys/itential.csr

Complete the following fields to create the security certificates for your Itential configuration.

Field Name	Description
Country	The two-letter country code where your certificate authority resides.
State or Province	The name of the state or province where your certificate authority resides.
Locality	The name of the city where your certificate authority resides.
Organization	The name of your company.
Organizational Unit	The name of your department or program.
Common Name	For server certificates, the common name should match the FQDN of the server.
Email Address	Your email address.
Challenge Password	Supply a challenge password for the certificate request.
Company Name (optional)	Supply a company name for the certificate request.

Verify the output.

Generating a 2048 bit RSA private key
................+++
............+++
writing new private key to 'mongo.key'
Enter PEM pass phrase:
Verifying - Enter PEM pass phrase:
-----
You are about to be asked to enter information that will be incorporated
into your certificate request.
What you are about to enter is what is called a Distinguished Name or a DN.
There are quite a few fields but you can leave some blank
For some fields there will be a default value,
If you enter '.', the field will be left blank.
-----
Country Name (2 letter code) [XX]:US
State or Province Name (full name) []:GA
Locality Name (eg, city) [Default City]:Atlanta
Organization Name (eg, company) [Default Company Ltd]:Itential, LLC.
Organizational Unit Name (eg, section) []:UAT
Common Name (eg, your name or your server's hostname) []:db01
Email Address []:

Please enter the following 'extra' attributes
to be sent with your certificate request
A challenge password []:
An optional company name []:

Perform the following steps.

Set the PEM pass phrase to a secure value.
Set the common name of the certificate to the IP address or FQDN assigned to the server.
The specific settings for the private key in the previous commands may be dictated by your organization's internal security policy.
The common name of a server certificate should the same as the FQDN its clients are configured to connect to. For example, when signing certificates for the MongoDB server, if the common name of the certificate request is my-itential-server.pronghorn.io, the IAP properties.json configuration must use my-itential-server.pronghorn.io in the URL.
If the certificate request is signed with an FQDN but the application is configured with an IP address, the connection will likely fail. The subject alternate name TLS extension may be used to provide a list of authorized names that may be used to connect to the server. A common usage pattern for the subject alternate name is to configure the common name with the FQDN and configure the IP address of the server as the subject alternate name.

Self-Signed Certificates

Optionally, you can create a self-signed certificate to use while you are waiting your certificate to be signed by a trusted authority.

Create self-signed certificate.
```
sudo openssl req -key /etc/ssl/keys/itential.key -out /etc/ssl/keys/itential.cert -in /etc/ssl/keys/itential.csr -x509 -days 365
```
Note: If you are using self-signed certificates, Itential should have the self-signed certificates available to validate the connection. An alternative is to configure the adapter with the sslValidate property set to false.

Combine the key and self-signed certificate into a single .keycert file.

sudo sh -c "cat /etc/ssl/keys/itential.key /etc/ssl/keys/itential.cert > /etc/ssl/keys/itential.keycert"

Copy the self-signed certificate to the itential_ca_chain.cert file.

sudo cp /etc/ssl/keys/itential.cert /etc/ssl/keys/itential_ca_chain.cert

Confirm the files in /etc/ssl/keys match the sample output.

$ ls -1 /etc/ssl/keys
itential_ca_chain.cert
itential.cert
itential.csr
itential.key
itential.keycert

Confirm the itential_ca_chain.cert file is in the following format.

$ sudo cat /etc/ssl/keys/itential_ca_chain.cert
-----BEGIN CERTIFICATE-----
...
-----END CERTIFICATE-----

Add the self-signed certificate to the system trust store.

sudo cp /etc/ssl/keys/itential_ca_chain.cert /etc/pki/ca-trust/source/anchors/
sudo update-ca-trust

CA-Signed Certificates

Once you have received the signed certificate back from your trusted certificate authority, you should receive three certificate files.

File	Description
`itential.cert`	Server certificate.
`intermediate_ca.cert`	Intermediate CA certificate.
`root_ca.cert`	Root CA certificate.

Use the following steps to install the certificates.

Copy the server, intermediate CA and root CA certificates to the /etc/ssl/keys directory, and verify that the server certificate and private key modules are consistent before installing the certificate.
```
sudo openssl rsa -noout -modulus -in /etc/ssl/keys/itential.key | openssl md5
sudo openssl x509 -noout -modulus -in /etc/ssl/keys/itential.cert | openssl md5
```

Verify the key and certificate match in the output.

(stdin)= e5b26b7e708aa699927532d6c836db02
(stdin)= e5b26b7e708aa699927532d6c836db02

Verify the issuer of the server certificate matches the subject of the intermediate CA certificate.

sudo openssl x509 -noout -in /etc/ssl/keys/itential.cert -text | grep Issuer:
sudo openssl x509 -noout -in /etc/ssl/keys/intermediate_ca.cert | grep Subject:

Verify the certificate chain matches in the output.

Issuer: C=US, ST=GA, L=Atlanta, O=Itential, LLC., OU=UAT, CN=db01
Subject: C=US, ST=GA, L=Atlanta, O=Itential, LLC., OU=UAT, CN=db01

Verify the issuer of the intermediate CA certificate matches the subject of the root CA certificate.

sudo openssl x509 -noout -in /etc/ssl/keys/intermediate_ca.cert | grep Issuer:
sudo openssl x509 -noout -in /etc/ssl/keys/root_ca.cert | grep Subject:

Verify the certificate chain matches in the output.

Issuer: C=US, ST=GA, L=Atlanta, O=Itential, LLC., OU=UAT, CN=db01
Subject: C=US, ST=GA, L=Atlanta, O=Itential, LLC., OU=UAT, CN=db01

Combine the intermediate CA and root certificates into a single certificate file.

sudo sh -c "cat /etc/ssl/keys/intermediate_ca.cert /etc/ssl/keys/root_ca.cert > /etc/ssl/keys/itential_ca_chain.cert"

Verify the files in /etc/ssl/keys match the sample output.

$ ls -1 /etc/ssl/keys
intermediate_ca.cert
itential.csr
itential.cert
itential.key
itential.keycert
itential_ca_chain.cert
root_ca.cert

When using CA-signed certificates, it is likely the intermediate CA and root certificates will be in the chain of trust. Confirm the itential_ca_chain.cert file is in the following format.
```
-----BEGIN CERTIFICATE-----
...
-----END CERTIFICATE-----
-----BEGIN CERTIFICATE-----
...
-----END CERTIFICATE-----
```

Add the intermediate CA and root certificates to the system trust store.

sudo cp /etc/ssl/keys/itential_ca_chain.cert /etc/pki/ca-trust/source/anchors/
sudo update-ca-trust

Configure the HA-Proxy Server

The HA-Proxy server is used to terminate HTTPS/TLS connections from clients and proxy them to the backend of the Automation Gateway server.

The HA-Proxy server comes with a well-defined default configuration file. Modify the default configuration to include frontend and backend definitions (see example below). To revert the proxy, simply remove the frontend and backend definitions from the default configuration.

$ vi /etc/haproxy/haproxy.cfg
...
frontend  automation-gateway-frontend
    reqadd X-Forwarded-Proto:\ https
    rspadd Strict-Transport-Security:\ max-age=31536000;\ includeSubDomains
    option forwardfor except 127.0.0.1
    maxconn 100
    bind *:8443 ssl crt /etc/ssl/certs/automation-gateway.pem force-tlsv12 ciphers DHE-RSA-AES256-GCM-SHA384:DHE-RSA-AES128-GCM-SHA256:ECDHE-RSA-AES256-GCM-SHA384:ECDHE-RSA-AES128-GCM-SHA256
    default_backend automation-gateway-backend

backend automation-gateway-backend
    server  app1 127.0.0.1:8083

Enable the HA-Proxy server to start on boot, and start the service.

$ sudo systemctl enable haproxy
$ sudo systemctl start haproxy
$ sudo systemctl status haproxy
● haproxy.service - HAProxy Load Balancer
   Loaded: loaded (/usr/lib/systemd/system/haproxy.service; enabled; vendor preset: disabled)
   Active: active (running) since Mon 2018-10-29 06:44:43 UTC; 1 weeks 2 days ago
 Main PID: 29603 (haproxy-systemd)
   CGroup: /system.slice/haproxy.service
           ├─29603 /usr/sbin/haproxy-systemd-wrapper -f /etc/haproxy/haproxy.cfg -p /run/haproxy.pid
           ├─29604 /usr/sbin/haproxy -f /etc/haproxy/haproxy.cfg -p /run/haproxy.pid -Ds
           └─29605 /usr/sbin/haproxy -f /etc/haproxy/haproxy.cfg -p /run/haproxy.pid -Ds

Oct 29 06:44:43 telegraph01 systemd[1]: Started HAProxy Load Balancer.
Oct 29 06:44:43 telegraph01 systemd[1]: Starting HAProxy Load Balancer...
Oct 29 06:44:43 telegraph01 haproxy-systemd-wrapper[29603]: haproxy-systemd-wrapper: executing /usr/sbin/haproxy -f /etc/haproxy/haproxy.cfg -p /run/haproxy.pid -Ds
Oct 29 06:44:43 telegraph01 haproxy-systemd-wrapper[29603]: [WARNING] 301/064443 (29604) : Setting tune.ssl.default-dh-param to 1024 by default, if your workload permit...disappear.
Hint: Some lines were ellipsized, use -l to show in full.

Itential Automation Gateway

On this page:

Post-Installation

Log In to Automation Gateway

Getting Started with the API

Add a Device

Get a Device List

Get Configuration for a Device

Run a Command on a Device

Create Keys and Certificates

Private Key and Certificate Request

Self-Signed Certificates

CA-Signed Certificates

Configure the HA-Proxy Server

Itential Automation Gateway

Help us improve by sending feedback...

On this page:

Post-Installation

Log In to Automation Gateway

Getting Started with the API

Add a Device

Get a Device List

Get Configuration for a Device

Run a Command on a Device

Create Keys and Certificates

Private Key and Certificate Request

Self-Signed Certificates

CA-Signed Certificates

Configure the HA-Proxy Server