Skip to main content

Installation Guide

Welcome to the Xshield Utility Installation Guide. This comprehensive guide is designed to walk you through the process of installing the Xshield Utility package on a local machine or virtual machine (VM).

Through this guide, you'll be provided with all the necessary information to:

  • Prepare your VM for the installation of the Xshield Utility package.
  • Navigate the installation process, including configuration of the utility environment and verification of successful setup.
  • Understand the prerequisites and system requirements for different environments to ensure compatibility and performance.

Our goal is to facilitate a seamless installation process, allowing you to quickly begin demonstrating the powerful micro-segmentation solutions offered by the xShield platform.

System Requirements:​

The Xshield Utility requires the following:

  • Operating System: Ubuntu 22.X, macOS, Windows
  • Compute : Minimum 4 vCPUs, 16 GB of Memory and 30 GB of Storage
  • Network: Access to the internet
  • Powershell or Bash: Powershell for Windows, Bash for Linux and macOS

Pre-requisites:​

  1. Generate API key credentials on the Xshield platform portal.
  2. Save the API key credentials and download the private key (.pem file).
  3. Ensure agents are deployed and assets are discovered.

Setup and Configuration:​

  1. Please follow steps from Prepare Configuration Credentials to create the config file

  2. Download the Utility Package:

    1. Ensure the user has root or admin privileges or switch to root user, Install wget & tar packages on the workspace

    For Ubuntu systems,

    sudo su
    apt-get update -y
    apt install wget tar

    For macOS systems,

    sudo su
    brew install wget

    most macOS systems come with tar package already installed, you can confirm it with tar --version command

    For machines with Windows OS, please follow instructions from Windows Installation Guide

    1. Download the latest published Utility package

    Please replace <artifacts-url> with the appropriate URL of your domain:

    • For ng.colortokens.com and bom.colortokens.com, use artifacts.<domain url> eg: artifacts.ng.colortokens.com
    • For all other domains, use artifacts-<domain url> eg: artifacts-syd.colortokens.com, artifacts-fra.colortokens.com

    Ensure that you substitute <domain> with your specific domain name to form the correct URL for downloading the package.

    wget https://<artifacts-url>/ct-xshield-util/latest/packages/xshield_utility.tar.gz
    1. Untar the Xshield Utility package
    mkdir -p xshield_utility
    tar -xzvf xshield_utility.tar.gz -C xshield_utility

  3. Run installXshieldUtil.sh: Run the installXshieldUtil.sh script located in the util directory

    1. Change directory to the util directory
    cd xshield_utility/util
    1. Run the install script
    bash installXshieldUtil.sh

    1. Fill up the details for config.yaml

      1. Option 1:
    root@xshield-util-01:/home/user/util# bash installXshieldUtil.sh
    Configuration setup:
    You can set up the config.yaml file in one of two ways:
      1. If you already have a config.yaml and API private key, select Option 1 and provide their file paths.
      2. If you do not have a config.yaml, select Option 2 to generate one using the interactive setup.

    Please choose an option:
    1) Use existing config.yaml and API private key
    2) Generate config.yaml interactively   
    1
    Please provide the config.yaml file path
    <path-to-config.yaml-file>       # /home/ctuser/config.yaml
    Please provide the API private key filepath
    <path-to-private-key-file>       # /home/ctuser/colortokens_key.pem
    Config file: /home/ctuser/config.yaml
    API private key: /home/ctuser/colortokens_key.pem
    1. Option 2:
    Please choose an option:
    1) Use existing config.yaml and API private key
    2) Generate config.yaml interactively   
    2
    Configuration is not valid or is missing required fields. Please provide config details:
    No valid configuration found. Let's create one.
    Enter your Xshield domain (e.g., https://ng.colortokens.com): <XSHIELD_URL>
    Enter your deployment key: <DEPLOYMENT_KEY> (e.g. 6g3gryhs3s0pm)
    Enter your fingerprint: <FINGERPRINT> (e.g. 13:24:13:14:4e:b0:e1:4c:1d:42:ff:f5:13:15:11:10)
    Enter your tenant ID: <TENANT_ID> (e.g. 17e74a1e-6a12-42f9-b21d-a11a5e323c33 )
    Enter your user ID: <USER_ID> (e.g. b8b111acb-a2ad-4339-94a1-daaaa0db3721)
    Enter your pem file location: <PRIVATE_KEY_PATH> (e.g. /home/ctuser/ng-api-key.pem)
    Configuration saved to /Users/muqeed.abdul/Documents/Pycharm_Projects/xshieldUtil/config/config.yaml

    Validating Installation and displaying help...
    XShield Utility installation complete! Please activate the python virtual env via --> "source .venv/bin/activate" 
   and execute --> "python3 xshield_util.py -h" to view the help menu
  1. Please check the administration guide for steps to launch the xshield utility tool and perform command executions Deployment of Xshield Utility tool