Dovetailed Technologies

2. Installation

2.1 Co:Z Toolkit for z/OS

This section explains how to install the Co:Z Toolkit on z/OS. Once the toolkit is installed, individual components can be configured for use. For component configuration details, consult the user's guides (referenced in Chapter 1, Introduction).

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

  1. Download the Co:Z z/OS self-extracting installer file (download available from dovetail.com).

  2. Upload coz-vv.rr.mm.bin file to the z/OS zFS file system. Make sure you transfer the file with a binary mode transfer option.

  3. Verify that the cksum command (cksum coz-vv.rr.mm.bin) results match the checksum values published on the website download page.

  4. The installation script requires a small amount of temporary space to run successfully. Ensure that your /tmp file system is not full.

  5. The installing userid should be either UID=0 or have BPX.SUPERUSER authority or have both BPX.FILEATTR.APF and BPX.FILEATTR.PROGCTL authority. These permissions are required in order to enable APF authorization on the ssh-socket-info utility and to mark Co:Z SFTP programs as program controlled. If these permissions are not available during installation, the product will still install but may not work properly if SMF recording is enabled. See the Enabling SMF recording section in the Co:Z SFTP User's Guide for additional information.

  6. Make the installer file executable:

    $ chmod +x coz-vv.rr.mm.bin
  7. Run the installer:

    $ ./coz-vv.rr.mm.bin
    
    This software is licensed under the Co:Z Community License Agreement available
    for review at http://dovetail.com/docs/coz/licenses.html or as part of this 
    install package in file LICENSE (the "License").  
    ...
    
    Do you agree to the above license terms? [yes or no]
    yes
    Enter home directory [/usr/local/coz] : 1
    (Enter)
    /usr/local/coz is not an existing directory, create it? [y/n] : 
    y
    Enter new or existing target PDSE load module library name [SYS1.COZ.LOADLIB]: 2
    (Enter)
    The PDSE load module library 'SYS1.COZ.LOADLIB' does not exist, create it? [y]:
    y
    /usr/local/coz/loadmodules/COZBATCH -> //'SYS1.COZ.LOADLIB(COZBATCH)': executable
    /usr/local/coz/loadmodules/COZLNCH -> //'SYS1.COZ.LOADLIB(COZLNCH)': executable
    
    Enter new or existing PDS for Co:Z Sample JCL and PROCs [SYS1.COZ.SAMPJCL]: 3
    (Enter)
    The PDS 'SYS1.COZ.SAMPJCL' does not exist, create it? [y]:
    y
    /usr/local/coz/sampjcl/@@README -> //'SYS1.COZ.SAMPJCL(@@README)': text
    /usr/local/coz/sampjcl/COZCFGD -> //'SYS1.COZ.SAMPJCL(COZCFGD)': text
    /usr/local/coz/sampjcl/COZPROC -> //'SYS1.COZ.SAMPJCL(COZPROC)': text
    ...
    
    Enter PATH directory in which to create command symlinks 
          or 'none' [/usr/local/bin]: 4
    (Enter)
    created symlink /usr/local/bin/catsearch -> /usr/local/coz/bin/catsearch
    created symlink /usr/local/bin/cozserver -> /usr/local/coz/bin/cozserver
    created symlink /usr/local/bin/cozsftp -> /usr/local/coz/bin/cozsftp
    created symlink /usr/local/bin/fromdsn -> /usr/local/coz/bin/fromdsn
    created symlink /usr/local/bin/pdsdir -> /usr/local/coz/bin/pdsdir
    created symlink /usr/local/bin/read_passwd_dsn.sh 
                       -> /usr/local/coz/bin/read_passwd_dsn.sh
    created symlink /usr/local/bin/saf-ssh-agent -> /usr/local/coz/bin/saf-ssh-agent
    created symlink /usr/local/bin/safauth -> /usr/local/coz/bin/safauth
    created symlink /usr/local/bin/todsn -> /usr/local/coz/bin/todsn
    created symlink /usr/local/bin/zsym -> /usr/local/coz/bin/zsym
    
    FOMF0303I /usr/local/bin/ssh-socket-info: chattr() error: rv=-1, errno=8B, rsn=0924041A 5
    ***
    Unable to set extended attributes for program bin/ssh-socket-info
      - see installation guide for more informantion
    ***
    
    You should update user profiles so that MANPATH contains: /usr/local/coz/doc/man
    
    *** Co:Z Installation complete  ****
    (see README and LICENSE in install root directory for more information)
          
    1

    Enter the name of a new or existing zFS or HFS directory that will become the top-level "home" directory for the Co:Z Toolkit installation. This directory must be in a filesystem that is writable by the installing user and contains 12MB of free space. If you supply the name of an existing directory that is not empty, you will be prompted to continue, as it is not generally advisable to overlay an existing installation with a new version.

    2

    The fully-qualified name of the PDSE library to contain the Co:Z Launcher and Co:Z Batch program objects. If this dataset exists, it must be a PDSE and existing Co:Z load modules will be replaced.

    3

    The fully-qualified name of the PDS library to contain sample JCL for the Co:Z Toolkit. If this dataset exists, if must be RECFM=FB,LRECL=80 and existing members with the same names will be replaced.

    4

    Several Co:Z Toolkit Unix commands, such as cozsftp, fromdsn, todsn, etc. should be made available in user's PATH. One option is to customize /etc/profile to add <COZ_HOME>/bin to the PATH, but an alternative is to create symbolic links in an existing PATH directory to the Co:Z user commands in <COZ_HOME>/bin.

    To have the installation script create symbolic links, enter the name of the existing directory in which to create the links, or none to skip. When creating symlinks, this script will prompt you before replacing existing symlinks or files.

    The <COZ_HOME>/install/create-symlinks.sh script can be used to create these links at a later time, or to replace links to one Co:Z home directory (version) with links to another. See the comments in this script for more information and example usage.

    5

    These messages will appear if the installing userid does not have READ access to the BPX.FILEATTR.APF SAF resource. Co:Z will install properly and can be used, but the SMF socket information is not guaranteed to be accurate. A similar error will occur if BPX.FILEATTR.PROGCTL permission is not available to mark Co:Z SFTP programs as "program controlled"

  8. z/OS OpenSSH must be available either as a component of z/OS (V2R2 or higher) or by installing IBM Ported Tools OpenSSH on older z/OS versions.

    Proper configuration and tuning of z/OS OpenSSH can greatly improve overall performance, specifially for z/OS ssh client startup times. See the version of our Quick Install Guides matching your z/OS OpenSSH version for additional information.

  9. Review the @@README member of the PDS containing Co:Z Sample JCL and PROCS. Tailor the following component specific members:

    • Co:Z Launcher and Dataset Pipes: COZPROC and COZCFGD

      • The RUNLNCH, RUNLNCHK, and RUNLNCHP are basic Co:Z Launcher samples using different authentication methods. Additional examples can be found in the User's Guide.

    • Co:Z SFTP: SFTPPROC and SFTPIND

      • While other samples are provided, the SFTPSAMP member contains sample JCL for the perferred method of using the Co:Z SFTP client in batch. These samples use the Co:Z SFTP batch scripts installed in <COZ_HOME>/samples/sftp_batch. See Using the Co:Z SFTP client in batch in the User's Guide for additional information.

  10. For additional configuration and usage information, refer to the indiviual component User's Guides:

