Dovetailed Technologies

Appendix C. Session config files

The files /etc/ssh/cozsftp_config and /etc/ssh/cozsftp_server_config can be used to customize the options available for Co:Z SFTP client and server sessions respectively. The permissions for each of these files should be 0644.

Samples of both of these files are located in the /usr/lpp/coz/samples directory. These samples may be customized and placed at the above locations to make them active.

Each file has the sections notification:, fixed:, default: and pattern: which are described below. Additionally, individual users can provide their own file patterns and defaults (but not fixed options) in copies of these files in $HOME/.ssh

The individual Co:Z SFTP client and server options are described in: Appendix B, Co:Z SFTP options.

C.1 Specifying notification (immutable) options

Use the notification: section to specify site-wide message properties that cannot be overridden by individual users. When the notify Co:Z SFTP option is enabled, a message is written to the console on completion of put and get commands by the Co:Z SFTP server and client. Notifications are also written on completion of remove and rename commands on the server. For additional information on the notify option see Appendix B, Co:Z SFTP options. The table defines the configurable message properties.

Table C.1. Notification message properties

PropertyDescription
messageidSpecifies the message id assigned on successful command completion. By default, the message identifier is COZSC0001I on the client and COZSS0001I on the server.
errormessageidSpecifies the message id assigned on failed command completion. By default, the message identifier is COZSC0002E on the client and COZSS0002E on the server.
routingcodesA comma separated list of routing codes. By default, none are specified. Invalid routing codes are ignored with a warning message written to the session log.
descriptorcodesA comma separated list of descriptor codes. By default, none are specified. Invalid descriptor codes are ignored with a warning message written to the session log.
template.nA line in the message template where n is a number from 1 to 9. This property can be used to specify up to 9 message lines. The message template contains variables that are replaced at runtime with information about the completed command. A variable is represented in the template with the following syntax: ${variable}. See the table below for the supported variables. Note that the characters $, {, and } are reserved and may not be used in message text. If a single line message is configured, the message may be 126 characters. If a multi-line message is configured, each line in the message is limited to 70 characters. If a line exceeds these limits, the line is truncated and the last character in the line is set to '*'.

The table below defines case sensitive variables that can be used in the message template.

Table C.2. Message template variables

VariableDescription
userThe user ID
remote_ipThe remote IP address
remote_port The remote port
local_ipThe local IP address
local_port The local port
cmdThe FTP command code. One of STOR, RETR, RNTO, or DELE.
comp_codeThe file transfer completion code. One of 0, 4, or 12. Completion code 12 is set when a transfer is terminated before completion.
conddispThe current CONDDISP setting: C for catalog, D for delete.
fileThe fully qualified file name. A file with a leading slash is a POSIX file. A file without a leading slash is a data set.
file_typeOne of SEQ or JES.
confThe confidence level. Blank when not a transfer, i.e. remove or rename. 'unknown' for out bound transfers (RETR on the server, STOR for the client). 'high' for successful in bound transfers. 'low' when an error occurs on an in bound transfer.
kbsTotal bytes transfered rounded to the nearest 1024 bytes.
bsTotal bytes transfered
reply_codeFTP reply code
reply_stringFTP reply string. Note that this field is often longer than 70 characters in command failure scenarios; therefore, will be truncated in a multi-line message. When configured, it is recommended that this variable is the only text on the template line.
session_idA unique id assigned to the user's session. The session id is generated from the jobname followed by the last 5 digits of the pid.

Using the example configuration below,

notification:
#messageid=COZSS0001I
#errormessageid=COZSS0002E
#routingcodes=
#descriptorcodes=
template.1=${user},${remote_ip},${cmd},${comp_code},${reply_code}
template.2=${file}
template.3=${bs} bytes transferred
template.4=${reply_string}

the following message is written to the console on successful completion of a put command to the Co:Z SFTP server:

COZSS0001I COZUSER,192.28.145.64,STOR,0,250 
/u/vendor/cozuser/testfile.txt 
7956480 bytes transferred
Transfer completed successfully.

C.2 Specifying fixed (immutable) options

Use the fixed: section to specify site-wide options that cannot be overridden by individual users. Multiple options may be specified on a single line if separated by commas.

In the example below, the smf option is activated for all users, and because it it fixed, may not overridden by any user.

fixed:
smf

C.3 Specifying default options

Use the default: section to specify site-wide options that can be overridden by individual users. Multiple options may be specified on a single line if separated by commas.

In the example below, the mode option is set to text default. Because this option is set in the default: section, it can be easily overridden by individual users.

default:
mode=text
[Note]Note

The shell script used to run the Co:Z SFTP subsystem (sftp-server.sh) and the sample cozsftp batch scripts (sftp_connect.sh, sftp_get.sh, etc.) export LC_ALL=C to ensure proper shell script and C runtime execution. As a result, the default codepage for file transfer will be set to the z/OS platform default of IBM-1047. In order to set Locale specific codepage defaults, the default: section of the configuration files can be used:

# cozsftp_config (client)
# Set the default codepage for file transfers to EBCDIC Finnish/Swedish
default:
clientcp=IBM-1138
# cozsftp_server_config (server)
# Sets the default codepage for file transfers to EBCDIC Finnish/Swedish
default:
servercp=IBM-1138

