2. Co:Z SFTP Configuration

In order to use Co:Z SFTP, installation is required for the Co:Z Toolkit for z/OS. Be sure to make note of the installation directory.

You do not need to install the Co:Z Target System Toolkit on your remote systems to use Co:Z SFTP. A compatible SSH/SFTP product is all that is required.

2.1 Co:Z SFTP Quick Start

After completing the installation of the Co:Z Toolkit for z/OS, the following are the minimum steps to get started using Co:Z SFTP. For more detailed information, see the remaining chapters in this guide.

On z/OS:

Edit /etc/ssh/sshd_config. Comment out the existing sftp subsystem line and add the following:
```
Subsystem sftp <COZ_INST>/bin/sftp-server.sh
```
Restart SSHD by executing:
```
kill -HUP `cat /var/run/sshd.pid`
```

Copy the site-wide sample configuration files to /etc/ssh:

cp <COZ_INST>/samples/sftp-server.site.rc /etc/ssh/sftp-server.rc
chmod 755 /etc/ssh/sftp-server.rc

cp <COZ_INST>/samples/cozsftp_server_site_config /etc/ssh/cozsftp_server_config
chmod 644 /etc/ssh/cozsftp_server_config

cp <COZ_INST>/samples/cozsftp_site_config /etc/ssh/cozsftp_config
chmod 644 /etc/ssh/cozsftp_config

Edit /etc/ssh/sftp-server.rc and uncomment USE_COZ_SFTP=true to enable Co:Z SFTP for all sftp users.
Using an SSH connection to z/OS (i.e, PuTTY from Windows or OpenSSH for unix), test a Co:Z SFTP client connection to the Co:Z SFTP Server using 127.0.0.1. Note: TSO OMVS cannot be used for this test because a password prompt does not work in this environment.
```
/u/home/user>cozsftp user@127.0.0.1
Co:Z SFTP version: 4.2.0 (6.4p1) 2017-01-10
Copyright (C) Dovetailed Technologies, LLC. 2008-2017. All rights reserved.
Connecting to 127.0.0.1...
Connected to 127.0.0.1.
Connection established, local_addr=127.0.0.1 local_port=1345 remote_addr=127.0.0.1 remote_port=22
cozsftp> ls /+
/+/error.log    /+/loglevel=I   /+/mode=binary  
cozsftp> exit
/u/home/user>
```
The command ls /+ is a special Co:Z SFTP command used to set file transfer options. If the response to this command is Can't ls: "/+" not found, then the Co:Z SFTP server installation is not correct. Recheck the installation steps to determine the error.

Once you have verified your Co:Z Toolkit installation for Co:Z SFTP, try connecting to the Co:Z SFTP server from a remote system with OpenSSH. Then work through the features described in Chapter 3, Using the Co:Z SFTP server. Next try connecting from z/OS using the Co:Z SFTP client command, cozsftp, to a remote SFTP server and work through the features described in Chapter 4, Using the Co:Z SFTP client.

2.2 Configuring the Co:Z SFTP Server

The configuration discussed here is designed to allow individual users to use either the original sftp-server or the enhanced Co:Z version, depending on their configuration. The default setup makes for an ideal beta testing environment, as only designated users will use the enhanced Co:Z sftp-server.

Modifying the SFTP Subsystem

Update the sshd_config file, typically located at /etc/ssh/sshd_config to modify the sftp subsystem definition: ^[2]

#Subsystem      sftp    /usr/lib/ssh/sftp-server     
Subsystem       sftp    <COZ_INST>//bin/sftp-server.sh

The original sftp subsystem line should be commented out.

The new subsystem line should point to the sftp-server.sh shell script located in the Co:Z installation bin directory. This script is designed to run the original sftp-server by default, but will run the Co:Z version if the user has configured it. See the section called “User specific customization” for details. The installation process should have marked this file as executable, but this should be verified.

If OpenSSH sshd was running prior to editing sshd_config, it should be reinitialized. This can be done by sending SIGHUP to the running process. The pid for this process is typically in the file /var/run/sshd.pid:
```
kill -HUP `cat /var/run/sshd.pid`
```

Co:Z SFTP Server configuration overview

The following table describes how a Co:Z SFTP Server session is started and outlines the sequence of configuration steps that occur prior to the establishment of the session. Details on these configuration steps follow the table.

Table 2.1. Co:Z SFTP Server initialization steps

