Versions Compared

Old Version 2

changes.mady.by.user Stonebranch

Saved on

compared with

New Version Current

changes.mady.by.user Stonebranch

Saved on

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.


Panel
Table of Contents
maxlevel2

Anchor
Introduction
Introduction

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.

Anchor
Functions
Functions

CLI Functions

CLI functions perform specific actions in a Universal Controller.

...

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.)

...

Agent Functions

Bundle Functions

Import and Export Functions

OMS Server Functions

Password Functions

Resource Functions

Task Functions

Tasks in Workflow Functions

Trigger Functions

Variable Functions

Anchor
Command Line Syntax
Command Line Syntax

Command Line Syntax

The following command line syntax is used for issuing the CLI command, uagcmd:
 

...

Command Line Entry

Description

uagcmd

CLI command that executes all CLI functions.

function

CLI function that performs a specific action in a Universal Controller.

Global parameters

CLI parameters (required and optional) available for all functions.

function-specific parameter(s)

CLI parameters (required and optional) specific to one or more functions.

...

Panel
uagcmd ops-task-launch -c config.cfg -x encryptedfile.txt task-type=unix task-name=task01

...

Note
titleNote

For backward-compatibility, you can exclude uagcmd from the command line for all pre-6.2.0.0 CLI functions.

Anchor
Special Characters Restrictions
Special Characters Restrictions

Special Characters Restrictions

The following restrictions apply to the use of special characters in CLI function parameters.

...

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

Anchor
Pre-6.2.0.0 CLI Functions
Pre-6.2.0.0 CLI Functions

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:
 

Agent Functions

Import and Export Functions

Password Functions

Resource Functions

Task Functions

Trigger Functions

Variable Functions

Anchor
Return Codes
Return Codes

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.

Anchor
Supported Platforms
Supported Platforms

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:

  • /CLI_HOME/bin

Replace CLI_HOME with the directory in which the Agent components are installed.

Windows

The CLI functions are installed in the following directory:

  • DRIVE:\CLI_HOME\bin

Replace:

  • DRIVE with the drive they are installed on. Add the appropriate directory for your O/S to your PATH environment variable in order to execute the functions without specifying their full path name.
  • CLI_HOME with the directory in which the Agent components are installed.
Note
titleNote

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, UAGCMDZ. UAGCMDZ (with alias OPSCMDZ) is installed in the SUNVLOAD library as part of the Universal Agent for z/OS Installation package.
 
See Using the CLI for z/OS for detailed information on using the CLI in a z/OS environment.

Anchor
CLI Login
CLI Login

CLI Login

Anchor
User Restriction
User Restriction

User Restriction

You can be restricted from logging in to the CLI either of two ways:

...

Note
titleNote

Password expiration is not applicable to LDAP authenticated users.

Anchor
Global Parameters
Global Parameters

Global Parameters

The CLI provides the following Global parameters for use with any CLI function:

Parameter

Required

Optional

CA Certificate List


(tick)

Configuration File


(tick)

CRL File


(tick)

Encrypted File


(tick)

Encrypted File Key


(tick)

Help


(tick)

Message Level
(tick)

OMS NFT


(tick)

OMS Servers

(tick)


Password

(tick)


Queue Name


(tick)

SSL/TLS


(tick)

SSL/TLS Cipher List
(tick)
SSL/TLS 1.3 Cipher Suites
(tick)
SSL/TLS Implementation
(tick)
SSL/TLS Minimum Protocol Version
(tick)
SSL/TLS Maximum Protocol Version
(tick)

Timeout


(tick)

User ID

(tick)


Version


(tick)

The following information is provided below for each Global parameter:

Anchor
Specifying Global Parameters
Specifying Global Parameters

Specifying Global Parameters

Three methods are available for specifying Global parameters:

  1. Command line switches
  2. Configuration file entries
  3. Environment variables
Note
titleNote

Each method is available only for some Global parameters; only a command line switch is available for each Global parameter.

Anchor
CA Certificate List
CA Certificate List

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.

PlatformsAll

Configuration File Entry

ssl.certstore=

Command Line Switch

-a

Environment Variable

n/a

Required

No

Default

(none)

Example

  • UNIX
    • /opt/cert/ca.pem
  • Windows
    • c:\cert\ca.pem
  • z/OS:
    • -a dd:CACERTS
    • -a CACERTS
    • -a “//’CACERTS’”
    • -a “//’CACERTS(mbr)’”
    • -a “/path/to/file/CACERTS”

...

Description

Configuration file containing one or more Global parameters. It can include the required User ID, Password, and OMS Servers Global parameters.

Note
titleNote

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:

