contact us

Co:Z Toolkit User's Guide

Prev V 1.3 [PDF] Next
1. Introduction Contents  3. Configuration

2. Installation

This chapter explains how to install the z/OS and target server components of the Co:Z Toolkit.

For questions, please visit the Dovetailed Technologies Co:Z Forum

2.1 Installation Overview

Follow these steps to install Co:Z in your environment. If you wish to use the Dataset Pipes commands as standalone commands from a remote system, you will need to add a subsystem to your z/OS OpenSSH configuration. This is discussed in the z/OS customization step below.

  1. Verify system requirements: Section 1.4, “Supported Environments”.

  2. Install Co:Z z/OS software: Section 2.2, “z/OS Installation”.

  3. Customize z/OS environment: Section 2.3, “z/OS Customization”.

  4. Install Co:Z on your selected target servers:

    1. Windows Target Host Installation: Section 2.4, “Windows Target System Installation”.

    2. Unix/Linux/Posix Target Host Installation: Section 2.5, “Unix/Linux/Posix Target System Installation”.

2.2 z/OS Installation

  1. Download the coz z/OS self-extracting installer (.bin) file.

  2. Upload coz-vv.rr-m.bin file (in binary) to the z/OS HFS or zFS file system.

  3. From a z/OS Unix shell, run the self-extracting installer. For example:

    $ chmod 755 coz-vv.rr-m.bin
$ ./coz-vv.rr-m.bin
(the Co:Z Toolkit for z/OS license agreement)
...
Do you agree to the above license terms? [yes or no]
yes
Enter home install directory [/usr/lpp/coz] :
(Enter)
/usr/lpp/coz is not an existing directory, create it? [y/n] :
y
Enter new or existing target PDSE load module library name [SYS1.COZ.LOADLIB]:
(Enter)
The PDSE load module library 'SYS1.COZ.LOADLIB'does not exist, create it? [y]:
y
Enter new or existing PDS for Co:Z Sample JCL and PROCs [SYS1.COZ.SAMPJCL]:
(Enter)
The PDS 'SYS1.COZ.SAMPJCL' does not exist, create it? [y]:
y
Enter PATH directory in which to create fromdsn, todosn, and cozserver symlinks 
    or 'none' [/usr/local/bin]:
(Enter)
You should update user profiles so that MANPATH contains: /usr/lpp/coz/doc/man

*** Co:Z Installation complete  ****
(see README and LICENSE in install root directory for more information)

2.3 z/OS Customization

  1. Install and configure IBM Ported Tools for z/OS (SSH) per the IBM documentation.

    1. If possible, configure z/OS ssh to use /dev/random. This can significantly decrease startup times for the z/OS ssh client. See the "Trouble Shooting" chapter in the IBM z/OS Ported Tools manual for more information.

    2. (Optional) To run Dataset Pipes commands initiated by a remote client, a subsystem must be configured in your z/OS OpenSSH server. [1] This is done by updating the sshd_config file, typically located at /etc/ssh/sshd_config. It is sometimes convenient to set up a test OpenSSH server where this subsystem can be easily added. to do this see: Appendix B, Setting up a test OpenSSH system on z/OS.

      1. Find the line "Subsystem" which defines the sftp subsystem

      2. Add a new line after this line, as follows: 

        Subsystem dspipes /usr/lpp/coz/bin/dspipes

        (where /usr/lpp/coz is the directory where Co:Z Toolkit is installed).

  2. Customize the COZPROC sample JCL PROC, per the included instructions.

  3. Customze the COZCFGD member, containing installation defaults, per the included instructions.

  4. Generate SSH public/private keypairs:

    This step should be performed on z/OS from the (each) userid that will be used to execute the Co:Z Batch jobs. Note: a z/OS shell invoked under telnet, rlogin, or ssh must be used for key generation. Don't attempt to do this under an OMVS shell, since the "ssh" commands are generally not supported under OMVS. 

    $ mkdir ~/.ssh
$ chmod 700 ~/.ssh
$ ssh-keygen -t dsa
Generating public/private dsa key pair.
Enter file in which to save the key (/home/<userid>/.ssh/id_dsa): <enter>
Enter passphrase (empty for no passphrase): <enter>
Enter same passphrase again: <enter>
Your identification has been saved in /home/<userid>/.ssh/id_dsa.
Your public key has been saved in /home/<userid>/.ssh/id_dsa.pub.
The key fingerprint is:
dd:ff:00:87:43:11:fa:7b:0d:84:3a:19:3b:7f:5d:2e <userid>@<host>

    The private key file id_dsa will be generated without a passphrase so that Co:Z can run in batch. It is therefore important that this file is protected with file permissions and/or ACLs that only allow the owning userid to read the file.

2.4 Windows Target System Installation

The distribution .zip file for Co:Z includes pre-built binaries for 32-bit Windows systems. The Windows machine must also have OpenSSH installed, which is available as part of the free Cygwin environment.