Step	Configuration	Notes
1	$COZ_HOME/bin/sftp-server.sh	This shell script is executed by z/OS OpenSSH sshd upon a request for an SFTP server subsystem. This file should not be modified by the installation, but you may want to review the comments at the beginning of the script. This script will execute the site-wide and user-specific rc scripts and configuration files (see following steps).
2	/etc/ssh/sftp-server.rc	Site-wide environment variable configuration.
3	$HOME/.ssh/sftp-server.rc	User specific environment variable configuration. Can contain customized log file location, logging and tracing options, etc. The location of this file may be changed by setting the $COZ_SFTP_USER_SERVER_RC environment variable.
4	$HOME/.ssh/cozsftp_server_config	User-specific configuration settings. User customized file patterns may be specified here. File patterns here override those found in the site-wide file below. The location of this file may be changed by setting the $COZ_SFTP_USER_SERVER_CONFIG environment variable.
5	/etc/ssh/cozsftp_server_config	Site-wide configuration settings. Site-wide notification, fixed, default and file pattern settings.

Sitewide server configuration

The Co:Z SFTP Server can be configured with system-wide defaults by creating and configuring the file /etc/ssh/sftp-server.rc. A sample file (sftp-server.site.rc) is provided in the <COZ_INST>/samples, and should be copied to the /etc/ssh directory:

cp <COZ_INST>/samples/sftp-server.site.rc /etc/ssh/sftp-server.rc
chmod 755 /etc/ssh/sftp-server.rc

Sample site sftp-server.rc file

#!/bin/sh
# Set site-wide environment variables for Co:Z SFTP server.
# Place this sample as an executable script in file: /etc/ssh/sftp-server.rc

# Uncomment the following to make CO:Z SFTP the default for all users
#USE_COZ_SFTP=true 

# The following are the default locations for user level configuration files.
#COZ_SFTP_USER_SERVER_RC=$HOME/.ssh/sftp-server.rc 
#COZ_SFTP_USER_SERVER_CONFIG=$HOME/.ssh/cozsftp_server_config

By default, the sftp-server.sh script discussed above will execute the IBM version of sftp-server. The USE_COZ_SFTP environment variable can be used to make Co:Z SFTP Server the default for all users, even if they don't have their own sftp-server.rc file.

In some cases, Co:Z SFTP users may not have access to individual $HOME directories or it may be desirable to have all user configuration files centralized. In this case, the environment variable COZ_SFTP_USER_SERVER_RC can be specified to provide an alternate file name for the user .rc file in a common, readable location. For example, to specify a common directory for all user configuration files, set the following: COZ_SFTP_USER_SERVER_RC=/usr/share/coz/$LOWER_LOGNAME.sftp-server.rc

To disable the usage of user specific sftp-server.rc files for all users, COZ_SFTP_USER_SERVER_RC can be set to a dummy file name (e.g: /dummy); however, this requires that USE_COZ_SFTP be set to true in order to activate Co:Z SFTP for all users.

Note that the z/OS Unix System Services $LOGNAME environment variable holding the current username is in uppercase. As this is not always consistent with other POSIX style usage, the sftp-server.sh script exports an enviroment variable named $LOWER_LOGNAME that downcases the value in $LOGNAME.

Additionally, individual user server config files (where pattern based file transfer options are set) can be similarly located. To learn more about config files, refer to section: Appendix C, Session config files. By default, user server config files are located at $HOME/.ssh/cozsftp_server_config.

Note: The /etc/ssh/sftp-server.rc, if present, must be marked executable, as must the individual user files.

System-wide defaults for customizing options available for Co:Z SFTP server sessions can be configured by creating and configuring the file /etc/ssh/cozsftp_server_config. A sample file (cozsftp_server_site_config) is provided in the <COZ_INST>/samples, and should be copied to the /etc/ssh directory:

cp <COZ_INST>/samples/cozsftp_server_site_config /etc/ssh/cozsftp_server_config
chmod 644 /etc/ssh/cozsftp_server_config

For information on the session options available for configuration, see Appendix C, Session config files.

Restricting OpenSSH users to SFTP

Some installations prefer to restrict ssh users to a certain set of commands like the sftp-server, rather than giving them interactive shell access. See Appendix I, Restricting OpenSSH users to SFTP for a technique to enforce this restriction.

User specific customization

By default, the sftp-server.sh script discussed above will execute the IBM version of sftp-server. Individual users can activate the Co:Z version of stfp-server by creating a profile script, sftp-server.rc, in their home .ssh directory:

# if the user's .ssh does not exist:
mkdir $HOME/.ssh
chmod 700 $HOME/.ssh

