An enhanced sftp client (cozsftp) for z/OS is also included in the Co:Z toolkit. This client can be used to initiate transfers with a remote host and supports the same set of file transfer options as the Co:Z sftp server. The cozsftp command is installed in the $COZ_HOME/bin directory.
$ export PATH=/opt/dovetail/coz/bin:$PATH 
$ cozsftp user@host
Co:Z sftp version: 1.1.0 (5.0p1) 2008-10-20
Copyright (C) Dovetailed Technologies, LLC. 2008. All rights reserved.
Connecting to host...
user@host's password: *****
cozsftp>The enhanced client introduces two new commands:
lzopts [-a] [option=value,...]
The lzopts command is used to set local (client) file transfer options. These options are set prior to initiating file/dataset transfers from z/OS to a remote host.
zopts [-a] [option=value,...]
The zopts command is used to set server file transfer options -- if the server is a Co:Z sftp server. The zopts command is functionally equivalent to the ls /+<option_list> command used by existing clients to set Co:Z sftp-server file transfer options.
Multiple options can be set by separating the option=value pairs with commas. An error is returned if one or more of the options was incorrectly specified, but the remaining options are set as requested.
The active options and their settings can be displayed by issuing the commands without
arguments. The -a option can be specified to list all
available options, even those that are not active.
![[Note]](images/note.gif) | Note |
|---|---|
For compatibility with IBM Ported Tools SFTP, the cozsftp command
recognizes the following additional subcommands:
ascii and binary. these subcommands are treated as synonyms for
|
Client session options are determined in the following priority order:
The
fixed:section of/etc/ssh/cozsftp_config(highest priority and non-modifiable)The first matching pattern (if any) from
$HOME/.ssh/cozsftp_configThe first matching pattern (if any) from
/etc/ssh/cozsftp_configPrevious interactive commands:
lzopts(described below) in the same sessionThe environment variable
SFTP_ZOS_OPTIONSThe
default:section of/etc/ssh/cozsftp_config(lowest priority)
For a list of available options, see Appendix A, Co:Z SFTP options.
For a description of the cozsftp_config file format, including
how to specify file name patterns, see Appendix B, Session config files.
cozsftp> lzopts mode=textclientcp=IBM-1047 loglevel=I mode=text servercp=IBM-1047
sftp> lzopts lrecl=80,recfm=fb,space=trk.3.2
lrecl=80,recfm=fb,space=trk.3.2cozsftp> lzopts -a
clientcp=IBM-1047 linerule=flexible loglevel=I lrecl=80
mode=text overflow=wrap recfm=fb servercp=IBM-1047
space=trk.3.2 NOallowmount NOblksize NObufno
NOcopies NOdataclas NOdest NOdir
NOdisp NOdsorg NOforms NOgdgnt
NOhold NOlabel NOlike NOmaxvol
NOmgmtclas NOnorecall NOoutdes NOrelease
NOretpd NOsequence NOshowall NOspin
NOstorclas NOsysout NOtrim NOtrtch
NOucount NOunit NOvol NOwriterThe enhanced Co:Z sftp client can connect to any sftp server, including a Co:Z SFTP server. In this case, there are two sets of transfer options in effect; the enhanced client's and the server's. Client side (local) options are controlled via the lzopts command. Server side (remote) options are controlled via the zopts command.
When transferring POSIX files between a z/OS server and z/OS client, using
the default mode=binary transfer option both locally and remotely
will usually yield the desired results. If codepage translations need to take place,
the desired clientcp, servercp and mode=text
can be set either locally (via lzopts command) or remotely
(via the zopts command). The other side can be left in
mode=binary.
When transferring datasets between a z/OS server and z/OS client, it is generally
recommended that linerule=rdw be used for binary transfers so that
record mode boundaries are preserved.
When converting from dataset to POSIX file between a z/OS server and z/OS client, the transfer options should be set where the dataset resides.
The Co:Z implementation of sftp accepts two prefix strings to identify
MVS datasets as absolute paths. The first (//) is consistent
with IBM's common usage. A secondary form (/-/) is also available.
The sftp lcd command can be used to navigate around the
z/OS dataset space. Using the dataset prefix // or
/-/, the dataset space can be entered. Once there, traversal
up and down various dataset levels can be performed similarly to hierarchical
file systems.
Partitioned datasets are treated as directories as well. Once a PDS is made the current working directory, its members can be listed and retrieved like normal files.
Just as listing the entire catalog from the root is not allowed, it is not possible to make the catalog root the current working directory. As such, the command lcd // will fail.
sftp> lcd //usersftp> lpwd Local working directory: //USER.COZ.TESTJCL sftp> lcd ..
sftp> lpwd Local working directory: //USER.COZ
The get and put commands are used to
transfer datasets and PDS members.
Any options previously set via the lzopts are in effect for any given transfer.
$ sftp user@linux.com
sftp> lzopts
sftp> lpwd Local working directory: //USER.COZ.TESTJCL sftp> put ONETEST /tmp/ONETEST
MVS datasets can be listed using the sftp lls command. Partitioned datasets are treated as directories with their members as entries.
When listing z/OS datasets locally with the lls command, catalog
search filter keys are in effect for any wildcard requests. The catalog search wildcards
*, **, and % used in the examples below
are described in the IBM manual DFSMS: Managing Catalogs - SC26-7409.
Note that this is different behavior from sftp clients that connect to the Co:Z sftp-server
and list datasets with the ls. In that case, regular file globbing rules are in
effect.
sftp> lcd //USER sftp> lls -al
... sftp> lcd //user.coz.sampjcl
This section describes how to use the enhanced client with POSIX files (HFS, zFS) on z/OS. Standard sftp implementations (including IBM's ported tools version) support only binary mode file transfers. The Co:Z implementation provides binary transfer mode by default, but also supports text mode transfers. Text mode transfers are controlled via the following options:
mode: when set totextcauses file transfers to be text based.clientcpandservercp: When text mode is active, these settings determine the codepage translation that will take place. The default client code page isISO8859-1. The default server code page is the current z/OS locale.linerule: When text mode is active, this setting determines how line separators are converted between the client and server.
The get and put commands are used to
transfer POSIX files (either on HFS or zFS filesystems).
The options (listed above) that have been previously set via the lzopts are in effect for any given transfer. All other options (used for dataset support) are ignored for POSIX file transfers.
$ sftp user@linux.comsftp>
sftp> put sftp-server.log /tmp
Uploading sftp-server.log to /tmp/sftp-server.log
sftp-server.log 100% 127 0.1KB/s 00:00
ZosPosixFile[I]: Closing file sftp-server.log - 127 bytes read, 127 bytes sent
ZosSmf119Record[I]: SMF Type119 recording not enabled; SMF recording disabled
The cozsftp client command can be conveniently used in a z/OS batch job without user interaction. The COZBATCH batch utility, also installed as part of the Co:Z toolkit, makes it easy to run cozsftp (or other Unix shell scripts) directly as z/OS batch jobs.
The authentication with the remote system must be set up so as not to require any user interaction. There are three ways to do this with OpenSSH:
Use the
SSH_ASKPASSenvironment variable to point to a program that will read a password.Use an OpenSSH public/private keypair.
Use a RACF Digital Certificate.
For details on these three authentication options, see Appendix E, Client Authentication Mechanisms. Note that instructions in this appendix must be followed in order to run the examples described below.
The RUNSFTP sample JCL distributed with the Co:Z toolkit can be used as a tailorable model for running the sftp client in a batch job.
//RUNSFTP EXEC PGM=COZBATCHEOB //DOWNLOAD DD DSN=&&DOWNLOAD,DISP=(NEW,DELETE), // DCB=(...),SPACE=(...) //
The RUNSFTPK sample JCL distributed with the Co:Z toolkit can be used as a tailorable model for running the sftp client in a batch job with certificates.
Note: A RACF Digital Certificate must be setup for the user prior to running this example. See the Co:Z customization section of the Co:Z Toolkit User's Guide for details.
//RUNSFTP EXEC PGM=COZBATCH
//STDIN DD *
# Customize these ...
coz_bin="/opt/dovetail/coz/bin"
ruser="uid"
server="remote.host.name"
servercp="ISO8859-1"
rfile="/path/to/file"
ssh_opts="-oConnectTimeout=60"
ssh_opts="$ssh_opts -oServerAliveInterval=60"
ssh_opts="$ssh_opts -oStrictHostKeyChecking=no" # accept initial host keys
# Invoke the Co:Z sftp client with an in-line batch of commands
# that downloads a remote file to a local DD.
# Note that "-k MY-RING" will cause cozsftp to use the Co:Z
# saf-ssh-agent to authenticate the ssh client using the user's
# RACF Digital Certificate in MY-RING
$coz_bin/cozsftp $ssh_opts -k MY-RING -b- $ruser@$server <<EOB
lzopts mode=text,servercp=$servercp
get $rfile //DD:DOWNLOAD
EOB
//DOWNLOAD DD DSN=&&DOWNLOAD,DISP=(NEW,DELETE),
// DCB=(...),SPACE=(...)
// The RUNSFTPS is similar to the previous example, but performs a put rather than a get. After the result of the put is checked, the saf-ssh-agent command is used to invoke ssh to process the new remote file.
Note: A RACF Digital Certificate must be setup for the user prior to running this example. See the Co:Z customization section of the Co:Z Toolkit User's Guide for details.
//RUNSFTP EXEC PGM=COZBATCH
//STDIN DD *
# Customize these ...
coz_bin="/opt/dovetail/coz/bin"
ruser="uid"
server="remote.host.name"
servercp="ISO8859-1"
rfile="/path/to/file"
ssh_opts="-oConnectTimeout=60"
ssh_opts="$ssh_opts -oServerAliveInterval=60"
ssh_opts="$ssh_opts -oStrictHostKeyChecking=no" # accept initial host keys
# Invoke the Co:Z sftp client with an in-line batch of commands
# that uploads a local dataset to a remote file and then runs
# ssh to invoke a remote command to process the uploaded file
# Note that "-k MY-RING" will cause cozsftp to use the Co:Z
# saf-ssh-agent to authenticate the ssh client using the user's
# RACF Digital Certificate in MY-RING
$coz_bin/cozsftp $ssh_opts -k MY-RING -b- $ruser@$server <<EOB
lzopts mode=text,servercp=$servercp
put //DD:UPLOAD $rfile
EOB
if [ $? -eq 0 ]; then
$coz_bin/saf-ssh-agent -c MY-RING ssh $ruser@$server /bin/chk $rfile
fi
//UPLOAD DD DSN=HLQ.UPLOAD.DATA,DISP=SHR
//