Dovetailed Technologies

2. Co:Z Launcher Installation

[Important]Important

Before proceeding, ensure that the Co:Z Toolkit for z/OS has been successfully installed according to the instructions provided in the document "Co:Z Toolkit Installation and Release Notes" at http://www.dovetail.com/docs/cozinstall/index.html. Be sure to make note of the installation directory.

In order to use the Co:Z Launcher (and remote Dataset Pipes clients), the Co:Z Target System Toolkit must be installed on the remote systems that you have identified. You do not need to install Co:Z on a remote system in order to use Dataset Pipes locally.

2.1 Co:Z Launcher environment requirements

  • z/OS requirements

    • Co:Z Toolkit for z/OS

    • Batch job userid allowed to listen on local port; OMVS segment required

  • Target System requirements:

    • Co:Z Target System Toolkit

    • OpenSSH sshd

    • sshd_config AllowTcpForwarding=yes for target userid

2.2 Configuring the dspipes subsystem (Optional)

To run Dataset Pipes commands initiated by a remote client, a subsystem must be configured in your z/OS OpenSSH server.[1] This subsystem does not need to be defined if you only want to use the Co:Z Launcher component of the toolkit.

This is done by updating the sshd_config file, typically located at /etc/ssh/sshd_config.[2]

Find the line "Subsystem" which defines the sftp subsystem. Immediately following the sftp line add this:

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

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

2.3 Unix/Linux/POSIX Target System Installation

[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 E, 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 (See this FAQ entry).

2.4 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 F, 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.



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

[2] It is sometimes convenient to set up a test OpenSSH server where this subsystem can be easily added. Instructions for doing this can be found in the Co:Z Installation and Release Notes.

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