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.
![[Note]](images/note.gif) | Note |
|---|---|
If duplicate property names are supplied, only the final value is used. To specify multi-line values for a property, place a backslash (\) continuation character on the line(s) to be continued. |
Each installation is required to customize the following property:
- server-path {
<COZ_INST>/bin/cozserver} The absolute path on z/OS of the
cozserverexecutable, where <COZ_INST> is the directory where Co:Z Toolkit for z/OS is installed.
The following properties may be overidden in COZCFGD or by individual job step
- server-ports[-sysid] {
none} The range of ports reserved for communication between CoZServer and the target system. This option should only be used when option ssh-forward-dynamic-port is required to be
false. If specified, each invocation of a Co:Z Launcher 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 Co:Z Launcher batch job. If ssh-tunnel=true, then the target servers must also ensure that these port are available (unless ssh-forward-dynamic-port=true). 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 Co:Z Launcher 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- 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 z/OS 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 remote port forwarding. If false, direct socket connections are made to the server.
- ssh-tunnel-loopback {
legacy} Specifies which loopback adapter (IPv4 or IPv6) to use over ssh via remote forwarding (when ssh-tunnel=true). The following values may be set:
first-- will cause CoZ to match OpenSSH. This will generally result in the desired behavior, and is recommended.4 | 6-- will force the tunnelled connection to be on either IPv4 or IPv6 respectively. Requires remote version of OpenSSH 6.7 or later.legacy-- retains original behavior, which will specify IPv4 only. If the remote OpenSSH picks IPv6, the connection will fail.
- ssh-forward-dynamic-port {
true} If true, allows the target ssh server to dynamically assign the target port. In order to enable this option:
The ssh-tunnel option must be set to true
The target ssh server must support dynamic reverse port forwarding (e.g. OpenSSH version 5.3 or later)
If false, the target port is set matching the selected server-port. Setting the target port to the server-port value can cause collisions when multiple Co:Z Launcher jobs from different LPARS are running concurrently to the same target host. Enabling the ssh-forward-dynamic-port option prevents these collisions.
- ssh-forward-dynamic-port-wait {
30} The number of seconds the Launcher will wait for the target system to report its dynamic port.
- 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 absolute path on the target system of the cozagent executable. Note that the Co:Z Target System Toolkit source distributions will by default install the Co:Z executables in directory
/opt/dovetail/coz/bin. This property need only be set if you install in a different directory- 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.3, “Console communication” for a list of available commands.-n-- run the target-command without a shell.
- 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 hostname (or address) of the CoZServer running on z/OS. If ssh-tunnel=false, the target program will connect to CoZServer on z/OS at this address. If ssh-tunnel=true, this value is ignored.
- server-ip-stack[-sysid] {
0.0.0.0 (all addresses)} The IP address on z/OS that 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 on z/OS. 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. See Appendix Co:Z Environment Variables for a list of environment variables.
- target-env-MY_VAR {
none} Customized target environment variables that will be set prior to launching the target program on the remote system. 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 on the remote system. 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 may alternatively be supplied in the form
user@host:porton the COZPROC ARGS= parameter.- target-port {
none} The port of the target machine. This value 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 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.
Data transferred between z/OS and the target remote system can be configured in one of two ways:
tunnelled (and encrypted) over ssh via reverse port forwarding
direct socket connection (better throughput with lower overhead, but unencrypted)
When using tunneling, the preferred configuration is to use dynamic port forwarding if supported. For a tunneled configuration, use the following settings:
ssh-tunnel=true ssh-forward-dynamic-port=true
If dynamic port forwarding is not supported on the target system, override the defaults in a job specific COZCFG:
ssh-tunnel=true ssh-forward-dynamic-port=false server-ports=8040-8059
When using a direct socket connection and no server-ports definition,
a server ephemeral port will be used which may cause trouble with existing firewall policies.
Therefore, it is recommended that a server-ports range be defined so that network
administration has visibility to the ports being used by Co:Z. The following settings are recommended
(note that the ssh-forward-dynamic-port option will be ignored, as it only takes effect
if ssh-tunnel=true):
ssh-tunnel=false server-ports=8040-8059
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 |
|---|---|
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