2.2 Co:Z Target System Toolkits

[Note]Note

These steps are required only if you wish to use *nix as a Target system for the Co:Z Launcher or the Dataset Pipes commands remotely. You do not need to install Co:Z on a remote system in order to use Co:Z SFTP.

Configure and test sshd

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. Test Linux ssh from z/OS:

    Repeat the above test from your z/OS userid to confirm that there are no firewall issues.

    ZOS$ ssh -p <port> <userid>@linux_host

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 A, 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
      

The package will be installed at /opt/dovetail/coz. Note: /opt/dovetail/coz/bin 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

2.3 Windows Target System Installation

The instructions that follow are for a Windows Server 2003 system, with the installation performed via the Remote Desktop.

For Windows desktop (non-server) environments, see Appendix B, Windows Desktop 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

If you are installing in a Windows Domain environment, this Cygwin/OpenSSH installation guide from IBM developerWorks may be helpful.

These instructions supplement the information available on the Cygwin website, and must be run under a Windows user with administrator privileges. The dialogs that follow are taken from the 1.7.x version of Cygwin.

  1. The instructions that follow assume that you have a functional Remote Desktop Connection to the Windows installation, and that the Windows system itself has Internet access.

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

  3. Select the option to install from Internet, then accept the default wizard selections except where changes are necessary (e.g. "Select Your Internet Connection")

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

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

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

