Dovetailed Technologies

3. Co:Z Launcher Configuration

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

3.1 Co:Z Launcher Properties

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

Required Properties

Each installation is required to customize the following properties:

server-path {<COZ_INST>/cozserver}

The absolute path on the server of the CozServer executable, where <COZ_INST> is the directory where Co:Z Toolkit is installed.

server-ports[-sysid] {none}

No longer a required option as of release 4.0.0.

Optional Properties

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 for a Co:Z Launcher release older than 4.0.0 or when option ssh-forward-dynamic-port is required to be false. When 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 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.

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

  • IBM Ported Tools OpenSSH v1.3 / z/OS V2R2 OpenSSH or higher is required

  • The target ssh server must support dynamic reverse port forwarding (e.g. OpenSSH version 5.3 or later)

This option was introduced in release 3.6.0 with a default value of false. The default was changed to true in release 4.0.0 (but note that the default remains false if the server-ports property is set). The intent of this change is to enable an ephemeral port to be used on z/OS by default, eliminating the need for reserved port ranges. The server-port option is no longer a required property as of release 4.0.0.

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

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 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. 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. 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:port on 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:port on 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 PATH environment variable will only contain /bin and other variables as determined by the installations /etc/init.options file. Therefore, a fully qualified command path name is often required, and a shell script may wish to "dot in" /etc/profile and ~/.profile if appropriate.

3.2 Configuration Best Practices

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)

The preferred configuration for multiple concurrent jobs is to use tunnelling with dynamic port forwarding.

When tunneling

When using tunneling, the preferred configuration is to use dynamic port forwarding when supported. For a tunneled configuration, use the following settings (default in COZCFGD for release 4.0.0 and later):

ssh-tunnel=true
ssh-forward-dynamic-port=true
#server-ports=

If not using IBM Ported Tools 1.3 (or later) or if dynamic port forwarding is not supported on the target system, override the defaults in a job specific COZCFG:

ssh-forward-dynamic-port=false
server-ports=8040-8059

When not tunneling

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

3.3 Console communication

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]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 IEE342I MODIFY REJECTED-TASK BUSY (the command will still be processed).

Commands directed to the CoZAgent process

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

Examples:

F MYJOB,APPL=/CMD PS -E_AF
F MYJOB,APPL=INPUT TO REMOTE PROGRAM
F MYJOB,APPL=/QUIESCE
      
Copyright© 2009-2017 Dovetailed Technologies, LLC. All rights reserved.
Co:Z® is a registered trademark of Dovetailed Technologies, LLC.