Command Line Interface (CLI)
Introduction
The Universal Controller Command Line Interface (CLI) is implemented as a set of functions that perform specific actions in a Universal Controller. The results of the actions are written to the CLI standard output.
The CLI command, uagcmd, executes a function according to information specified in its required and optional Global parameters and function-specific parameters.
CLI Functions
CLI functions perform specific actions in a Universal Controller.
The CLI command, uagcmd, can execute functions on any system that has TCP/IP connectivity to the Universal Message Service (OMS).
The command line syntax for each execution of uagcmd must specify a single CLI function, required / optional Global parameters, and required / optional function-specific parameters. You must use the required Global parameters to connect to OMS Servers and to log on to a Controller (User ID and Password).
(See Pre-6.2.0.0 CLI Functions for a backward-compatible version of this syntax that can be used for pre-6.2.0.0 CLI functions.)
The following information is provided for each CLI Function:
- Description
- Command line syntax
- Function-specific parameters
- Example
Functions are listed alphabetically, by category, on the following pages:
Command Line Syntax
The following command line syntax is used for issuing the CLI command, uagcmd:
uagcmd function Global parameters function-specific parameter(s)
|
Command Line Entry |
Description |
|---|---|
|
uagcmd |
CLI command that executes all CLI functions. |
|
CLI function that performs a specific action in a Universal Controller. |
|
|
CLI parameters (required and optional) available for all functions. |
|
|
CLI parameters (required and optional) specific to one or more functions. |
For example:
uagcmd ops-task-launch -c config.cfg -x encryptedfile.txt task-type=unix task-name=task01
In this example, the required Global Parameters are contained in the config.cfg configuration file.
Note
For backward-compatibility, you can exclude uagcmd from the command line for all pre-6.2.0.0 CLI functions.
Special Characters Restrictions
The following restrictions apply to the use of special characters in CLI function parameters.
|
Special Characters |
Restrictions |
Examples |
|---|---|---|
|
| |
Can be used only if enclosed in double quotation marks. |
C:\Program Files\Universal\OpsCli\bin>uagcmd.exe ops-task-launch -c c.cfg task-name=A|B |
|
~ |
Cannot be used, even if enclosed in double quotation marks. |
C:\Program Files\Universal\OpsCli\bin>uagcmd.exe ops-task-launch -c c.cfg task-name="A~B" |
|
= |
Cannot be used, even if enclosed in double quotation marks; prevents a CLI function from running. |
C:\Program Files\Universal\OpsCli\bin>uagcmd.exe ops-task-launch -c c.cfg task-name="A=B" |
|
+ |
Can be used with or without double quotation marks. |
C:\Program Files\Universal\OpsCli\bin>uagcmd.exe ops-task-launch -c c.cfg task-name="A+B" |
Restrictions for task-variables= Parameter
None of these special characters identified in Special Characters Restrictions - =, |, +, and ~ - can be use in a task-variables= parameter.
Examples
C:\Program Files\Universal\OpsCli\bin>uagcmd.exe ops-task-launch -c c.cfg task-name=AB task-variables={variable1="V=1" variable2=V2}
Valid format for variables: {variable=value}.
opscmd-complete
C:\Program Files\Universal\OpsCli\bin>uagcmd.exe ops-task-launch -c c.cfg task-name=AB task-variables={variable1="V|1" variable2=V2}
Valid format for variables: {variable=value}.
opscmd-complete
C:\Program Files\Universal\OpsCli\bin>uagcmd.exe ops-task-launch -c c.cfg task-name=AB task-variables={variable1="V+1" variable2=V2}
Valid format for variables: {variable=value}.
opscmd-complete
C:\Program Files\Universal\OpsCli\bin>uagcmd.exe ops-task-launch -c c.cfg task-name=AB task-variables={variable1="V~1" variable2=V2}
Parameter CMDVERB contains malformed name/value pair(s).
opscmd-complete
Pre-6.2.0.0 CLI Functions
For backward-compatibility, you can exclude uagcmd from the command line for all pre-6.2.0.0 CLI functions:
Return Codes
The following table identifies all return codes that can be returned in response to a function:
|
Return Code |
Description |
|---|---|
|
0 |
Completed successfully. |
|
1 |
Configuration error (incorrect command line or configuration file entries). |
|
2 |
Error processing the request. |
Supported Platforms
For all supported platforms, the CLI is included in the Universal Agent 7.2.x package.
|
UNIX |
The CLI functions are installed in the following directory:
Replace |
|---|---|
|
Windows |
The CLI functions are installed in the following directory:
Replace:
Note Do not use fully qualified file names (that is, with the .exe extension) in CLI for Windows parameters; an error will occur. |
|
z/OS |
The CLI is implemented with a single program, |
CLI Login
User Restriction
You can be restricted from logging in to the CLI either of two ways:
- The system level default for CLI access, specified by the System Default Command Line Access Universal Controller system property, has been set to No, and the Command Line Access field in the User Details for your user account is set to -- System Default --."
- The Command Line Access field in the User Details for your user account is set to No, which overrides the System Default Command Line Access value.
If either restriction is in place, the following error message will display when you issue a CLI command:
User <your user name> not permitted to use the command line interface. Please check with your administrator.
To remove the restriction, the system administrator must either:
- Set the System Default Command Line Access property to Yes and set the Command Line access field on the User Definition screen for your user account to -- System Default --.
- Set the Command Line access field on the User Definition screen for your user account to Yes.
Password Expiration
While a password is expired, CLI access will be prohibited until the password has been changed.
Note
Password expiration is not applicable to LDAP authenticated users.
Global Parameters
The CLI provides the following Global parameters for use with any CLI function:
|
Parameter |
Required |
Optional |
|---|---|---|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
| Message Level |
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
| SSL/TLS Cipher List |
|
|
| SSL/TLS 1.3 Cipher Suites |
|
|
| SSL/TLS Implementation |
|
|
| SSL/TLS Minimum Protocol Version |
|
|
| SSL/TLS Maximum Protocol Version |
|
|
|
|
|
|
|
|
|
|
|
|
|
The following information is provided below for each Global parameter:
- Description
- Syntax for specifying the parameter.
- Requirement to use the parameter.
- Default value (if any).
- Example
Specifying Global Parameters
Three methods are available for specifying Global parameters:
- Command line switches
- Configuration file entries
- Environment variables
Note
Each method is available only for some Global parameters; only a command line switch is available for each Global parameter.
CA Certificate List
|
Description |
Trusted CA certificate list in PEM format. DD Name / Dataset Name / HFS File Name for z/OS; file path for other platforms. |
|---|---|
| Platforms | All |
|
Configuration File Entry |
ssl.certstore= |
|
Command Line Switch |
-a |
|
Environment Variable |
n/a |
|
Required |
No |
|
Default |
(none) |
|
Example |
|
Configuration File
|
Description |
Configuration file containing one or more Global parameters. It can include the required User ID, Password, and OMS Servers Global parameters. Note The configuration file syntax is cfggroup.cfgopt=cfgval, where cfggroup is the group to which the option belongs, cfgopt is the option name, and cfgval is the option value. For example:
Note A sample CLI configuration file, cmdtools.props, is created during the installation of the CLI (an optionally installed component of Universal Agent). However, you can create a configuration file with any name; it must exist in the directory from where you are issuing the uagcmd command. |
|---|---|
| Platforms | All |
|
Configuration File Entry |
n/a |
|
Command Line Switch |
-c |
|
Environment Variable |
n/a |
|
Required |
No |
|
Default |
(none) |
|
Example |
|
CRL File
|
Description |
CRL file in PEM format. DD Name / Dataset Name / HFS File Name for z/OS; file path for other platforms. |
|---|---|
| Platforms | All |
|
Configuration File Entry |
ssl.crlfile= |
|
Command Line Switch |
-e |
|
Environment Variable |
n/a |
|
Required |
No |
|
Default |
(none) |
|
Example |
UNIX
Windows
z/OS
|
Encrypted File
|
Description |
Complete path to a file encrypted with the Universal Encrypt utility that contains encrypted user credentials. Note Universal Encrypt is included in every Agent installation package. |
|---|---|
| Platforms | All |
|
Configuration File Entry |
n/a |
|
Command Line Switch |
-x |
|
Environment Variable |
n/a |
|
Required |
No |
|
Default |
(none) |
|
Example |
UNIX
Windows
z/OS
|
Encrypted File Key
|
Description |
Optional key that was passed to the Universal Encrypt utility when the encrypted file specified by -x was created. |
|---|---|
| Platforms | All |
|
Configuration File Entry |
n/a |
|
Command Line Switch |
-k |
|
Environment Variable |
n/a |
|
Required |
No |
|
Default |
(none) |
|
Example |
|
Help
|
Description |
Provides help information for any function. |
|---|---|
| Platforms | All |
|
Configuration File Entry |
n/a |
|
Command Line Switch |
-h | -? |
|
Environment Variable |
n/a |
|
Required |
No |
|
Default |
(none) |
|
Example |
-h |
Note
This parameter is exclusive; do not use it with any other parameter. If you do, only the Help information will be returned.
Message Level
|
Description |
Message level to use. The only supported value is:
|
|---|---|
| Platforms | All |
|
Configuration File Entry |
- |
|
Command Line Switch |
-l value |
|
Environment Variable |
n/a |
|
Required |
No |
|
Default |
Do not use trace. |
|
Example |
-l trace |
OMS NFT
|
Description |
Specification (yes or no) for whether or not to use NFT (network fault tolerance) for OMS. A uagcmd command execution will attempt to connect to each specified OMS Server. If no connection can be made, uagcmd will fail with a non-zero exit code (2). If a network error occurs after a connection to an OMS server is made, the uagcmd will fail with a non-zero exit code (2). |
|---|---|
| Platforms | All |
|
Configuration File Entry |
network.omsnft= |
|
Command Line Switch |
-f |
|
Environment Variable |
OMSNFT |
|
Required |
No |
|
Default |
yes |
|
Example |
|
OMS Servers
|
Description |
Specifies one or more OMS server addresses used for network communication.
If multiple OMS servers are specified, they must be comma-separated. |
|---|---|
| Platforms | All |
|
Configuration File Entry |
network.omsservers= |
|
Command Line Switch |
-m |
|
Environment Variable |
OMSSERVERS |
|
Required |
Yes |
|
Default |
|
|
Example |
network.omsservers=7878@dallas01.acme.com,7878@dallas02.acme.com |
Password
|
Description |
Password that the CLI will use to log into the Controller. Must be a valid password for this user. |
|---|---|
| Platforms | All |
|
Configuration File Entry |
security.password= |
|
Command Line Switch |
-p |
|
Environment Variable |
n/a |
|
Required |
Yes |
|
Default |
(none) |
|
Example |
o |
Queue Name
|
Description |
Controller queue name. Must be default for normal set-up. |
|---|---|
| Platforms | All |
|
Configuration File Entry |
network.core= |
|
Command Line Switch |
-n |
|
Environment Variable |
HUBNAME |
|
Required |
No |
|
Default |
ops.controller.queue |
|
Example |
queue02 |
SSL/TLS
|
Description |
Specification (by its inclusion on the command line) for whether or not to enable SSL/TLS. Valid values for the configuration file entry are:
|
|---|---|
| Platforms | All |
|
Configuration File Entry |
ssl.enable= |
|
Command Line Switch |
-s |
|
Environment Variable |
n/a |
|
Required |
No |
|
Default |
no |
|
Example |
-s |
SSL/TLS Cipher List
|
Description |
Colon-separated or comma-separated list of allowed SSL/TLS ciphers. The ciphers below are valid only for TLS 1.2 and earlier versions. The following ciphers are allowed:
|
|---|---|
| Platforms | All |
|
Configuration File Entry |
ssl.ciphers= |
|
Command Line Switch |
-g value |
|
Environment Variable |
n/a |
|
Required |
No |
|
Default |
no |
|
Example |
-g AES256-SHA,AES128-SHA |
SSL/TLS 1.3 Cipher Suites
|
Description |
Colon-separated or comma-separated list of allowed SSL/TLS 1.3 ciphers. The following ciphers are allowed:
|
|---|---|
| Platforms | All |
|
Configuration File Entry |
ssl.cipher_suites= |
|
Command Line Switch |
-q value |
|
Environment Variable |
n/a |
|
Required |
No |
|
Default |
no |
|
Example |
-g TLS_AES_128_GCM_SHA256,TLS_CHACHA20_POLY1305_SHA256 |
SSL/TLS Implementation
|
Description |
Specification for which SSL/TLS implementation to use on z/OS. Supported values are:
|
|---|---|
| Platforms | z/OS |
|
Configuration File Entry |
ssl.implementation= |
|
Command Line Switch |
-i value |
|
Environment Variable |
n/a |
|
Required |
No |
|
Default |
(none) |
|
Example |
-i openssl |
SSL/TLS Minimum Protocol Version
|
Description |
Restricts the minimal SSL/TLS protocol version allowed in SSL/TLS session negotiation to the value specified. Supported values are :
|
|---|---|
| Platforms | All |
|
Configuration File Entry |
ssl.min_protocol= |
|
Command Line Switch |
-d value |
|
Environment Variable |
n/a |
|
Required |
No |
|
Default |
tls1_2 |
|
Example |
-d tls1_0 |
SSL/TLS Maximum Protocol Version
|
Description |
Restricts the maximum SSL/TLS protocol version allowed in SSL/TLS session negotiation to the value specified. Supported values are :
|
|---|---|
| Platforms | All |
|
Configuration File Entry |
ssl.max_protocol= |
|
Command Line Switch |
-d value |
|
Environment Variable |
n/a |
|
Required |
No |
|
Default |
tls1_2 |
|
Example |
-d tls1_3 |
Timeout
|
Description |
Time (in seconds) that the CLI will wait before it reports an error. |
|---|---|
| Platforms | All |
|
Configuration File Entry |
config.timeout= |
|
Command Line Switch |
-o |
|
Environment Variable |
n/a |
|
Required |
No |
|
Default |
60 |
|
Example |
10 |
User ID
|
Description |
User ID that the CLI will use to log into the Controller. Must be a valid user with the appropriate permissions defined in the Controller database using the Controller Security module. |
|---|---|
| Platforms | All |
|
Configuration File Entry |
security.userid= |
|
Command Line Switch |
-u |
|
Environment Variable |
n/a |
|
Required |
Yes |
|
Default |
(none) |
|
Example |
ops.admin |
Version
|
Description |
Displays version information for the CLI. |
|---|---|
| Platforms | All |
|
Configuration File Entry |
n/a |
|
Command Line Switch |
-v |
|
Environment Variable |
n/a |
|
Required |
No |
|
Default |
(none) |
|
Example |
-v |
Note
If this parameter is specified, all other parameters (except Help) are ignored.
Function-Specific Parameters
Most functions contain one or more required and/or optional parameters that are specific to one or more functions.
Modifying Variables
Some function-specific parameters let you modify variables.
Currently, the CLI only supports the modification of User-Defined Variables: global variables, trigger variables, and task/workflow variables.
Modifying a task variable does not impact any existing task instances of that task. When the next task instance is created from the updated task, the new task instance will use the updated variable.
To modify a variable in a task or workflow, you can create a Set Variable action.
Using the CLI for z/OS
All CLI functions are supported in the z/OS environment. They are managed and executed by the program UAGCMDZ (with alias OPSCMDZ), which may execute as either a command processor or a standard z/OS batch job. UAGCMDZ is installed with the z/OS agent in library SUNVLOAD.
z/OS-Specific Syntax Requirements
The functions and syntax requirements for the z/OS environment are very similar to the other supported platforms with a few exceptions described below.
IBM’s z/OS Language Environment (LE) interprets the first forward slash (/) in a parameter string as a separator between parameters meant for LE and parameters meant for the program being executed. To avoid confusion, parameters which contain a forward slash should be enclosed in double quotes. For instance agent-type=z/OS should be agent-type=”z/OS”.
Command Line Options
When UAGCMDZ is executed as a batch program, command line parameters are specified with the step PARM keyword.
For example:
//STEP01 EXEC PGM=UAGCMDZ, // PARM='ops-agent-status -c dd:CMDOPTS agent-type=windows'
Syntax for Options That Accept File Names: -a, -c, -e, and -x
If you use the -a, -c, -e, and -x command line switches for specifying a file on the command line, you must use one of the following formats for the file name.
For example, for the -c (Configuration File) command line switch:
|
Format |
Syntax |
Description |
|---|---|---|
|
DD Name |
|
|
|
Dataset Name |
|
|
| HFS File Name | -c “/path/to/file/fname” |
A fully-qualified path to a file located on the hierarchical z/OS Unix File System, where |
Line Numbers in Configuration File
Do not place line numbers in columns 73-80. The entire 80-byte record is read and processed as input.
Methods for Issuing CLI Functions in z/OS
Three methods are available for running UAGCMDZ and executing CLI functions:
In each example where data sets are specified, we use:
|
UNV.SUNVLOAD |
Library containing the CLI programs UAGCMDZ (and OPSCMDZ alias). |
|---|---|
|
USER.PARM |
Data set containing command options. |
|
USER.REXX |
Data set containing user REXX EXECs. |
Running OCLI Functions in a Batch Job
The CLI program UAGCMDZ executes a single function as a JCL batch job step. If multiple functions are to be executed, run each one as an individual job step.
The following example illustrates running UAGCMDZ as a batch job to request the status of all Windows Agents.
//jobname JOB (acctg-info),'your name',MSGCLASS=X,MSGLEVEL=(1,1), // CLASS=A,NOTIFY=&SYSUID //* //STEP01 EXEC PGM=UAGCMDZ, // PARM='ops-agent-status -c dd:CMDOPTS agent-type=windows' //STEPLIB DD DISP=SHR,DSN=UNV.SUNVLOAD //SYSPRINT DD SYSOUT=* //SYSOUT DD SYSOUT=* //CMDOPTS DD DSN=USER.PARM(CMDOPTS),DISP=SHR //CEEDUMP DD SYSOUT=*
In this example:
The step PARM value specifies the CLI function and its options.
The job step can include only one function.
The STEPLIB points to the z/OS Agent load library.
The output will be in SYSPRINT.
CMDOPTS is a DDNAME that references the location of the function parameters.
Issuing CLI Functions under TSO
You can also issue CLI functions under a TSO session.
The sample command string below shows a CLI function issued from an ISPF Command Shell prompt:
Enter TSO or Workstation functions below: ===> uagcmdz ops-agent-status -c "//'USER.PARM(CMDOPTS)'" agent-type=windows
This function will return data similar to the sample below:
Agentname AgentType Status agent-sys00101 Windows Active agent-sys00201 Windows Offline opscmd-complete
Issuing CLI Functions as a Batch TSO
The following two examples show how to issue a CLI function in a batch TSO.
Example One
//CMDZBAT JOB (acctg-info),'your name',MSGCLASS=X,MSGLEVEL=(1,1), // CLASS=A,NOTIFY=&SYSUID,TIME=5 //* //STEP01 EXEC PGM=IKJEFT01,DYNAMNBR=200,REGION=40M //STEPLIB DD DISP=SHR,DSN=UNV.SUNVLOAD //SYSPRINT DD SYSOUT=* //SYSOUT DD SYSOUT=* //SYSTSPRT DD SYSOUT=* //CMDOPTS DD DSN=USER.PARM(CMDOPTS),DISP=SHR //SYSTSIN DD * uagcmdz ops-agent-status -c dd:CMDOPTS agent-type=windows /*
Output will be in SYSTSPRT.
Example Two
//REXXAGNT JOB (acctg-info),'your name',MSGCLASS=X,MSGLEVEL=(1,1), // CLASS=A,NOTIFY=&SYSUID,TIME=5 //* //STEP01 EXEC PGM=IKJEFT01,DYNAMNBR=200,REGION=40M //STEPLIB DD DISP=SHR,DSN=UNV.SUNVLOAD //SYSEXEC DD DSN=USER.REXX,DISP=SHR //SYSPRINT DD SYSOUT=* //SYSTSPRT DD SYSOUT=* //CMDOPTS DD DSN=USER.PARM(CMDOPTS),DISP=SHR //SYSTSIN DD * %OUTTRAP1 /*
The following REXX EXEC must be located in USER.REXX(OUTTRAP1):
/**************************** REXX *********************************/
/* Using OUTTRAP to */
/* (1) Obtain z/OS agent status */
/* (2) Test status from the response */
/* (3) Launch a task if the agent status is Active */
/*******************************************************************/
x = OUTTRAP('OPS.')
uagcmdz "ops-agent-status -c dd:CMDOPTS agent-type=""z/OS"""
SAY 'RC is:' RC
SAY OPS.0 'records were read.'
launch = 'NO'
DO i = 1 to OPS.0 WHILE launch = 'NO'
IF SUBSTR(OPS.i,61,6) = 'Active' THEN
DO
launch = 'YES'
uagcmdz "ops-task-launch -c dd:CMDOPTS task-name=DUMPT"
END
END
DO i = 1 to OPS.0
SAY OPS.i
END
y = OUTTRAP('OFF')