cp <COZ_INST>/samples/sftp-server.user.rc $HOME/.ssh/sftp-server.rc
chmod u+x $HOME/.ssh/sftp-server.rc

Note: Removing or renaming this file will re-enable the IBM version of sftp-server, unless USE_COZ_SFTP=true has been set by the site.

Sample user sftp-server.rc file

#!/bin/sh
# The presence of this executable script in $HOME/.ssh/sftp-server.rc
# will cause the COZ version of sftp-server to be used

# You may uncomment and set the following options to override the defaults:  
#export SFTP_ZOS_OPTIONS="mode=text" 
#export SFTP_ZOS_INITIAL_DIR=// 
#export SFTP_LOGFILE=$HOME/sftp.log 

# The Co:Z support team may request that you uncomment the following options
# to enable tracing:
#export SFTP_SERVER_OPTIONS="-e -l debug3"
#export COZ_LOG=T

	The `SFTP_ZOS_OPTIONS` environment variable can be used to set the default options for the user. Multiple options may be specified, separated by commas. The options are described here: Appendix B, Co:Z SFTP options.
	The `SFTP_ZOS_INITIAL_DIR` environment variable can be used to override the home directory on the server. By default this is the user's USS home directory. If the string `//` or `/-/` is supplied, the user's MVS top level qualifier is used. Otherwise an absolute path (USS or MVS dataset space) may be supplied.
	Log files are created for every sftp server session; these files are of particular interest in case a problem is encountered and additional error detail is needed. See the section called “Co:Z SFTP Server logging” for additional information.

User specific defaults for customizing options available for Co:Z SFTP server sessions can be configured by creating and configuring the file /etc/ssh/cozsftp_server_config. A sample file (cozsftp_server_user_config) is provided in the <COZ_INST>/samples, and can be copied to the user's .ssh directory:

cp <COZ_INST>/samples/cozsftp_server_user_config $HOME/.ssh/cozsftp_server_config
chmod 644 $HOME/.ssh/cozsftp_server_config

For information on the session options available for configuration, see Appendix C, Session config files.

Co:Z SFTP Server logging

Log files are created for every sftp server session; these files are of particular interest when a problem is encountered and additional error detail is needed. An sftp client can retieve the current session log from the Co:Z SFTP Server. See Section 3.2, “Reading the error log” for additional information.

The following sections define how to control the logging destination as well as logging levels.

Logging Destination

Logging may be directed to the filesystem (/tmp by default) or to SYSOUT:

Filesystem
By default, log files are written to the /tmp directory (or the directory specified by the TMPDIR environment variable, if it is set). To change this default for all users, modify /etc/ssh/sftp-server.rc as needed. Individual users can override this setting by exporting SFTP_LOGDIR in the copy of sftp-server.rc in their individual .ssh directory.
In many cases, installations will choose to put Co:Z SFTP server session logs in a separate zFS or HFS filesystem. See the z/OS OpenSSH - Quick Install Guide for additional information on managing the /tmp filesystem.
The directory containing the log files must be cleaned up and monitored for space; however, it is important to keep these files for some period of time in order to allow:
- the current session log file to be accessed by the remote sftp client (e.g: get /+error.log) to get details of a problem, and
- support personnel to review the session log file for diagnostic information when investigating a problem.
In order to assist with log file maintenance, the environment variable SFTP_LOG_KEEP_DAYS can be exported from either the site or individual user's sftp-server.rc. When this variable is specified, the argument must be an integer greater than zero. Log files older than the argument will be removed when the user next establishes a Co:Z SFTP server session. The log files to be deleted must belong to the the connecting user and reside in the immediate directory specified by SFTP_LOGDIR (or $TMPDIR if SFTP_LOGDIR is not specified). Note that if SFTP_LOGFILE is specified, SFTP_LOG_KEEP_DAYS (if set) will be ignored.
SYSOUT
Optionally, logging output may be redirected to a SYSOUT spool file. To enable this, update the /etc/ssh/sftp-server.rc or user-specific $HOME/.ssh/sftp-server.rc script as follows:
```
SFTP_LOG_SYSOUT=true        # required
SFTP_SYSOUT_CLASS=H         # optional
unset SFTP_LOGFILE          # don't set this
export _BPX_JOBNAME=COZLOG  # recommended
```
If this feature is enabled:
- an additional OMVS address space will be created for each connection to write the log, and
- remote SFTP connections will not be able to get the current session log file using the "get /+error.log" command.
SDSF can be used to locate a user's logfile when needed for problem diagnosis. When the session is active, the output will be displayed by SDSF.DA. Once the session has ended, output is available in SDSF.H or SDSF.O, depending on whether the spool class/file is held. The jobid assigned to the output is from a pool of OMVS started tasks; therefore, is not unique and not owned by the SFTP user. The output can be identified by the jobname and the creation date. The following SDSF commands are useful:
- arr crdate 20 - expands the CrDate field to show the time as well as the date
- sort crdate d - sorts descending by date/time
If you would like to download the log spool file using Co:Z SFTP, first find the job in SDSF. Next, use the "?" prefix command to find the DSID. Finally, use the following commands in a remote SFTP client to download it:
```
ls /+mode=text
get //-JES/STCxxxxx/nnn logfile.txt
```

