Co:Z Toolkit User's Guide

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.

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.

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

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

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

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.

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:

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

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

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