This chapter explains how to configure the z/OS and target server components of Co:Z.
For questions, please visit the Dovetailed Technologies z/OS Forum
.Co:Z programs are initiated via JCL job steps that execute the Co:Z Launcher
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:
/usr/lpp/coz/cozserver}The absolute path on the server of the CozServer executable.
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
/bin/ssh}Specifies the location of the z/OS ssh client executable.
none}Additional options to be supplied to z/OS ssh command.
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.
/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/bin by default.
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.
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)
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.
0.0.0.0 (all addresses)}The IP address the CoZServer will accept connections on. If ssh-tunnel=true, this value is ignored.
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.
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.
none}The target program to be run by CoZAgent. If not supplied, the target user's default shell will be executed.
none}The hostname or IP address of the target machine. This value and target-user
may alternatively be supplied in the form user@host:port on the COZPROC
ARGS= parameter.
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:port
on the COZPROC ARGS= parameter.
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.
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.
SIGKILL}Issues the specified signal to the target program.
Issues command as a system() call. Typical commands include
process status commands such as ps -eaf. Any resulting stdout data
is written either to the MVS console or the STDOUT DD, depending on the value of the
agent-output-wto property, described above.
Any console command not prefixed with a slash (/) as above is sent directly
to the target program for processing.