Install a Single Node Air-Gap Target

1. The install assumes that you have CentOS 7 as your operating system. Check your CentOS 7 version.

   $ sudo cat /etc/centos-release

2. Set the user for the target machine to a username of your choice. For example, autoid.

   $ sudo adduser autoid

3. Set the password for the user you created in the previous step.

   $ sudo passwd autoid

4. Configure the user for passwordless sudo.

   $ echo "autoid  ALL=(ALL)  NOPASSWD:ALL" | sudo tee /etc/sudoers.d/autoid

5. Add administrator privileges to the user.

   $ sudo usermod -aG wheel autoid

6. Change to the user account.

   $ su - autoid

7. Install yum-utils package on the deployer machine. yum-utils is a utilities manager for the Yum RPM package repository. The repository compresses software packages for Linux distributions.

   $ sudo yum install -y yum-utils

8. Create the installation directory. Note that you can use any install directory for your system as long as your run the deployer.sh script from there. Also, the disk volume where you have the install directory must have at least 8GB free space for the installation.

   $ mkdir ~/autoid-config

1. On the target machine, set up the Docker-CE repository.

   $ sudo yum-config-manager \
        --add-repo https://download.docker.com/linux/centos/docker-ce.repo

2. Install the latest version of the Docker CE, the command-line interface, and containerd.io, a containerized website.

   $ sudo yum install -y docker-ce docker-ce-cli containerd.io

3. Enable Docker to start at boot.

   $ sudo systemctl enable docker

4. Start Docker.

   $ sudo systemctl start docker

5. Check that Docker is running.

   $ systemctl status docker

6. Add the user to the Docker group.

   $ sudo usermod -aG docker ${USER}

7. Reset the privileges on the Docker socket.

   $ sudo chmod 666 /var/run/docker.sock

1. On the deployer machine, run ssh-keygen to generate an RSA keypair, and then click Enter. You can use the default filename. Enter a password for protecting your private key.

   $ ssh-keygen -t rsa -C "autoid"

   The public and private rsa key pair is stored in home-directory/.ssh/id_rsa and home-directory/.ssh/id_rsa.pub.

2. Copy the SSH key to the ~/autoid-config directory.

    $ cp ~/.ssh/id_rsa ~/autoid-config

3. Change the privileges to the file.

   $ chmod 400 ~/autoid-config/id_rsa

1. On the deployer machine, change to the installation directory.

   $ cd ~/autoid-config/

2. Log in to the ForgeRock Google Cloud Registry (gcr.io) using the registry key. The registry key is only available to ForgeRock Autonomous Identity customers. For specific instructions on obtaining the registry key, see How To Configure Service Credentials (Push Auth, Docker) in Backstage.

   $ docker login -u _json_key -p "$(cat autoid_registry_key.json)" https://gcr.io/forgerock-autoid

   You should see:

   Login Succeeded

3. Run the create-template command to generate the deployer.sh script wrapper. Note that the command sets the configuration directory on the target node to /config. Note that the --user parameter eliminates the need to use sudo while editing the hosts file and other configuration files.

   $ docker run --user=`id -u` -v ~/autoid-config:/config -it gcr.io/forgerock-autoid/deployer:2020.10.2 create-template

4. Make the script executable.

   $ chmod +x deployer.sh

5. Download the Docker images. This step downloads software dependencies needed for the deployment and places them in the autoid-packages directory.

   $ ./deployer.sh download-images

