Dovetailed Technologies

6. Running Dataset Pipes

The Dataset Pipes commands can be run independently of Co:Z. They work by default on any z/OS system that has Co:Z installed. These commands can also be run from any system that has the Co:Z toolkit for target systems installed if the dspipes SSH subsystem has been configured on your z/OS system (see this installation step).

6.1 Running Dataset Pipes with the openssh client

  1. From your shell, test your ssh connection to z/OS: ssh userid@zoshost env This should remotely run the env command and display the results in your shell. If this doesn't work, refer to the z/OS SSH manual or OpenSSH man pages for more information.

    1. The ssh -vvv option can be used to enable a protocol trace which can be helpful in diagnosing SSH connection problems.

    2. The command: telnet zoshost 22 can be used to verify that you can connect to your z/OS host over the default SSH port.

  2. The fromdsn -ssh and todsn -ssh client commands do not allow the underlying ssh child process to prompt for passwords.

    In order to use the clients, you must create SSH authentication keys:

    1. From your shell, Create SSH2 DSA key pair:

      $ cd
      $ mkdir .ssh
      $ chmod 700 .ssh
      $ ssh-keygen -t dsa
                  

      • give the private key a passphrase if you care at all about security!

      • save the private key in the default location: ~/.ssh/id_dsa

      • save the public key in the default location: ~/.ssh/id_dsa.pub

    2. In a z/OS Unix shell:

      zos$ cd
      zos$ mkdir .ssh
      zos$ chmod 700 .ssh
                  
    3. Upload the DSA public key (~/.ssh/id_dsa.pub) to the (userhome)/.ssh directory, and copy it (to the end) of authorized-keys. Note that this is a text file, so make sure that it is in EBCDIC after you upload it.

      For example (from your z/OS Unix shell):

      zos$ cd ~/.ssh
      zos$ cp id_dsa.pub >> authorized_keys
      zos$ chmod 600 authorized_keys
                    
    4. Under your shell, start a new shell as a child process of ssh-agent, which allows it to used your keypair. Under the new shell, use ssh-add to add your private key to the agent:

      $ ssh-agent $SHELL
      $ ssh-add
      Need passphrase for /home/uid/.ssh/id_dsa..
      Enter passphrase: ********
                  

      Note: it's also possible to setup ssh-agent as a cron/daemon process.

  3. The following commands can be used (from a shell running under ssh-agent) to test fromdsn and todsn:

    Example 6.1. display a PDS member

    fromdsn -ssh mypass userid@zoshost 'sys1.maclib(acb)'

    Example 6.2. upload a text file to the dataset "USERID.AUTOEXEC.BAT"

    cat /etc/profile | todsn -ssh userid@zoshost -r autoexec.bat

6.2 Running Dataset Pipes with the PuTTY ssh client

A Cygwin installation is required for Co:Z under Windows per the installation instructions, but you may use PuTTY as your ssh client in place of Cygwin's openssh client if you wish.

  1. Download and install the PuTTY commands.

    1. Download the PuTTY SSH client commands. plink is the only command absolutely required, but you will probably also find putty, pagent, puttygen, pscp, and psftp useful.

    2. Put these commands in a directory in your Windows PATH. Refer to the Putty docs for more information.

  2. From a Windows command prompt, test a plink remote z/OS command

    plink -ssh userid@zoshost env

    This should remotely run the "env" command and display the results in your Windows shell. If this doesn't work, refer to the z/OS SSH manual or PuTTY documentation for more information.

    1. The plink -vvv option can be used to enable a protocol trace which can be helpful in diagnosing SSH connection problems.

      The command telnet zoshost 22 can be used to verify that you can connect to your z/OS host over the default SSH port.

    The following commands can be used to test fromdsn and todsn:

    Example 6.3. display a PDS member

    fromdsn -ssh -pw mypass userid@zoshost //sys1.maclib(acb)

    Example 6.4. upload a text file to the dataset "USERID.AUTOEXEC.BAT"

    copy autoexec.bat con: | 
      todsn -ssh -pw mypass userid@zoshost -r //autoexec.bat

  3. The fromdsn and todsn client commands do not allow the underlying plink child process to prompt for passwords. As shown above, the plink -pw option can be used to supply your password on the command line.

    It's even better to setup SSH authentication keys so that you don't need to supply a password:

    1. Create SSH2 DSA key pair using the puttygen command

      • Ask for a "DSA" key

      • Give the private key a passphrase if you care at all about security!

      • Save both the public and private key to two separate files

    2. In a z/OS Unix shell:

      zos$ cd
      zos$ mkdir .ssh
      zos$ chmod 700 .ssh

    3. Upload the DSA public key to the (userhome)/.ssh directory, and copy it (to the end) of authorized-keys. Note that this is a text file, so make sure that it is in EBCDIC after you upload it.

      For example:

      zos$ cd ~/.ssh
      zos$ cp dsa_pub.key >> authorized_keys
    4. The authorized_keys files must have restricted permissions: chmod 600 ~/.ssh/authorized_keys

    5. Under Windows, start pagent.exe, and add your private key to it. This will prompt you (once) for your private key passphrase. It's nice to configure pagent automatically at startup; there's a command switch that lets you specify the private key to use. Then, when ever you login to Windows, you'll see a prompt from Pagent for your passphase, once you enter it, pagent will sit happily in your system tray.

      Once pagent.exe is running in the background with your (unlocked) private key, you never have to supply a password to fromdsn or todsn (or putty and plink) !!

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