Package: cgxsh
cgxsh (Preview)CloudGeniXSHell (cgxsh)Command-line access to the controller-based CloudGenix ION Troubleshooting Toolkit.WARNINGAs of 6/2023, Using username/password for controller login is DEPRECATED. This method has not been removed fromcgxshas of version 1.0.2b1. This may still function for specific legacy customers/accounts.Please switch to AUTH_TOKEN controller login as soon as possible.
A future update will add support for Prisma SASE TSG/Service Accounts, which will be the recommended authentication mode for future use.SynopsisThecgxshapplication is designed to allow a CloudGenix customer to replace a lot of the device-specific troubleshooting
traditionally performed via SSH with a cloud-based connectivity model.This utility attempts to behave "ssh-like", but there are fundamental differences.This utility should support Windows (Win 10 or higher) and Mac/Linux systems.RequirementsActive CloudGenix AccountPython >=3.10CloudGenix IONs running 5.2.1+ SoftwarePython modules:cloudgenix   -https://github.com/CloudGenix/sdk-pythonwebsockets   -https://websockets.readthedocs.io/en/stable/fuzzywuzzy   -https://github.com/seatgeek/fuzzywuzzy/pyyaml       -https://pyyaml.org/wiki/PyYAMLDocumentationtabulate     -https://github.com/astanin/python-tabulatecryptography -https://github.com/pyca/cryptographyInstallationVia PIP as simple aspip install cgxshCommands/FeaturescgxshSSH-replacement console utility using CloudGenix Cloud ControllerSimple commandline use:cgxsh "Portland ION"Interactive session by default, but specific commands and exit support too:cgxsh "Portland ION" "set paging off" "dump lldp all"Multi-tenant ESP/MSP support:cgxsh "Device_name"@"Tenant_Name"Configuration file with Multi-tenant support and optional Encryption to store credential(s)Fuzzy matching:edwards-mbp-pro:cgxshaaron$cgxsh"Portland ION"NomatchforPortlandION,bestguesses:1)PortlandSalesOfficeION,(86%)2)ION2K-A,(54%)3)ION2K-B,(54%)4)DHL-1,(36%)5)MAD-7K-1,(36%)6)MAD-7K-2,(36%)7)MAN-3K-1,(36%)Selectanumber,oranyotherkeytoexit:1Escape command menu for operations while connected:Portland Sales Office ION#  

cgxsh> ?
Commands are:
    send            Send special characters (help send for more)
    sdkdebug        Enable/Disable API/WebSocket debug messages (help sdkdebug for more)
    verbosity       Change cgxsh message verbosity (help verbosity for more)
    sessions        View active Toolkit Websocket Sessions (help sessions for more)
    sessions_kill   View and kill/close active Toolkit Websocket Sessions (help sessions_kill for more)
    quit            Close the connection and exit.
    close           Close the connection and exit.
    exit            Close the connection and exit.
    help            Additional help on sub commands. eg: help <command>
    
    Pressing <enter> on empty command line will return you to session.
    
cgxsh>cgxsh_generic_wsGeneric CloudGenix Websocket client to manage and experiment with Subscriptions.CloudGenix-required keepalive handlingJSON output formatting.cgxsh_create_defaultconfigCreates default cgxsh config (in $HOME/.cgxsh/config.yml)cgxsh_edit_configLaunches editor to editcgxshconfig.Mac/Linux: Default /usr/bin/viWindows: Default notepad.exeHandles decryption/re-encryption of configuration, if encrypted.cgxsh_decrypt_configAllows for decryptioncgxshconfiguration, if desired.cgxsh_encrypt_configEncryptscgxshconfiguration, if not already encrypted.LicenseMITVersionVersionBuildChanges1.0.2b1Support for Python 3.10+, Websockets 12.0+ (Github issue #3)1.0.1b1Fix for Github issues #1 and #21.0.0b1Initial Release0.0.1b1Placeholder for future release.(Optional) Environment VariablesAUTH_TOKENorX_AUTH_TOKEN: CloudGenix Controller Authentication Token (overrides configuration files)CGXSH_CONFIG_PASSWORD: Password for loading encryptedcgxshconfiguration.Usage info and examples.Connecting to an ION with fuzzy name match and no configuration info savedcgxsh \<ION name or ID>edwards-mbp-pro:cgxsh aaron$ cgxsh "Portland ION"
controller login: user@email.com
controller password: 

No match for Portland ION, best guesses:
  1) Portland Sales Office ION, (86%)
  2) ION2K-A, (54%)
  3) ION2K-B, (54%)
  4) MAN-3K-1, (36%)
  5) MAD-7K-2, (36%)
  6) MAD-7K-1, (36%)
  7) DHL-1, (36%)