Note: Exercise caution when editing text files in the Cygwin distribution, especially shell scripts. Make sure that you use an editor that recognizes and preserves the unix line end characters. Wordpad will work in a pinch, but Notepad will not. If you are comfortable with Unix editors, you can include the vim (vi) package when you install Cygwin.

Install Cygwin and OpenSSH on Windows

These instructions supplement the information available on the Cygwin website, and must be run under a Windows user with administrator privileges.

  1. Download and excute the Cygwin setup.exe installation wizard

  2. Accept the default wizard selections, except where changes are necessary (e.g. "Select Your Internet Connection")

  3. After choosing a Download Site, the available packages are listed. Expand the Net node in the package list and click on the Skip: icon next to the package openssh. This will cause the openssh and openssl packages to be selected for installation.

  4. (Optional) Expand the "Editors" node in the package list and select the vim package if you would like to edit with vi.

  5. Wait for the installation to complete. This may take some time depending on the speed of your internet connection.

  6. Open a shell: Start+Programs+Cygwin+Cygwin Bash Shell. NOTE: If you are running under Windows Vista, this shell must be run as Administrator. Also note that under Vista, some of the ssh config messages below will be slightly different, but with the suggested responses below, it should install correctly.

Configure and test sshd

[Note]Note

This step is required only if you wish to use Windows as a Target system for the Co:Z Launcher. Use of the Dataset Pipes commands to initiate access to MVS datasets does not require a Windows sshd server.

  1. Once Cygwin is installed, setting up sshd is simply the matter of running the script ssh-host-config from the shell opened in the previous step. Recommended user responses are included below:

    win$ ssh-host-config
Generating /etc/ssh_host_key
Generating /etc/ssh_host_rsa_key
Generating /etc/ssh_host_dsa_key
Generating /etc/ssh_config file
Privilege separation is set to yes by default since OpenSSH 3.3.
However, this requires a non-privileged account called 'sshd'.
For more info on privilege separation read 
/usr/share/doc/openssh/README.privsep.

Should privilege separation be used? (yes/no) yes
Warning: The following function requires administrator privileges!
Should this script create a local user 'sshd' on this machine? (yes/no) yes
Generating /etc/sshd_config file


Warning: The following functions require administrator privileges!