Configure and test sshd

  1. Open a shell: Start+Programs+Cygwin+Cygwin Bash Shell. NOTE: This shell must be run as Administrator.

    Issue the ssh-host-config command. In the dialog that follows, user responses are highlighted in bold.

    $ ssh-host-config
    
    *** Info: Generating /etc/ssh_host_key
    *** Info: Generating /etc/ssh_host_rsa_key
    *** Info: Generating /etc/ssh_host_dsa_key
    *** Info: Generating /etc/ssh_host_ecdsa_key
    *** Info: Creating default /etc/ssh_config file
    *** Info: Creating default /etc/sshd_config file
    *** Info: Privilege separation is set to yes by default since OpenSSH 3.3.
    *** Info: However, this requires a non-privileged account called 'sshd'.
    *** Info: For more info on privilege separation read /usr/share/doc/openssh/README.privsep.
    *** Query: Should privilege separation be used? (yes/no) yes
    *** Info: Note that creating a new user requires that the current account have
    *** Info: Administrator privileges.  Should this script attempt to create a
    *** Query: new local account 'sshd'? (yes/no) yes
    *** Info: Updating /etc/sshd_config file
    
    *** Query: Do you want to install sshd as a service?
    *** Query: (Say "no" if it is already installed as a service) (yes/no) yes
    *** Query: Enter the value of CYGWIN for the daemon: [] <enter>
    *** Info: On Windows Server 2003, Windows Vista, and above, the
    *** Info: SYSTEM account cannot setuid to other users -- a capability
    *** Info: sshd requires.  You need to have or to create a privileged
    *** Info: account.  This script will help you do so.
    
    *** Info: You appear to be running Windows XP 64bit, Windows 2003 Server,
    *** Info: or later.  On these systems, it's not possible to use the LocalSystem
    *** Info: account for services that can change the user id without an
    *** Info: explicit password (such as passwordless logins [e.g. public key
    *** Info: authentication] via sshd).
    
    *** Info: If you want to enable that functionality, it's required to create
    *** Info: a new account with special privileges (unless a similar account
    *** Info: already exists). This account is then used to run these special
    *** Info: servers.
    
    *** Info: Note that creating a new user requires that the current account
    *** Info: have Administrator privileges itself.
    
    *** Info: No privileged account could be found.
    
    *** Info: This script plans to use 'cyg_server'.
    *** Info: 'cyg_server' will only be used by registered services.
    *** Query: Do you want to use a different name? (yes/no) no
    *** Query: Create new privileged user account 'cyg_server'? (yes/no) yes
    *** Info: Please enter a password for new user cyg_server.  Please be sure
    *** Info: that this password matches the password rules given on your system.
    *** Info: Entering no password will exit the configuration.
    *** Query: Please enter the password: <password>
    *** Query: Reenter: <password>
    
    *** Info: User 'cyg_server' has been created with password 'cyg_server'.
    *** Info: If you change the password, please remember also to change the
    *** Info: password for the installed services which use (or will soon use)
    *** Info: the 'cyg_server' account.
    
    *** Info: Also keep in mind that the user 'cyg_server' needs read permissions
    *** Info: on all users' relevant files for the services running as 'cyg_server'.
    *** Info: In particular, for the sshd server all users' .ssh/authorized_keys
    *** Info: files must have appropriate permissions to allow public key
    *** Info: authentication. (Re-)running ssh-user-config for each user will set
    *** Info: these permissions correctly. [Similar restrictions apply, for
    *** Info: instance, for .rhosts files if the rshd server is running, etc].
    
    
    *** Info: The sshd service has been installed under the 'cyg_server'
    *** Info: account.  To start the service now, call `net start sshd' or
    *** Info: `cygrunsrv -S sshd'.  Otherwise, it will start automatically
    *** Info: after the next reboot.
    
    *** Info: Host configuration finished. Have fun!
    

    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.

  2. Start sshd with netstart:

    $ net start sshd
    The CYGWIN sshd service is starting.
    The CYGWIN sshd service was started successfully.
              
  3. Test Cygwin ssh locally:

    [Note]Note

    When you supply the Windows userid, it must match the case of the actual id on your Windows system.

    $ ssh Administrator@localhost
    The authenticity of host 'localhost (::1)' can't be established.
    ECDSA key fingerprint is 4d:7c:7e:b5:f6:43:ae:6f:12:e2:1a:af:80:45:ae:fa.
    Are you sure you want to continue connecting (yes/no)? yes
    Warning: Permanently added 'localhost' (ECDSA) to the list of known hosts.
    Administrator@localhost's password:
    
    $ logout
    Connection to localhost closed.
  4. Create required userid(s)

    As Administrator, create the userid(s) you plan to use to carry out any Co:Z related work, and create appropriate passwords. Note: if you are using the Remote Desktop to administer this system, you will need to authorize these userids for remote access via Start+Control Panel+System+Remote settings+Select Users...

  5. Update /etc/passwd and /etc/group

    To allow for proper authentication under Cygwin/OpenSSH, the userid(s) created in the previous step need to be added to the Cygwin environment:

    $ $ mkpasswd -l > /etc/passwd
    $ $ mkgroup -l > /etc/group
  6. Configure userid(s) for ssh:

    Log out from the Administrator id and login to each of the created userid(s), and run a bash shell: Start+Programs+Cygwin+Cygwin Bash Shell. At the prompt, run the ssh-user-config. There is no need to create local identities for use with Co:Z, but feel free to create them if needed/desired for other purposes.

    $ ssh-user-config
    *** Query: Shall I create a SSH2 RSA identity file for you? (yes/no) no
    *** Query: Shall I create a SSH2 DSA identity file for you? (yes/no) no
    *** Query: Shall I create a SSH2 ECDSA identity file for you? (yes/no) no
    *** Query: Shall I create a (deprecated) SSH1 RSA identity file for you? (yes/no) no
    
    *** Info: Configuration finished. Have fun!
              
  7. Test Cygwin/OpenSSH from z/OS:

    Connect to the Windows Server from z/OS via ssh to capture the Windows OpenSSH server identity and to confirm that there are no firewall issues:

    ZOS$ ssh -p <port> <userid>@windows_server

    If this connection hangs, or is otherwise unsuccessful it is probably a Windows filewall issue. To test, disable the firewall temporarily and try again. If the connection works this time, you will need to add a firewall rule to allow the program c:\cygwin\usr\sbin\sshd.exe or add an inbound rule to allow the port that sshd listens on (usually 22).

Install Co:Z target executables

  1. Log back in as Administrator.

  2. Download Co:Z Target System Toolkit for Windows/Cygwin from the downloads page.

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

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

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

    $ cd /opt/dovetail/coz/bin
    $ chmod +x cozagent cozclient fromdsn todsn
              
  6. Add {CYGWIN_HOME}\bin and {CYGWIN_HOME}\opt\dovetail\coz\bin to your Windows PATH environment variable.

Copyright© 2009-2017 Dovetailed Technologies, LLC. All rights reserved.
Co:Z® is a registered trademark of Dovetailed Technologies, LLC.