Select a number, or any other key to exit: 1
Connecting to Portland Sales Office ION (15608897741660166).
Connected to 15608897741660166.
Escape character is '^]'.
ec2683ee-0d9c-8a64-3467-55121bb8a672 login: aaron
Password: 
Last login: Tue Dec 17 22:47:18 UTC 2019 on pts/0
 
Portland Sales Office ION# dump standingalarms 

Code		:	NETWORK_VPNPEER_UNREACHABLE
Ident		:	15608901339660208
Severity	:	minor
Raised		:	2019-12-12 20:54:44.834 +0000 UTC (122h6m8.469335222s ago)
Correlation ID	:	F70lP6T9
 vpn_link_id	:	15608901339570207
 al_id		:	15608896659530120

Portland Sales Office ION#Connecting to an ION with exact name match and controller/device configuration in config filecgxsh \<ION name or ID>edwards-mbp-pro:cgxsh aaron$ cgxsh "Portland Sales Office ION"
Connecting to Portland Sales Office ION (15608897741660166).
Connected to 15608897741660166.
Escape character is '^]'.

Last login: Tue Dec 17 22:52:46 UTC 2019 on pts/0
 
Portland Sales Office ION# dump standingalarms

Code		:	NETWORK_VPNPEER_UNREACHABLE
Ident		:	15608901339660208
Severity	:	minor
Raised		:	2019-12-12 20:54:44.834 +0000 UTC (122h6m8.469335222s ago)
Correlation ID	:	F70lP6T9
 vpn_link_id	:	15608901339570207
 al_id		:	15608896659530120

Portland Sales Office ION#Connecting to an ION on a sub-tenant via an ESP/MSP account with saved per-sub-tenant configurationscgxsh \<ION name or ID>edwards-mbp-pro:cgxsh aaron$ cgxsh "Portland Sales Office ION"@MyCustomerClientZ 
No match for MyCustomerClientZ, best guesses:
  1) MyCustomerClientA, (90%)
  2) CustomerClientB, (22%)
  3) CustomerClientC, (22%)
  4) CustomerClientD, (22%)
  5) CustomerClientE, (22%)
  6) CustomerClientF, (22%)
Select a number, or any other key to exit: 1

Connecting to Client MyCustomerClientA (MyCustomerClient_canonicalname).
Connecting to Portland Sales Office ION (15608897741660166).
Connected to 15608897741660166.
Escape character is '^]'.

Last login: Tue Dec 17 22:52:46 UTC 2019 on pts/0
 
Portland Sales Office ION# dump standingalarms

Code		:	NETWORK_VPNPEER_UNREACHABLE
Ident		:	15608901339660208
Severity	:	minor
Raised		:	2019-12-12 20:54:44.834 +0000 UTC (122h6m8.469335222s ago)
Correlation ID	:	F70lP6T9
 vpn_link_id	:	15608901339570207
 al_id		:	15608896659530120

Portland Sales Office ION#Managing connected cgxsh/web toolkit users to the current IONPress escape char (CTRL-]) during cgxsh sessionPortland Sales Office ION#  