Note

	Note
Directing the Co:Z SFTP server log file to `/dev/console` is NOT recommended for the following reasons: the remote client will not be able to retrieve the log via the special /+error.log file name, when enabling debug logging to troubleshoot a problem, a very large amount of data will be written to the z/OS console, and when log messages go to the z/OS console, it is difficult to collect messages for a particular session which significantly impacts problem diagnosis. If console messages are needed for automation, see Chapter 5, Automation with System Console Messages for additional information.

Directing the Co:Z SFTP server log file to /dev/console is NOT recommended for the following reasons:

the remote client will not be able to retrieve the log via the special /+error.log file name,
when enabling debug logging to troubleshoot a problem, a very large amount of data will be written to the z/OS console, and
when log messages go to the z/OS console, it is difficult to collect messages for a particular session which significantly impacts problem diagnosis.

If console messages are needed for automation, see Chapter 5, Automation with System Console Messages for additional information.

Logging Level

The logging level is controlled by exporting the COZ_LOG and/or SFTP_SERVER_OPTIONS variables. To set these variables for all users, modify the /etc/ssh/sftp-server.rc as needed. Individual users can override these setting by exporting the variables in a copy of sftp-server.rc in their individual .ssh directory. Additionally, the Co:Z log level can be set with the Co:Z SFTP loglevel option. See Section B.2, “Miscellaneous options” for additional information.

SFTP_SERVER_OPTIONS allows command line options to be set for the sftp-server. The default is "-e -l info" which is required in order to route messages to SFTP_LOGFILE. "-e -l debug3" may be used to configure debug-level logging in sftp-server code.
COZ_LOG controls logging options for the Co:Z extension library used to add z/OS support to sftp-server. The default is I which logs error, warning and informational messages to SFTP_LOGFILE. This variable may be set to one of E, W, N, I, D, T or F for Error, Warning, Notice, Informational, Debug, Trace, or Fine logging levels as requested by the Co:Z support team.

2.3 Configuring the Co:Z SFTP Client

Client configuration overview

The following table describes how a Co:Z SFTP client (cozsftp) session is started and outlines the sequence of configuration steps that occur prior to the establishment of the session. Details on these configuration steps follow the table.

Table 2.2. Co:Z SFTP Client initialization steps

Step	Configuration	Notes
1	$COZ_HOME/bin/cozsftp	This shell script is is executed either interactively by a z/OS user or in a batch job. This file should not be modified by the installation, but you may want to review the comments at the beginning of the script. This script will execute the site-wide and user-specific rc scripts and configuration files (see following steps).
2	/etc/ssh/cozsftp_client.rc	Site-wide environment variable configuration.
3	$HOME/.ssh/cozsftp_client.rc	User specific environment variable configuration. Can contain customized options to the sftp command itself and/or custom logging settings. The location of this file may be changed by setting the $COZ_SFTP_USER_RC environment variable.
4	$HOME/.ssh/cozsftp_config	User-specific configuration settings. User customized file patterns may be specified here. File patterns here override those found in the site-wide file below. The location of this file may be changed by setting the $COZ_SFTP_USER_CONFIG environment variable.
5	/etc/ssh/cozsftp_config	Site-wide configuration settings. Site-wide notification, fixed, default and file pattern settings.

Sitewide client configuration

The cozsftp client command can be configured with system-wide defaults by creating and customizing the file /etc/ssh/cozsftp_client.rc. A sample file (cozsftp_client.site.rc) is provided in the <COZ_INST>/samples, and may be copied to the /etc/ssh directory:

cp <COZ_INST>/samples/cozsftp_client.site.rc /etc/ssh/cozsftp_client.rc
chmod 755 /etc/ssh/cozsftp_client.rc