Do you want to install sshd as service?
(Say "no" if it's already installed as service) (yes/no) yes

Which value should the environment variable CYGWIN have when
sshd starts? It's recommended to set at least "ntsec" to be
able to change user context without password.
Default is "ntsec".  CYGWIN=(Enter)

The service has been installed under LocalSystem account.
To start the service, call `net start sshd' or `cygrunsrv -S sshd'.

Host configuration finished. Have fun!

    More information on setting up OpenSSH under Cygwin are available in the /usr/share/doc/openssh/README file under the Cygwin home directory.

    Note: If you wish to have sshd listen on a port other than the default (22) edit the file /etc/sshd_config and change the Port 22 line to reflect the desired port. With Vista, you will need to change the file permissions to do this as the file is owned by a different user id. Be sure to revert the permissions after editing.

  2. Start sshd by running cygrunsrv:

    win$ cygrunsrv -S sshd
win$ ps -eaf
      UID     PID    PPID TTY     STIME COMMAND
  sgoetze    2644       1 con  16:28:32 /usr/bin/bash
   SYSTEM    4012       1   ?  16:30:53 /usr/bin/cygrunsrv
   SYSTEM     868    4012   ?  16:30:53 /usr/sbin/sshd
  sgoetze    1664    2644 con  16:30:58 /usr/bin/ps

  3. Test Cygwin ssh locally:

    win$ ssh <userid>@localhost
The authenticity of host 'localhost (127.0.0.1)' can't be established.
RSA key fingerprint is cc:7c:3d:b5:3e:43:5a:6f:12:e2:1a:af:80:45:ae:fa.
Are you sure you want to continue connecting (yes/no)? yes
Warning: Permanently added 'localhost' (RSA) to the list of known hosts.
<userid>@localhost's password:

win$ logout
Connection to localhost closed.

  4. Install SSH public keys for z/OS userids on Windows

    In this step you will install the public key for the z/OS userid that you created when Section 2.3, “z/OS Customization” so that the z/OS ssh client can login to your Windows server without a password.

    Login to a z/OS Unix shell (telnet, rlogin, or ssh) and transfer the ssh public key to the server and issue the following commands (you may omit the -oPort option if you are using the default sshd port):

    ZOS$ sftp -oPort=<port>  <userid>@<windows_host>
Connecting to n.n.n.n...
The authenticity of host 'windows_host (n.n.n.n)' can't be established.
RSA key fingerprint is cc:7c:3d:b5:3e:43:5a:6f:12:e2:1a:af:80:45:ae:fa.
Are you sure you want to continue connecting (yes/no)? yes
Warning: Permanently added 'windows_host' (RSA) to the list of known hosts.
<userid>@windows_host's password:  ******
sftp>  ascii
Sets the file transfer type to ASCII.
sftp>  cd .ssh
sftp>  put -p id_dsa.pub authorized_keys
Uploading id_dsa.pub to /home/sgoetze/.ssh/authorized_keys
id_dsa.pub                               100%  601     0.6KB/s   00:00
sftp> quit

    Note: If you are adding public keys from more than one z/OS userid to authorized_keys, then you must append each key rather than replacing the file as shown above.

  5. Test SSH connection initiated from z/OS

    This test will verify that you are not prompted for a password when logging into your Windows server using the z/OS ssh client. (You may omit the -p option if you are using the default ssh port: 22).

    ZOS$ ssh -p <port> <userid>@windows_host
Last login: Thu Nov 16 17:00:23 2006 from localhost

win$ logout
Connection to windows_host closed.
ZOS$

Install Co:Z target executables

  1. Download Co:Z for Windows from the downloads page.

  2. From a Cygwin bash shell, create the directory /opt if it doesn't exist.

  3. Extract the contents of the distribution .zip file to the /opt directory.

  4. Ensure that the files in /opt/dovetail/coz/bin are marked executable:

    $ cd /opt/dovetail/coz/bin
$ chmod +x cozagent cozclient fromdsn todsn

  5. Add {CYGWIN_HOME}/opt/dovetail/coz/bin to your Windows PATH environment variable and ensure that {CYGWIN_HOME}/bin is also present.

2.5 Unix/Linux/Posix Target System Installation

Configure and test sshd

[Note]Note

This step is required only if you wish to use the target system from the Co:Z Launcher. Use of the Dataset Pipes commands to initiate access to MVS datasets does not require a sshd server.

Most Linux and Unix distributions include OpenSSH. Follow the instructions for your operating system for installing and configuring the OpenSSH server (sshd) on your system.

  1. Test logging into ssh locally

    linux$ ssh <userid>@localhost
The authenticity of host 'localhost (127.0.0.1)' can't be established.
RSA key fingerprint is cc:7c:3d:b5:3e:43:5a:6f:12:e2:1a:af:80:45:ae:fa.
Are you sure you want to continue connecting (yes/no)? yes
Warning: Permanently added 'localhost' (RSA) to the list of known hosts.
<userid>@localhost's password: ******

linux$ logout
Connection to localhost closed.

  2. Install SSH public keys for z/OS Userids

    In this step you will install the public key for the z/OS userid that you created when Section 2.3, “z/OS Customization” so that the z/OS ssh client can login to your Unix/Linux server without a password.

    Login to a z/OS Unix shell (telnet, rlogin, or ssh) and transfer the ssh public key to the server and issue the following commands (you may omit the -oPort option if you are using the default sshd port):

    ZOS$ sftp -oPort=<port>  <userid>@linux_host
Connecting to 192.168.0.99...
The authenticity of host 'linux_host (192.168.0.99)' can't be established.
RSA key fingerprint is cc:7c:3d:b5:3e:43:5a:6f:12:e2:1a:af:80:45:ae:fa.
Are you sure you want to continue connecting (yes/no)? yes
Warning: Permanently added 'linux_host' (RSA) to the list of known hosts.
<userid>@linux_host's password:
sftp> ascii
Sets the file transfer type to ASCII.
sftp> cd .ssh
sftp> put -p id_dsa.pub authorized_keys
Uploading id_dsa.pub to /home/userid/.ssh/authorized_keys
id_dsa.pub                            100%  601     0.6KB/s   00:00
sftp> quit

    Note: If you are adding public keys from more than one z/OS userid to authorized_keys, then you must append each key rather than replacing the file as shown above.

  3. Test SSH connection initiated from z/OS

    This test will verify that you are not prompted for a password when logging into your server from the z/OS ssh client. (You may omit the -p option if you are using the default ssh port: 22).

    ZOS$ ssh -p <port> <userid>@linux_host
Last login: Thu Nov 16 17:00:23 2006 from localhost

linux$ logout
Connection to linux_host closed.
ZOS$

Install Co:Z target executables

Co:Z is distributed as a binary LSB compliant RPM for many linux distributions, including Linux for System Z. If you have an LSB 3.0 compliant distribution, installation is very simple and does not require re-compilation.

If a pre-built binary package is not available for your operating system, build and install the required Co:Z binaries on your target server as described in Appendix C, Compiling the Co:Z target system sources.

To install an RPM on an RPM based disto, download the appropriate Co:Z LSB from the downloads page and issue the following command:

$ sudo rpm -i coz-toolkit-n.n-m.rpm

It is possible to install an LSB RPM on a Debian based distro that is LSB 3.0+ compliant (e.g. Ubuntu Dapper) as well, but it first needs to be converted to a .deb file via alien:

$ sudo alien coz-toolkit-n.n-m.rpm
$ sudo dpkg -i coz-toolkit-n.n-n.deb

Note: the installation directory must be in the default PATH used when logging into sshd.

On some some distros, you may need to update /etc/profile to add binaries to PATH (See this FAQ entry).


[1] SSH user subsystems are, like all SSH remote commands, executed in a process under the authenticated client userid, so normal z/OS user security determines what resources can be accessed.

Prev   Next
1. Introduction Home 3. Configuration

Products | Documentation | Contact Us
Copyright 2006 Dovetailed Technologies, LLC.