6. Create a tar file containing all of the Autonomous Identity binaries.

   $ tar czf autoid-packages.tgz deployer.sh autoid-packages/*

7. Copy the autoid-packages.tgz, deployer.sh, and SSH key (id_rsa) to a USB drive or portable hard drive.

1. Create the ~/autoid-config directory if you haven't already.

   $ mkdir ~/autoid-config

2. Copy the autoid-package.tgz tar file from the portable storage device.

3. Unpack the tar file.

   $ tar xf autoid-packages.tgz -C ~/autoid-config

4. On the air-gap host node, copy the SSH key to the ~/autoid-config directory.

5. Change the privileges to the file.

   $ chmod 400 ~/autoid-config/id_rsa

6. Change to the configuration directory.

   $ cd ~/autoid-config

7. Install Docker.

   $ sudo ./deployer.sh install-docker

8. Log out and back in.

9. Change to the configuration directory.

   $ cd ~/autoid-config

10. Import the deployer image.

    $ ./deployer.sh import-deployer

    You should see:

    ...
    db631c8b06ee: Loading layer [==================================================>]   2.56kB/2.56kB
    2d62082e3327: Loading layer [==================================================>]  753.2kB/753.2kB
    Loaded image: gcr.io/forgerock-autoid/deployer2020.10.1

11. Create the configuration template using the create-template command. This command creates the configuration files: ansible.cfg, vars.yml, vault.yml and hosts.

    $ ./deployer.sh create-template

    You should see:

    Config template is copied to host machine directory mapped to /config

1. Open a text editor and edit the ansible.cfg to set up the target machine user and SSH private key file location on the target node. Make sure that the remote_user exists on the target node and that the deployer machine can ssh to the target node as the user specified in the id_rsa file.

   [defaults]
   host_key_checking = False
   remote_user = autoid
   private_key_file = id_rsa

2. Open a text editor and edit the ~/autoid-config/vars.yml file to configure specific settings for your deployment:

   1. Domain and Target Environment. Set the domain name and target environment specific to your deployment by editing the /autoid-config/vars.xml file. By default, the domain name is set to forgerock.com and the target environment is set to autoid. The default Autonomous Identity URL will be: https://autoid-ui.forgerock.com. For this example, we use the default values.

      domain_name: forgerock.com
      target_environment: autoid

      If you change the domain name and target environment, you need to also change the certificates to reflect the new changes. For more information, see Customize the Domain and Namespace.

   2. Analytics Data Directory and Analytics Configuration Direction. Although rarely necessary for a single node deployment, you can change the analytics and analytics configuration mount directories by editing the properties in the ~/autoid-config/vars.yml file.

      analytics_data_dir: /data
      analytics_conf_dif: /data/conf

   3. Dark Theme Mode. Optional. By default, the Autonomous Identity UI displays its pages with a light background. You can set a dark theme mode by setting the enable_dark_theme property to true.

   4. Database Type. By default, Apache Cassandra is set as the default database for Autonomous Identity. For MongoDB, set the db_driver_type: to mongo.

      db_driver_type: mongo

   5. Private IP Address Mapping. An air-gap deployment has no external IP addresses, but you may still need to define a mapping in the ~/autoid-config/vars.yml file, if your internal IP address differs from an external IP, say in a virtual air-gapped configuration.

      If your external and internal IP addresses are the same, you can skip this step.

      Add the private_ip_address_mapping property in the ~/autoid-config/vars.yml file. You can look up the private IP on the cloud console, or run sudo ifconfig on the target host. Make sure the values are within double quotes. The key should not be in double quotes and should have two spaces preceding the IP address.

      private_ip_address_mapping:
        external_ip:  "internal_ip"

      For example:

      private_ip_address_mapping:
        34.70.190.144:  "10.128.0.71"

   6. Authentication Option. Autonomous Identity provides a single sign-on (SSO) feature that you can configure with an OIDC identity provider.

   7. JWT Expiry and Secret File. Optional. By default, the session JWT is set at 30 minutes. To change this value, set the jwt_expiry property to a different value.

      jwt_expiry: "30 minutes"

   8. Elasticsearch Heap Size. Optional. The default heap size for Elasticsearch is 1GB, which may be small for production. For production deployments, uncomment the option and specify 2G or 3G.

      #elastic_heap_size: 1g   # sets the heap size (1g|2g|3g) for the Elastic Servers

   9. OpenLDAP. Optional. Autonomous Identity installs an OpenLDAP Docker image on the target server to hold user data. Administrators can add or remove users or change their group privileges using the phpldapadmin command. You can customize your OpenLDAP domain, base DN, and URL to match your company's environment. For more information, see Configuring LDAP.

3. Open a text editor and enter the target host's private IP addresses in the ~/autoid-config/hosts file. The following is an example of the ~/autoid-config/hosts file:

   Click to See a Host File for Cassandra Deployments

   If you configured Cassandra as your database, the ~/autoid-config/hosts file is as follows for single-node air-gapped target deployment:

   [docker-managers]
   10.128.0.34
   
   [docker-workers]
   10.128.0.34
   
   [docker:children]
   docker-managers
   docker-workers
   
   [cassandra-seeds]
   10.128.0.34
   
   [cassandra-workers]
   10.128.0.34
   
   [spark-master]
   10.128.0.34
   
   [spark-workers]
   10.128.0.34
   
   [analytics]
   10.128.0.34
   
   [mongo_master]
   #ip# mongodb_master=True
   
   [mongo_replicas]
   
   [mongo:children]
   mongo_replicas
   mongo_master
   
   # ELastic Nodes
   [odfe-master-node]
   10.128.0.34
   
   [odfe-data-nodes]
   
   [kibana-node]
   10.128.0.34

   Click to See a Host File for MongoDB Deployments

   If you configured MongoDB as your database, the ~/autoid-config/hosts file is as follows for single-node air-gapped target deployment:

   [docker-managers]
   10.128.0.34
   
   [docker-workers]
   10.128.0.34
   
   [docker:children]
   docker-managers
   docker-workers
   
   [cassandra-seeds]
   
   [cassandra-workers]
   
   [spark-master]
   10.128.0.34
   
   [spark-workers]
   10.128.0.34
   
   [analytics]
   10.128.0.34
   
   [mongo_master]
   10.128.0.34  mongodb_master=True
   
   [mongo_replicas]
   10.128.0.34
   
   [mongo:children]
   mongo_replicas
   mongo_master
   
   # ELastic Nodes
   [odfe-master-node]
   10.128.0.34
   
   [odfe-data-nodes]
   
   [kibana-node]
   10.128.0.34

4. Set the Autonomous Identity passwords, located at ~/autoid-config/vault.yml.

   Note

   Do not include special characters & or $ in vault.yml passwords as it will result in a failed deployer process.

   configuration_service_vault:
     basic_auth_password: Welcome123
   
   openldap_vault:
     openldap_password: Welcome123
   
   cassandra_vault:
     cassandra_password: Welcome123
     cassandra_admin_password: Welcome123
   
   mongo_vault:
     mongo_admin_password: Welcome123
     mongo_root_password: Welcome123
   
   elastic_vault:
     elastic_admin_password: Welcome123
     elasticsearch_password: Welcome123

5. Encrypt the vault file that stores the Autonomous Identity passwords, located at ~/autoid-config/vault.yml. The encrypted passwords will be saved to /config/.autoid_vault_password. The /config/ mount is internal to the deployer container.

   $ ./deployer.sh encrypt-vault

6. Run the deployment.

   $ ./deployer.sh run

Resolve the hostname:

1. Configure your DNS servers to access Autonomous Identity dashboard and self-service applications on the target node. The following domain names must resolve to the IP address of the target node: <target-environment>-ui.<domain-name> and <target-environment>-selfservice.<domain-name>.

2. If DNS cannot resolve target node hostname, edit it locally on the machine that you want to access Autonomous Identity using a browser. Open a text editor and add an entry in the /etc/hosts file for the self-service and UI services for each managed target node.

   target-ip-address  <target-environment>-ui.<domain-name> <target-environment>-selfservice.<domain-name>

   For example:

   34.70.190.144  autoid-ui.forgerock.com autoid-selfservice.forgerock.com

3. If you set up a custom domain name and target environment, add the entries in /etc/hosts. For example:

   34.70.190.144  myid-ui.abc.com  myid-selfservice.abc.com

   For more information on customizing your domain name, see Customize the Domain and Namespace.

Access the Autonomous Identity console UI:

1. Open a browser, and point it to https://autoid-ui.forgerock.com/ (or your customized URL: https://myid-ui.abc.com).

2. Log in as a test user: bob.rodgers@forgerock.com. Enter the password: Welcome123.

Check Cassandra:

1. On the target node, check the status of Apache Cassandra.

   $ /opt/autoid/apache-cassandra-3.11.2/bin/nodetool status

2. An example output is as follows:

   Datacenter: datacenter1
   =======================
   Status=Up/Down
   |/ State=Normal/Leaving/Joining/Moving
   --  Address       Load       Tokens       Owns (effective)  Host ID                               Rack
   UN  34.70.190.144 1.33 MiB   256          100.0%            a10a91a4-96e83dd-85a2-4f90d19224d9  rack1

Check the status of MongoDB:

• On the target node, check the status of MongoDB.

  $ mongo --tls --host <Host IP Address> --tlsCAFile /opt/autoid/mongo/certs/rootCA.pem   --tlsAllowInvalidCertificates  --tlsCertificateKeyFile /opt/autoid/mongo/certs/mongodb.pem

Check Spark:

• SSH to the target node and open Spark dashboard using the bundled text-mode web browser

  $ elinks http://localhost:8080

  You should see Spark Master status as ALIVE and worker(s) with State ALIVE.

  Click to See an Example of the Spark Dashboard
  

Access self-service:

• Open a browser and point it to: https://autoid-selfservice.forgerock.com/.

  Click to See an Example of the Self-Service Dashboard
  

Start the analytics service:

• Run the analytics pipeline commands. This may take a bit longer than the install, depending on the size of your dataset. For specific information, see Run the Analytics Pipeline.