The Co:Z Launcher is initiated in batch via JCL job steps that execute the
COZLNCH load module. The z/OS installation package includes a sample stored procedure
for invoking the launcher COZPROC. The launcher is configured through
a set of customizable properties, which are described below (default values are
shown in braces).
Some server properties (server-ports, server-ip-stack
and server-host) may be optionally suffixed with a z/OS sysid. In this
case, these properties will apply only to a specific z/OS system. This allows for a single
COZCFG member to be used for all of the candidate z/OS systems in an installation.
The PDS member COZCFGD can be customized for each installation to
provide system level defaults for many of these properties.
Each installation is required to customize the following properties:
- server-path {
/usr/lpp/coz/cozserver} The absolute path on the server of the CozServer executable.
- server-ports[-sysid] {
none} The range of ports reserved for communication between CoZServer and the target system. Each invocation of a CoZLauncher batch job will find one available port in this range, and establish a socket listener.
If ssh-tunnel=true (the default), an available port in this range will be bound to the z/OS loopback adapter (127.0.0.1), and the target program on the target server will connect to this port via the tunnel established by ssh.
If ssh-tunnel=false, an available port in this range will be bound to any stack on z/OS (this can be changed using the server-ip-stack property), and the target program on the target server will connect to this port directly over the network.
Installations must reserve a port range on z/OS large enough for each concurrent CoZLauncher batch job. If ssh-tunnel=true, then the target servers must also ensure that these port are available. If multiple z/OS systems share the same target machines, each z/OS system should reserve its own port range.
The following example sets up a 20 port pool for use by any CoZLauncher instance.
server-ports=8040-8059
The following example sets up separate 20 port pools for three z/OS systems running in an installation (and sharing the same COZCFGD member). If ssh-tunnel=true (the default), then each target system must make 8040-8099 available.
server-ports-SYSA=8040-8059 server-ports-SYSB=8060-8079 server-ports-SYSC=8080-8099
The following properties may be overidden in COZCFGD or by individual job step
- ssh-le-options {
none} Custom Language Environment (LE) options to set for the ssh client process created by the Launcher. No options are set by default, but see the COZCFGD sample for the recommended options to work around a problem that causes out-of-memory conditions in Ported Tools OpenSSH. See IBM APAR OA34819.
- ssh-options {
none} Additional options to be supplied to z/OS ssh command.
- ssh-path {
/bin/ssh} Specifies the location of the z/OS ssh client executable.
- ssh-tunnel {
true} If true, target program IO requests (via fromdsn and todsn) are tunnelled over ssh via reverse port forwarding. If false, direct socket connects are made to the server.
- saf-cert {
none} Specifies that the user's RACF Digital Certificate should be used for client authentication. The value supplied for this property is in the form KEYRING[:LABEL]. If LABEL is omitted, the keyring's default label will be used. Examples:
saf-cert=MY-RING saf-cert=MY-RING:MY-CERT- agent-path {
/opt/dovetail/coz/bin/cozagent} The executable path on the target of the CozAgent executable. Note that the client make install target places the Co:Z executables at
/opt/dovetail/coz/binby default.- agent-options {
none} Command line options to CoZAgent. These include:
-c-- allow the operator to communicate with the agent to control the target program. See Section 3.2, “Console communication” for a list of available commands.
- agent-output-wto {
false} If true, messages written by the CoZAgent are written to the operator console. If false, they are written to the launcher's stdout (DD://SYSPRINT)
- server-host[-sysid] {
gethostname()} The external address of the CoZServer running on z/OS. If ssh-tunnel=false, the target program will connect to this address. If ssh-tunnel=true, this value is ignored.
- server-ip-stack[-sysid] {
0.0.0.0 (all addresses)} The IP address the CoZServer will accept connections on. If ssh-tunnel=true, this value is ignored.
- server-env-MY_VAR {
none} Customized server environment variables that will be set prior to launching the CoZServer. MY_VAR should be replaced by the name of the environment variable to be set. These environment variables will also be adopted by the Launcher itself.
- target-env-MY_VAR {
none} Customized target environment variables that will be set prior to launching the target program. MY_VAR should be replaced by the name of the environment variable to be set.
- target-command {
none} The target program to be run by CoZAgent. If not supplied, the target user's default shell will be executed.
- target-host {
none} The hostname or IP address of the target machine. This value and target-user may alternatively be supplied in the form
user@host:porton the COZPROC ARGS= parameter.- target-user {
none} The userid that the target program runs under on the target machine. This value and target-host may alternatively be supplied in the form
user@host:porton the COZPROC ARGS= parameter.- properties-exit {
none} Specifies the executable Unix command and arguments that are used to run a Unix program or shell script that may write additional configuraton properties to its stdout. Output lines from this program will be used as additional configuration properties as if they were specified at the end of the DD:COZCFG file. A practical use for this feature might be to dynamically determine the target-host property from a list of candidate servers.
The command string specified is run using /bin/sh -c "command args". Note that the Co:Z Launcher batch utility does not run a "login" shell, so that the
PATHenvironment variable will only contain/binand other variables as determined by the installations/etc/init.optionsfile. Therefore, a fully qualified command path name is often required, and a shell script may wish to "dot in"/etc/profileand~/.profileif appropriate.
If the CoZAgent is started with the console communication switch (-c), the MVS system console can be used to communicate with the target system. This interaction can occur once the target program has completed its processing of the STDIN DD, if it exists. In this case, the target program will not receive an EOF from stdin until a /QUIESCE command is sent from the console. The available commands are described below.
If the CoZAgent is started without the -c switch, no console communication is permitted. When the target program finishes reading STDIN, it will receive an EOF as in normal processing.
Console commands are sent to the remote agent by using the MVS MODIFY (F)
and STOP (P) commands. The modify string must be prefixed by keyword APPL=.
If the text supplied on the modify command is surrounded by single quote (') characters, it is passed unmodified to the console. Note that in some cases ISPF panels will force entered text to uppercase. If so, eliminate the single quote characters and the entire command will be folded to lower case by Co:Z, which is generally more compatible with remote Unix systems. In this situation, upper case characters may be specified by prefixing each character with an underscore ('_').
The MVS console supresses certain characters, such as `,\,~,^,[,],{,}. These
characters should not be specified.
![[Note]](images/note.gif) | Note |
|---|---|
Because of the way z/OS Unix names child processes, your job/task name should consist
of 7 characters or less (or use an identifier) if you wish to use console commands.
If you use an 8 character jobname, you will see the following message
|
- /QUIESCE
Sends an EOF to the target program's stdin. This will allow the target program that waits for interactive stdin commands to perform its normal completion processing.
- /KILL [signal_level] {
SIGKILL} Issues the specified signal to the target program.
- /CMD <command>
Issues
commandas a system() call. Typical commands include process status commands such asps -eaf. Any resulting stdout data is written either to the MVS console or the STDOUT DD, depending on the value of theagent-output-wtoproperty, described above.
Any console command not prefixed with a slash (/) as above is sent directly
to the target program for processing.
Examples:
F MYJOB,APPL=/CMD PS -E_AF
F MYJOB,APPL=INPUT TO REMOTE PROGRAM
F MYJOB,APPL=/QUIESCE