security.userid=ops.admin
security.password=abc123
network.omsservers=7878@dallas01.acme.com,7878@dallas02.acme.com
network.omsnft=yes
config.timeout=60


You also can specify individual Global parameters (required and optional) on the command line.


Note
titleNote

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.


PlatformsAll

Configuration File Entry

n/a

Command Line Switch

-c

Environment Variable

n/a

Required

No

Default

(none)

Example

  • UNIX
    • /opt/cfgopt/cfgval.pem
  • Windows
    • c:\cfgopt\cfgval.pem
  • z/OS:
    • -c dd:cfgval
    • -c cfgval
    • -c “//’cfgval’”
    • -c “//’cfgval(mbr)’”
    • -c “/path/to/file/cfgval”

Anchor
CRL File
CRL File

CRL File

Description

CRL file in PEM format. DD Name / Dataset Name / HFS File Name for z/OS; file path for other platforms.

PlatformsAll

Configuration File Entry

ssl.crlfile=

Command Line Switch

-e

Environment Variable

n/a

Required

No

Default

(none)

Example

UNIX

  • /opt/cert/crl.pem

Windows

  • c:\cert\crl.pem

z/OS

  • -e dd:CRL
  • -e CRL
  • -e “//’CRL’”
  • -e “//’CRL(mbr)’”
  • -e “/path/to/file/CRL”

Anchor
Encrypted File
Encrypted File

Encrypted File

Description

Complete path to a file encrypted with the Universal Encrypt utility that contains encrypted user credentials.
 
This file can be used to store encrypted Controller credentials that would otherwise be specified using the User ID or Password parameters. One or both of these parameters can be encrypted and stored in this file. Any other parameters stored in the encrypted file are ignored.
 
Any values specified by User ID or Password on the command line and/or in the Configuration File will override values stored in this file.
 

Note
titleNote

Universal Encrypt is included in every Agent installation package.


PlatformsAll

Configuration File Entry

n/a

Command Line Switch

-x

Environment Variable

n/a

Required

No

Default

(none)

Example

UNIX

  • /opt/encfile/fname.enc

Windows

  • c:\encfile\fname.enc

z/OS

  • -x dd:fname
  • -x fname
  • -x “//’fname’”
  • -x “//’fname(mbr)’”
  • -x “/path/to/encfile/fname”

Anchor
Encrypted File Key
Encrypted File Key

Encrypted File Key

Description

Optional key that was passed to the Universal Encrypt utility when the encrypted file specified by -x was created.

PlatformsAll

Configuration File Entry

n/a

Command Line Switch

-k

Environment Variable

n/a

Required

No

Default

(none)

Example


Anchor
Help
Help

Help

Description

Provides help information for any function.

PlatformsAll

Configuration File Entry

n/a

Command Line Switch

-h | -?

Environment Variable

n/a

Required

No

Default

(none)

Example

-h

...

Note
titleNote

This parameter is exclusive; do not use it with any other parameter. If you do, only the Help information will be returned.

Anchor
Message Level
Message Level

Message Level

Description

Message level to use.

The only supported value is:

  • trace (which turns on debug messages)
PlatformsAll

Configuration File Entry

-

Command Line Switch

-l value

Environment Variable

n/a

Required

No

Default

Do not use trace.

Example

-l trace

Anchor
OMS NFT
OMS NFT

OMS NFT

Description

Specification (yes or no) for whether or not to use NFT (network fault tolerance) for OMS.
 
If NFT is not used:

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).

PlatformsAll

Configuration File Entry

network.omsnft=

Command Line Switch

-f

Environment Variable

OMSNFT

Required

No

Default

yes

Example


Anchor
OMS Servers
OMS Servers

OMS Servers

Description

Specifies one or more OMS server addresses used for network communication.
 
The syntax of the value is PORT@HOST[,PORT@HOST...], where:

  • PORT is the TCP port on which the OMS server is listening. The OMS default port is 7878.
  • HOST is the host name or IP address of the OMS server.

If multiple OMS servers are specified, they must be comma-separated.

PlatformsAll

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

Anchor
Password
Password

Password

Description

Password that the CLI will use to log into the Controller. Must be a valid password for this user.

PlatformsAll

Configuration File Entry

security.password=

Command Line Switch

-p

Environment Variable

n/a

Required

Yes

Default

(none)

Example

o

Anchor
Queue Name
Queue Name

Queue Name

Description

Controller queue name. Must be default for normal set-up.

PlatformsAll

Configuration File Entry

network.core=

Command Line Switch

-n

Environment Variable

HUBNAME

Required

No

Default

ops.controller.queue