C.4 Specifying file pattern specific options

It is often useful to have a set of custom options associated with specific files and/or datasets. For example, transferring all files with the .pax extension in binary mode. The pattern sections of the configuration files enable file and dataset names matching a specific POSIX glob pattern to automatically have specific options applied regardless of the options currently in place.

pattern sections can be supplied in the site (/etc/ssh) versions of the config files and may also be supplied in copies of these files located in the user's $HOME/.ssh directory.

[Note]Note

In some cases, it may not be possible for this file to be located in $HOME/.ssh; if this is the case, this location can be overridden during Co:Z SFTP server or cozsftp startup. For details, see the section called “Sitewide server configuration” and the section called “Sitewide client configuration”.

[Note]Note

A specific pattern may only be defined once; subsequent definitions read from the config file(s) are ignored.

When a put or get command is issued, the file or dataset name is checked against the patterns in the order that they were originally read. The options associated with the first matching pattern (if any) are applied to that specific file transfer. If an option is not defined by the pattern, it is left unchanged. Once the transfer completes, the overridden options are restored.

Pattern sections have the following syntax:

pattern: [//]<glob_pattern>
pattern-get: [//]<glob_pattern>
pattern-put: [//]<glob_pattern>

If double slashes (//) precede the pattern, it is used to match dataset names, otherwise it is used to match POSIX pathnames. Matching is performed on the name after it has been normalized (e.g. embedded slashes in a dataset name are converted to periods and the characters are converted to uppercase). Please note that DD names will not be not resolved to their catalog name prior to matching.

Patterns follow the UNIX glob pattern syntax, where the wildcard characters ? (match exactly one character) and * (match zero or more characters) can be used in conjunction with literal characters to provide a match pattern. For a complete description of the pattern syntax, see the “File name generation” section of the sh command documentation in the z/OS Unix System Services Command Reference.

Patterns in either the pattern: or pattern-get: sections are used to match files that are involved in SFTP get operations. Patterns in the pattern: or pattern-put: sections are used to match files that are involved in SFTP put operations. The same pattern may be defined in both a pattern-get: and pattern-put: section (with potentially different transfer options). A pattern specified in a pattern: section will apply to both operations. Note: If a pattern is defined in a pattern: section, it may not also be defined in a pattern-get: / pattern-put: section, and vice versa.

Determining which argument of the get or put command is used to match a pattern depends on which Co:Z component is being used:

sftp-server patterns (defined in the cozsftp_server_config files) are applied as follows:

sftp> get file-or-dsn <dest>    # pattern-get: or pattern: section
sftp> put <source> file-or-dsn  # pattern-put: or pattern: section

cozsftp patterns (defined in the cozsftp_config files) are applied as follows:

cozsftp> get <source> file-or-dsn  # pattern-get: or pattern: section
cozsftp> put file-or-dsn <dest>    # pattern-put: or pattern: section

Pattern examples

Setting text mode transfer for all members of a PDS

In the following example, a user specifies in $HOME/.ssh/cozsftp_config:

pattern: //*.JCL(*)
mode=text

And in a cozsftp session issues the following:

$ cozsftp user@host
Co:Z SFTP version: 1.9.3 (5.0p1) 2011-09-01
Copyright (C) Dovetailed Technologies, LLC. 2011. All rights reserved.
Connecting to host...
user@host's password: *****
cozsftp>lzopts mode=binary 
cozsftp>get myjcl //HLQ.DEV.JCL(FOO)

Because the target name matches the pattern, the file myjcl will be transferred as in text mode even though the current mode setting is binary.

Automatically set dataset allocation parameters

In the following example, consider the Co:Z SFTP server configuration file /etc/ssh/cozsftp_server_config:

pattern: //*.PARTNER.TRANS*
space=cyl.3.2,recfm=fb,lrecl=80

And a remote sftp session issues the following:

sftp> put trans0923 //HLQ.PARTNER.TRANS0923

Assuming the dataset HLQ.PARTNER.TRANS0923 doesn't already exist, a new dataset with that name will be allocated with allocation parameters associated with the pattern. This example shows how a server can be setup to automatically allocate incoming datasets based on a predefined name pattern.

Pattern selection determined by first match

For the examples that follow, consider the following configuration files excerpts:

(from $HOME/.ssh/cozsftp_server_config)
pattern: *.txt
mode=text,clientcp=1252,linerule=crlf
(from /etc/ssh/cozsftp_server_config)
pattern: *.zip
mode=binary
pattern: *.pax
mode=binary
pattern: *.txt
mode=text,linerule=lf
sftp> get myarchive.pax     1
sftp> get mynotes.txt     2
1

The file will be transferred in binary mode because it matches the site specified pattern (via /etc/ssh/cozsftp_server_config) for files with a .pax extension.

2

The file myfile.txt will be transferred in text mode with a client code page of 1252 and a linerule of crlf. While the .txt extension could match two of the specified patterns, the one processed first (via $HOME/.ssh/cozsftp_server_config) is selected. This is an example of how an individual user can override site behavior for a specific need (e.g. a Windows client platform).

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