Dovetailed Technologies Solutions Support Contact Us

Co:Z SFTP - User's Guide   V 2.1.1  Download PDF

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

2. Co:Z SFTP Configuration

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

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

  1. 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     1
Subsystem       sftp    /usr/lpp/coz/bin/sftp-server.sh     2

    1

    The original sftp subsystem line should be commented out.

    2

    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 “Customizing sftp-server.rc” for details. The installation process should have marked this file as executable, but this should be verified.

  2. 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`

Customizing sftp-server.rc

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 copying a special profile shell to their home .ssh directory: 

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

cp /usr/lpp/coz/samples/sftp-server.rc $HOME/.ssh
chmod u+x $HOME/.ssh/sftp-server.rc

Note: Removing or renaming this file will re-enable the IBM version of sftp-server.

Making Co:Z sftp-server the default for all users

In order to make the Co:Z sftp-server the default for all users, place a copy of sftp-server.rc in /etc/ssh:

cp /usr/lpp/coz/samples/sftp-server.rc /etc/ssh
chmod +x /etc/ssh/sftp-server.rc

In this version of the profile, explicitly set the environment variable USE_COZ_SFTP: 

USE_COZ_SFTP=true

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 G, Restricting OpenSSH users to SFTP for a technique to enforce this restriction.

Sample sftp-server.rc

A sample version of sftp-server.rc can be found in the samples directory of the installed Co:Z Toolkit. This file can be used as a template for individual users to modify and place in their $HOME/.ssh directory.

#! /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" 1
#export SFTP_ZOS_INITIAL_DIR=// 2
#export SFTP_LOGFILE=$HOME/sftp.log 3

# 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
1

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 A, Co:Z SFTP options.

2

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 // is supplied, the user's MVS top level qualifier is used. Otherwise an absolute path (USS or MVS dataset space) may be supplied.

3

Logfiles 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. By default, logfiles 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 sftp-server.sh as needed. Individual users can override this setting by exporting SFTP_LOGFILE in the copy of sftp-server.rc in their individual .ssh directory.

2.2 Configuring the Co:Z SFTP Client

When the cozsftp command is invoked, the contents of the files /etc/ssh/cozsftp_client.rc and $HOME/.ssh/cozsftp_client.rc are dotted into the environment at the start of the command.

These files 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 should be made available in the environment variable COZSFTP_CLIENT_OPTS.

For example, assume that the file /etc/ssh/cozsftp_client.rc is created with the following content: 

#!/bin/sh
COZSFTP_CLIENT_OPTS="-S /u/vendor/oshxl/bin/ssh"

In this example, the -S option directs all invocations of cozsftp to use the OpenSSH Accelerator for its ssh program.


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

Prev   Next
1. Introduction Home 3. Using the Co:Z sftp server
Copyright 2009 Dovetailed Technologies, LLC. All rights reserved.