Example

queue02

Anchor
SSL TLS
SSL TLS

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:

  • yes
  • no
PlatformsAll

Configuration File Entry

ssl.enable=

Command Line Switch

-s

Environment Variable

n/a

Required

No

Default

no

Example

-s

Anchor
SSL TLS Cipher List
SSL TLS Cipher List

SSL/TLS Cipher List

Description

Colon-separated or comma-separated list of allowed SSL/TLS ciphers.

Note

The ciphers below are valid only for TLS 1.2 and earlier versions.
See the ssl.cipher_suites option for configuring TLS 1.3 specific
ciphers.

The following ciphers are allowed:

  • AES256-GCM-SHA384
  • AES256-SHA
  • AES128-GCM-SHA256
  • AES128-SHA
  • RC4-SHA
  • RC4-MD5
  • DES-CBC3-SHA
  • NULL-SHA
  • NULL-SHA256
  • NULL-MD5
PlatformsAll

Configuration File Entry

ssl.ciphers=

Command Line Switch

-g value

Environment Variable

n/a

Required

No

Default

no

Example

-g AES256-SHA,AES128-SHA

Anchor
SSL TLS 1.3 Cipher Suites
SSL TLS 1.3 Cipher Suites

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:

  • TLS_AES_256_GCM_SHA384
  • TLS_CHACHA20_POLY1305_SHA256
  • TLS_AES_128_GCM_SHA256
PlatformsAll

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

Anchor
SSL TLS Implementation
SSL TLS Implementation

SSL/TLS Implementation

Description

Specification for which SSL/TLS implementation to use on z/OS.

Supported values are:

  • openssl
  • system
Platformsz/OS

Configuration File Entry

ssl.implementation=

Command Line Switch

-i value

Environment Variable

n/a

Required

No

Default

(none)

Example

-i openssl

Anchor
SSL TLS Minimum Protocol Version
SSL TLS Minimum Protocol Version

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 :

  • tls1_0
  • tls1_2
  • tls1_3
PlatformsAll

Configuration File Entry

ssl.min_protocol=

Command Line Switch

-d value

Environment Variable

n/a

Required

No

Default

tls1_2

Example

-d tls1_0

Anchor
SSL TLS Maximum Protocol Version
SSL TLS Maximum Protocol Version

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 :

  • tls1_2
  • tls1_3
PlatformsAll

Configuration File Entry

ssl.max_protocol=

Command Line Switch

-d value

Environment Variable

n/a

Required

No

Default

tls1_2

Example

-d tls1_3

Anchor
Timeout
Timeout

Timeout

Description

Time (in seconds) that the CLI will wait before it reports an error.

PlatformsAll

Configuration File Entry

config.timeout=

Command Line Switch

-o

Environment Variable

n/a

Required

No

Default

60

Example

10

Anchor
User ID
User ID

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.

PlatformsAll

Configuration File Entry

security.userid=

Command Line Switch

-u

Environment Variable

n/a

Required

Yes

Default

(none)

Example

ops.admin

Anchor
Version
Version

Version

Description

Displays version information for the CLI.

PlatformsAll

Configuration File Entry

n/a

Command Line Switch

-v

Environment Variable

n/a

Required

No

Default

(none)

Example

-v

...

Note
titleNote

If this parameter is specified, all other parameters (except Help) are ignored.

Anchor
Function-Specific Parameters
Function-Specific Parameters

Function-Specific Parameters

Most functions contain one or more required and/or optional parameters that are specific to one or more functions.

Anchor
Modifying Variables
Modifying Variables

Modifying Variables

Some function-specific parameters let you modify variables.

...

To modify a variable in a task or workflow, you can create a Set Variable action.

Anchor
Using the CLI for z/OS
Using the CLI for z/OS

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.

...

The functions and syntax requirements for the z/OS environment are very similar to the other supported platforms with a few exceptions described below.

Note

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.

...

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.

Anchor
Running CLI Functions in a Batch Job
Running CLI Functions in a Batch Job

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.

...

CMDOPTS is a DDNAME that references the location of the function parameters.

Anchor
Issuing CLI Functions under TSO
Issuing CLI Functions under TSO

Issuing CLI Functions under TSO

You can also issue CLI functions under a TSO session.

...

Panel
 Agentname                       AgentType     Status
 agent-sys00101                  Windows       Active
 agent-sys00201                  Windows       Offline
 opscmd-complete

Anchor
Issuing CLI Functions as a Batch TSO
Issuing CLI Functions as a Batch TSO

Issuing CLI Functions as a Batch TSO

The following two examples show how to issue a CLI function in a batch TSO.

...