Sample site cozsftp_client.rc file

#!/bin/sh
# Set site-wide environment variables for Co:Z SFTP client.
# Place this sample as an executable script in file: /etc/ssh/cozsftp_client.rc

# Uncomment the following to set command line options for the cozsftp command
#COZSFTP_CLIENT_OPTS=  

# The following are the default locations for user level configuration files.
#COZ_SFTP_USER_RC=$HOME/.ssh/cozsftp_client.rc 
#COZ_SFTP_USER_CONFIG=$HOME/.ssh/cozsftp_config 

# Uncomment the following export if you wish to keep the old cozsftp exit/return codes.
# Otherwise, then will be: 
#    0 - OK
#    8 - SFTP failed
#   12 - Failed to start SSH connection
#   16 - SSH connection failed after starting SFTP 
#export COZ_SFTP_EXIT_CODES=OLD

	This environment variable can be used to specify site-wide cozsftp command line options.
	In some cases, Co:Z SFTP users may not have access to individual `$HOME` directories or it may be desirable to have all user configuration files centralized. In this case, the environment variable `COZ_SFTP_USER_RC` can be specified to provide an alternate location for individual .rc files in a common, readable location. For example, to specify a common directory for all user configuration files, set the following: `COZ_SFTP_USER_RC=/usr/share/coz/$LOWER_LOGNAME.cozsftp_client.rc` Note that the z/OS Unix System Services `$LOGNAME` environment variable holding the current username is in uppercase. As this is not always consistent with other POSIX style usage, the sftp-server.sh script exports an enviroment variable named `$LOWER_LOGNAME` that downcases the value in `$LOGNAME`.
	Additionally, individual user client config files (where pattern based file transfer options are set) can be similarly located. To learn more about config files, refer to section: Appendix C, Session config files. By default, user client config files are located at `$HOME/.ssh/cozsftp_config`.
	Starting in Co:Z version 6.1.0, the Co:Z SFTP client exit codes were enhanced as described in the comments above. To preserve the old style exit codes (0==Success, 1==Failure). uncomment this export.

Note: The /etc/ssh/cozsftp_client.rc, if present, must be marked executable, as must the individual user files. e.g.

chmod +x /etc/ssh/cozsftp_client.rc

System-wide defaults for customizing options available for Co:Z SFTP client sessions can be configured by creating and configuring the file /etc/ssh/cozsftp_config. A sample file (cozsftp_site_config) is provided in the <COZ_INST>/samples, and should be copied to the /etc/ssh directory:

cp <COZ_INST>/samples/cozsftp_site_config /etc/ssh/cozsftp_config
chmod 644 /etc/ssh/cozsftp_config

For information on the session options available for configuration, see Appendix C, Session config files.

User specific customization

When the cozsftp client command is invoked, the contents of the optional file $HOME/.ssh/cozsftp_client.rc are dotted into the environment at the start of the command.

Most users will not require this file, but it may be used to automatically provide command line arguments to the cozsftp client without having to explicitly code them every time the client is invoked. The desired command line arguments must be made available in the environment variable COZSFTP_CLIENT_OPTS.

Sample user cozsftp_client.rc file

#!/bin/sh
# Set user-specific environment variables for Co:Z SFTP client.
# Place this sample as an executable script in file: $HOME/.ssh/cozsftp_client.rc

# Uncomment the following to set command line options for the cozsftp command
#   For example, to allow new host keys to be created automatically: 
#COZSFTP_CLIENT_OPTS="$COZSFTP_CLIENT_OPTS -oStrictHostKeyChecking=no"

User specific defaults for customizing options available for Co:Z SFTP client sessions can be configured by creating and configuring the file /etc/ssh/cozsftp_config. A sample file (cozsftp_user_config) is provided in the <COZ_INST>/samples, and can be copied to the user's .ssh directory:

cp <COZ_INST>/samples/cozsftp_user_config $HOME/.ssh/cozsftp_config
chmod 644 $HOME/.ssh/cozsftp_config

For information on the session options available for configuration, see Appendix C, Session config files.

^[2]It is sometimes convenient to set up a test OpenSSH server where this subsystem can be easily modified. To do this see: Appendix J, Setting up a test OpenSSH system on z/OS.

Prev		Next
1. Introduction	Contents	3. Using the Co:Z SFTP server

Prev		Next
1. Introduction	Home	3. Using the Co:Z SFTP server

Components

Downloads

Documentation

License/Support

Co:Z Documentation :: Co:Z SFTP - User's Guide V 8.1.0