cgxsh> ?
Commands are:
    send            Send special characters (help send for more)
    sdkdebug        Enable/Disable API/WebSocket debug messages (help sdkdebug for more)
    verbosity       Change cgxsh message verbosity (help verbosity for more)
    sessions        View active Toolkit Websocket Sessions (help sessions for more)
    sessions_kill   View and kill/close active Toolkit Websocket Sessions (help sessions_kill for more)
    quit            Close the connection and exit.
    close           Close the connection and exit.
    exit            Close the connection and exit.
    help            Additional help on sub commands. eg: help <command>
    
    Pressing <enter> on empty command line will return you to session.
    
cgxsh> sessions_kill element
Toolkit Sessions:
  Index  Element                    Operator                  Age       State                                  Session ID
-------  -------------------------  ------------------------  --------  -------  ----------------------------------------
      1  Portland Sales Office ION  aaron@cloudgenix.com      1h36m12s  active   1576618422757015099992703857847609972162
      2  Portland Sales Office ION  otheruser@cloudgenix.com  9m9s      active   1576623645452007700007702497325448497534
Total: 2
Enter Index to remove (range for multiple (eg. 1,3,5-10), or x to exit: 2
Planning to end the following sessions (index): 2.
Confirm? (y/n): y
Ended session 2 to Portland Sales Office ION.

cgxsh> 
Portland Sales Office ION#Encrypting a clear-text configuration.edwards-mbp-pro:cgxshaaron$cgxsh_encrypt_configEnterpasswordtoencryptfile:Confirmfileencryptionpassword:Savingencryptedconfiguration:Done.
edwards-mbp-pro:cgxshaaron$Default config.yml template---
type: cgxsh
version: 1.0

# This section allows you to specify a default AUTH_TOKEN, DEVICE_USER and DEVICE_PASSWORD. These will be used
# by default if others are not specified.
#
# For Controller authentication, AUTH_TOKEN is used first (if present.) If no AUTH_TOKEN, CONTROLLER_USER and 
# CONTROLLER_PASSWORD are used. If those are missing or fail, login will be prompted.
# 
# If the DEVICE_USER or DEVICE_PASSWORD fails, you will be prompted to finish logging in when connecting to the device.

DEFAULT:
    AUTH_TOKEN:
    CONTROLLER_USER:
    CONTROLLER_PASSWORD:
    DEVICE_USER: 
    DEVICE_PASSWORD: 

# If you have a CloudGenix MSP/ESP portal account, you can specify the device access credentials on a per-client
# basis. If the client name is not an exact match, the credentials will not be used.
#
# Note: MSP/ESP client attachment requires DEFAULT: CONTROLLER_USERNAME/CONTROLLER_PASSOWRD. AUTH_TOKENs cannot be used. 

ESP:
  "Example Client1 Name Match":
    DEVICE_USER:
    DEVICE_PASSWORD: 
    
  "Example Client2 Name Match":
    DEVICE_USER:
    DEVICE_PASSWORD:Subscribe to generic websocket to get push config change messages (element, site in this example)cgxsh_generic_wsedwards-mbp-pro:cgxsh aaron$ cgxsh_generic_ws
Connected.
> { "type": "PUT", "uri": "/v2.0/api/tenants/10006/subscriptions", "body": {"type": "config_change", "subscriptions": [{"resource_key": "elements"},{"resource_key": "sites"}] }}
< {
      "type": "PUT",
      "uri": "/v2.0/api/tenants/10006/subscriptions",
      "body": {
          "id": "15766253860930016",
          "_etag": 1,
          "_content_length": 0,
          "_schema": 0,
          "_created_on_utc": 15766253860930016,
          "_updated_on_utc": 15766253860930016,
          "_status_code": "200",
          "_message_id": "1576625386053000499998772050152704482435",
          "_request_id": "1576625386053000399991149536419934892671",
          "subscriptions": [
              {
                  "resource_key": "elements"
              },
              {
                  "resource_key": "sites"
              }
          ],
          "type": "config_change"
      }
  }subsequent time later when configuration change on element occurs..< {
      "id": "15766254376560072",
      "_created_on_utc": 15766254376560072,
      "_updated_on_utc": 15766254376560072,
      "_message_id": "1576625437641018399996760510275758800343",
      "_request_id": "1576625437641018299992839389780516744938",
      "operator_id": "15713488339050031",
      "operator_tenant_id": "10006",
      "esp_tenant_id": "123",
      "request_id": "1576625437588017700003942214959372913327",
      "source_ip": "96.64.220.253",
      "resource_key": "elements",
      "resource_id": "15608897741660166",
      "resource_etag": 1728,
      "resource_version": "v2.3",
      "request_type": "PUT",
      "request_uri": "/v2.3/api/tenants/10006/elements/15608897741660166",
      "request_body": {
          "_etag": 1727,
          "_schema": 0,
          "id": "15608897741660166",
          "site_id": "15608896590040129",
          "name": "Portland Sales Office ION",
          "description": null,
          "tags": [
              "SNOW-high"
          ],
          "sw_obj": null,
          "cluster_insertion_mode": null,
          "cluster_member_id": null,
          "l3_direct_private_wan_forwarding": true,
          "l3_lan_forwarding": true,
          "vpn_to_vpn_forwarding": false,
          "network_policysetstack_id": null,
          "priority_policysetstack_id": null,
          "nat_policysetstack_id": null,
          "spoke_ha_config": null
      },
      "response_code": 200,
      "response_body": {
          "id": "15608897741660166",
          "_etag": 1728,
          "_content_length": "0",
          "_schema": 0,
          "_created_on_utc": 15608897741660166,
          "_updated_on_utc": 15766254376080179,
          "_status_code": "200",
          "_request_id": "1576625437588017700003942214959372913327",
          "_debug": null,
          "_info": null,
          "_warning": null,
          "_error": null,
          "tenant_id": "10006",
          "site_id": "15608896590040129",
          "software_version": "5.2.1-a85",
          "hw_id": "ec2683ee-0d9c-8a64-3467-55121bb8a672",
          "serial_number": "ec2683ee-0d9c-8a64-3467-55121bb8a672",
          "model_name": "ion 3102v",
          "name": "Portland Sales Office ION",
          "description": null,
          "role": "SPOKE",
          "state": "bound",
          "allowed_roles": [
              "HUB",
              "SPOKE"
          ],
          "cluster_insertion_mode": null,
          "cluster_member_id": null,
          "l3_direct_private_wan_forwarding": true,
          "l3_lan_forwarding": true,
          "connected": true,
          "admin_action": null,
          "deployment_op": null,
          "network_policysetstack_id": null,
          "priority_policysetstack_id": null,
          "spoke_ha_config": null,
          "tags": [
              "SNOW-high"
          ],
          "nat_policysetstack_id": null,
          "vpn_to_vpn_forwarding": false
      },
      "time_ms": 52,
      "request_content_length": 439,
      "response_content_length": 0,
      "request_ts": 1576625437588,
      "response_ts": 1576625437640
  }
>Command-line argumentscgxshusage: cgxsh [-h] [--controller-email CONTROLLER_EMAIL]
             [--controller-password CONTROLLER_PASSWORD]
             [--device-user DEVICE_USER] [--device-password DEVICE_PASSWORD]
             [--noexit] [--controller CONTROLLER] [--insecure] [--noregion]
             [--override-host-header FORCE_HOST] [--verbosity VERBOSITY]
             [--sdkdebug SDKDEBUG]
             element[@client] ...

cgxsh (1.0.0b1)

optional arguments:
  -h, --help            show this help message and exit

cgxsh_args:
  CGXSH Arguments

  --controller-email CONTROLLER_EMAIL, -E CONTROLLER_EMAIL
                        Use this email for controller login.
  --controller-password CONTROLLER_PASSWORD
                        Use this password for controller login. NOT
                        RECOMMENDED - Password will likely be stored in shell
                        history.
  --device-user DEVICE_USER
                        Use this user to login to the Element Toolkit.
  --device-password DEVICE_PASSWORD
                        Use this password to login to the Element Toolkit. NOT
                        RECOMMENDED - Password will likely be stored in shell
                        history.
  --noexit              If using commands, do not exit after running commands.
                        Maintain interactive shell.
  element[@client]      Element name or ID to connect to. If connecting as
                        ESP/MSP account, @client name or ID is required.
  commands              (Optional) Strings of space-separated Toolkit commands
                        to run. Example: "set paging off" "dump lldp all"

Controller Options:
  These options change how the program connects to the CloudGenix Controller

  --controller CONTROLLER, -C CONTROLLER
                        Override Controller API URI. Default:
                        https://api.elcapitan.cloudgenix.com
  --insecure, -I        Do not verify API SSL certificate
  --noregion, -NR       Ignore Region-based redirection.
  --override-host-header FORCE_HOST, -OH FORCE_HOST
                        Force Host Header on API requests.

Debug:
  These options enable debugging output

  --verbosity VERBOSITY, -V VERBOSITY
                        CGXSH client verbosity.
  --sdkdebug SDKDEBUG, -D SDKDEBUG
                        Enable CloudGenix SDK Debug output, levels 0-3cgxsh_generic_wsusage: cgxsh_generic_ws [-h] [--no-format] [--show-keepalives]
                        [--controller-email CONTROLLER_EMAIL]
                        [--controller-password CONTROLLER_PASSWORD]
                        [--controller CONTROLLER] [--insecure] [--noregion]
                        [--override-host-header FORCE_HOST]
                        [--verbosity VERBOSITY] [--sdkdebug SDKDEBUG]
                        [[@client]]

cgxsh_generic_ws (1.0.0b1)

optional arguments:
  -h, --help            show this help message and exit

cgxsh_generic_ws args:
  CGXSH Generic WebSocket Client Arguments

  --no-format, -NF      Disable output pretty-printing/formatting.
  --show-keepalives     Show background keepalive messages
  --controller-email CONTROLLER_EMAIL, -E CONTROLLER_EMAIL
                        Use this email for controller login.
  --controller-password CONTROLLER_PASSWORD
                        Use this password for controller login. NOT
                        RECOMMENDED - Password will likely be stored in shell
                        history.
  [@client]             If connecting as ESP/MSP account, @client name or ID
                        is required.

Controller Options:
  These options change how the program connects to the CloudGenix Controller

  --controller CONTROLLER, -C CONTROLLER
                        Override Controller API URI. Default:
                        https://api.elcapitan.cloudgenix.com
  --insecure, -I        Do not verify API SSL certificate
  --noregion, -NR       Ignore Region-based redirection.
  --override-host-header FORCE_HOST, -OH FORCE_HOST
                        Force Host Header on API requests.

Debug:
  These options enable debugging output

  --verbosity VERBOSITY, -V VERBOSITY
                        CGXSH Generic WebSocket Client verbosity.
  --sdkdebug SDKDEBUG, -D SDKDEBUG
                        Enable CloudGenix SDK Debug output, levels 0-3cgxsh_edit_configusage: cgxsh_edit_config [-h] [--editor EDITOR]

cgxsh_edit_config (1.0.0b1)

optional arguments:
  -h, --help            show this help message and exit

cgxsh_edit_config:
  CGXSH Edit Configuration Arguments

  --editor EDITOR, -E EDITOR
                        Use this program to edit configuration. Editor must
                        supportfilename as first argument. Default:
                        /usr/bin/vicgxsh_edit_configusage: cgxsh_decrypt_config [-h] [--force FORCE]

cgxsh_decrypt_config (1.0.0b1)

optional arguments:
  -h, --help            show this help message and exit

cgxsh_decrypt_config:
  CGXSH Decrypt Configuration Arguments

  --force FORCE, -F FORCE
                        Export configurations to alternate file. Don't verify
                        contents after decryption. Must specify filename to
                        decrypt contents into, since config may be corrupt.
                        Valid password is still required.