Introduction

• The JS7 offers to perform any operation on the Agent inventory by the JS7 - REST Web Service API.
  • Note that any operation available with the JOC Cockpit GUI makes use of the REST Web Service API.
  • For detailed information see the Technical Documentation of the REST Web Service API.
• The REST Web Service API can be accessed from Shell utilities such as curl.
• In addition, a PowerShell module is available for simplified access to the REST Web Service API. This is described in the JS7 - PowerShell Module article.

The script introduced in this article can be used to export Agents to an archive file (.zip, .tar.gz) holding .json files per Agent.

Export Agent Script

The script is provided for download and can be used to automate export of Agents.

• The script is available for Linux and MacOS® using bash shell.
• The script terminates with exit code 0 to signal successful export, with exit code 1 for command line argument errors and with exit code 4 for non-recoverable errors. Exit code 3 signals that no matching Agents have been found.
• The script is intended as a baseline example for customization by JS7 users and by SOS within the scope of professional services.
  

Prerequisites

The Script requires the jq utility to be available from the operating system. 

jq ships with the MIT license, see https://opensource.org/licenses/MIT.

Download

Download: export-agent.sh

Usage

Invoking the script without arguments displays the usage clause:

Usage: delete-notices.sh [Options] [Switches]

  Options:
    --url=<url>                               | required: JOC Cockpit URL
    --user=<account>                          | required: JOC Cockpit user account
    --password=<password>                     | optional: JOC Cockpit password
    --ca-cert=<path>                          | optional: path to CA Certificate used for JOC Cockpit login
    --client-cert=<path>                      | optional: path to Client Certificate used for login
    --client-key=<path>                       | optional: path to Client Key used for login
    --controller-id=<identifier>              | required: Controller ID
    --export-file=<identifier>                | required: path to export file
    --export-format=<ZIP|TAR_GZ>              | optional: export file format, default: ZIP
    --agent-id=<identifier[,identifier]>      | optional: one or more Agent IDs separated by comma
    --log-dir=<directory>                     | optional: path to the directory holding the script's batch log files

  Switches:
    -h | --help                              | displays usage
    -v | --verbose                           | displays verbose output
    -p | --password                          | asks for password
    --show-logs                              | shows log output if --log-dir is used
    --make-dirs                              | creates directories if they do not exist

Options

• --url
  • Specifies the URL by which JOC Cockpit is accessible using <http|https>://<host>:<port>.
  • Example: http://centostest-primary.sos:4446
  • Example: https://centostest-primary.sos:4443
• --user
  • Specifies the user account for login to JOC Cockpit. If JS7 - Identity Services are available for Client authentication certificates that are specified with the --client-cert and --client-key options then their common name (CN) attribute has to match the user account.
  • If a user account is specified then a password can be specified using the --password option or interactive keyboard input can be prompted using the -p switch.
• --password
  • Specifies the password used for the account specified with the --user option to login to JOC Cockpit.
  • Consider use of the -p switch offering a secure option for interactive keyboard input.
• --cacert
  • Specifies the path to a .pem file that holds the Root CA Certificate and optionally Intermediate CA Certificates to verify HTTPS connections to JOC Cockpit.
• --client-cert
  • Specifies the path to a .pem file that holds the Client Certificate if HTTPS mutual authentication is used..
• --client-key
  • Specifies the path to a .pem file that holds the Client Privae Key if HTTPS mutual authentication is used..
• --controller-id
  • Specifies the identification of the Controller that holds related orders.
• --export-file
  • Specifies the path to the archive file that should be created.
  • The archive file will include one .json file per exported Agent.
• --export-format
  • Specifies the format of the export file which is one of ZIP or TAR_GZ.
  • If the option is not specified then the value will be used from the .zip or .tar.gz extension of the export file.
• --agent-id
  • Optionally specifies one or more Agents from the related Agent ID to be exported. If more than one Agent ID is specified then they are separated by comma.
  • If the option is not present then all Agents will be exported.
• --log-dir
  • If a log directory is specified then the script will log information about processing steps to a log file in this directory.
  • File names are created according to the pattern: export-agent.<yyyy>-<MM>-<dd>T<hh>-<mm>-<ss>.log
  • For example: export-agent.2022-03-19T20-50-45.log

Switches

• -h | --help
  • Displays usage.
• -p | --password
  • Asks the user for interactive keyboard input of the password used for the account specified with the --user option..
  • The switch is used for secure interactive input as an alternative to use of the option --password=<password>.
• -v | --verbose
  • Displays verbose log output.
• --show-logs
  • Displays the log output created by the script if the --log-dir option is used.
• --make-dirs
  • If directories are missing that are indicated with the --log-dir option then they will be created.

Exit Codes

• 0: deletion of notices successfully initiated
• 1: argument errors
• 3: no Agents found
• 4: JS7 REST Web Service is not reachable or reports errors

Examples

The following examples illustrate typical use cases.

Export all Agents

./export-agent.sh \
    --url=http://joc-2-0-primary:7446 \
    --user=root \
    --password=root \
    --controller-id=controller \
    --export-file=export.zip

# exports all Agents registered with the given Controller
# creates the export file in .zip format

Export selected Agents

./export-agent.sh \
    --url=https://joc-2-0-primary:7443 \
    --cacert=/home/sos/jstest/certs/root-ca.pem \
    --user=root \
    -p \
    --controller-id=controller \
    --agent-id=agent_001,agent_002,agent_cluster_001 \
    --export-file=export.zip
 
# exports Agents specified from their Agent ID
# exports any Subagents if the Agent ID of an Agent Cluster is specified 
# asks the user for interactive keyboard input of the password used for the account specified

Further Resources

• JS7 - REST Web Service API