sftpplus client 1.5.1 user manual - proatria.com · 17.2.2 REXX Error Codes ... 20 PROTOCOL ERROR MESSAGES ... SFTPPlus.rexx

Copyright: © Pro:Atria Limited 2005-2009. Neither the whole nor any part of this Document may be reproduced or transmitted, in any form or by any means,

electronic, mechanical, photo-copying or otherwise, without the prior written permission of Pro:Atria Limited

Client 1.5.1Client 1.5.1Client 1.5.1Client 1.5.1

User ManualUser ManualUser ManualUser Manual

The Old Exchange

South Cadbury

Yeovil

Somerset

© Pro:Atria Limited 2005-2009 Page 2 of 161

SFTPPlus Client 1.5.1 User Manual, Document Version 02/06/2009-1.003

Table of Contents

1 LEGAL NOTICES .............................................................................................................................. 5

1.1 COPYRIGHT ............................................................................................................................... 5

1.2 TRADEMARKS ........................................................................................................................... 5

1.3 LICENSE .................................................................................................................................... 6

1.4 STATUTORY REGULATION COMPLIANCE .................................................................................. 6

1.5 DOCUMENT CHANGE HISTORY................................................................................................. 6

2 PREFACE ....................................................................................................................................... 7

3 INTRODUCTION .......................................................................................................................... 8

4 DOCUMENT CONVENTIONS .................................................................................................... 9

5 INSTALLING SFTPPLUS CLIENT .......................................................................................... 10

6 CONFIGURING SFTPPLUS CLIENT ...................................................................................... 11

6.1 SFTPPLUS GLOBAL.CONF ..................................................................................................... 12

7 PROTOCOLS ............................................................................................................................... 13

7.1 TRANSFER PROTOCOLS ......................................................................................................... 13

7.1.1 SFTP .............................................................................................................................. 13

7.1.2 FTP ................................................................................................................................. 13

7.1.3 FTPS .............................................................................................................................. 14

7.1.4 SCP ................................................................................................................................ 14

7.1.5 HTTP .............................................................................................................................. 14

7.1.6 HTTPS ........................................................................................................................... 15

7.2 PROTOCOL PORTS ................................................................................................................. 15

8 PUTTY - CREATING CONNECTION FILES ......................................................................... 16

8.1 PUTTY INTRODUCTION (WINDOWS ONLY) ............................................................................ 16

8.2 STARTING A SESSION ............................................................................................................. 16

8.3 VERIFYING THE HOST KEY (SSH ONLY) ................................................................................ 17

8.4 LOGGING IN ............................................................................................................................. 18

8.5 AFTER LOGGING IN ................................................................................................................. 19

8.6 LOGGING OUT ......................................................................................................................... 19

8.7 ADDITIONAL PUTTY INFORMATION ........................................................................................ 19

9 SETTING UP TRANSFER DEFINITION FILES .................................................................... 20

9.1 EXAMPLE ‘PUT’ TRANSFER ..................................................................................................... 20

9.1.1 Connection definition ‘targetsys’ using PuTTY ........................................................ 20

9.1.2 Example targetsys.conf setup .................................................................................... 21

9.1.3 Restart Services - Windows ....................................................................................... 22

9.1.4 Restart Services – Linux/UNIX .................................................................................. 24

9.2 EXAMPLE ‘GET’ TRANSFER ..................................................................................................... 24

9.2.1 Connection definition ‘targetysys’ using PuTTY ...................................................... 24

9.2.2 Example gettargetsys.conf setup .............................................................................. 25

9.2.3 Initiate transfer .............................................................................................................. 26

10 NOTIFICATIONS AND ALERTS ......................................................................................... 28

10.1 EVENT ALERTS FOR WINDOWS .......................................................................................... 28

10.2 EVENT ALERTS FOR LINUX AND UNIX ................................................................................ 32

10.3 EMAIL ALERTS .................................................................................................................... 32

11 REMOTE SYSTEM COMMAND PROCESSING ................................................................ 34



12 AUDIT ....................................................................................................................................... 36

12.1 MESSAGE.CONF FILE ......................................................................................................... 36

12.2 MESSAGE DETAILS ............................................................................................................. 36

12.2.1 Message Severity......................................................................................................... 37

12.2.2 Message Routes .......................................................................................................... 38

12.3 MESSAGE.LOG FILE ............................................................................................................ 39

12.3.1 Message Format .......................................................................................................... 39

12.3.2 Log control .................................................................................................................... 39

12.4 ARCHIVE ............................................................................................................................. 39

13 USING PGP (GPG) .................................................................................................................. 41

13.1 PGP BASICS ....................................................................................................................... 41

13.2 INSTALLATION ..................................................................................................................... 41

13.3 PGP PUBLIC/PRIVATE KEY CREATION .............................................................................. 41

13.4 CREATE PUBLIC KEY .......................................................................................................... 42

13.5 CREATE PRIVATE KEY ........................................................................................................ 45

13.6 GENERATING A REVOCATION CERTIFICATE ....................................................................... 46

13.7 GLOBAL.CONF SETTINGS FOR GPG PARAMETERS ........................................................... 46

13.8 IMPORT PUBLIC KEYS FROM TRADING PARTNERS ............................................................ 47

13.9 GPG PROCEDURE SUMMARY ............................................................................................ 48

13.10 GPG COMMANDS AND OPTIONS ....................................................................................... 49

13.10.1 GPG.exe Commands .............................................................................................. 49

13.10.2 GPG.exe Options ..................................................................................................... 50

13.11 MISCELLANEOUS GPG INFORMATION ................................................................................ 51

13.11.1 Encrypting and Decrypting Documents ................................................................ 51

13.11.2 Defining Your Security Needs ................................................................................ 52

13.11.3 Choosing a Key Size ............................................................................................... 53

13.11.4 Protecting Your Private Key ................................................................................... 54

13.11.5 Selecting Expiration Dates and Using Sub Keys ................................................ 56

13.11.6 Key Integrity .............................................................................................................. 57

14 MANUAL TRANSFERS.......................................................................................................... 59

14.1 SFTP .................................................................................................................................. 59

14.1.1 SFTP Usage ................................................................................................................. 59

14.1.2 Starting PSFTP ............................................................................................................ 59

14.1.3 PSFTP start-up parameters........................................................................................ 60

14.1.4 Running PSFTP ........................................................................................................... 62

14.1.5 PSFTP quoting rules ................................................................................................... 63

14.1.6 PSFTP Examples ......................................................................................................... 64

14.1.7 PSFTP Parameters ...................................................................................................... 65

14.1.8 PSFTP Session commands........................................................................................ 66

14.1.9 Important PSFTP Notes .............................................................................................. 70

14.2 FTP/FTPS & HTTP/HTTPS ............................................................................................ 71

14.2.1 cURL Usage .................................................................................................................. 71

14.2.2 Starting cURL ............................................................................................................... 71

14.2.3 cURL Start-up Parameters ......................................................................................... 71

14.2.4 Running cURL .............................................................................................................. 72

14.2.5 cURL Examples ............................................................................................................ 72

14.2.6 FTP(S) & HTTP(S) Parameters ................................................................................. 74

14.2.7 Important cURL Notes ................................................................................................. 80

14.3 SCP .................................................................................................................................... 80

14.3.1 PSCP Usage ................................................................................................................. 81

14.3.2 Starting PSCP .............................................................................................................. 81

14.3.3 PSCP Parameters ........................................................................................................ 81

14.3.4 Running PSCP ............................................................................................................. 84

14.3.5 PSCP Examples ........................................................................................................... 85

14.3.6 PSCP Parameters ........................................................................................................ 86

14.3.7 Important PSCP Notes ................................................................................................ 87

15 TROUBLESHOOTING ........................................................................................................... 88



15.1 HELP ....................................................................................................................................... 88

15.1.1 Debug Mode ................................................................................................................. 88

15.1.2 Message Interpretation ............................................................................................... 90

15.1.3 As a Service or Manually? .......................................................................................... 90

16 SFTPPPLUS CLIENT ERROR MESSAGES ...................................................................... 92

16.1 SFTPPLUS CLIENT MESSAGE FORMAT ............................................................................ 92

16.2 SFTPPLUS CLIENT MESSAGE LIST ................................................................................... 93

17 REXX INTERPRETER .......................................................................................................... 109

17.1 SFTPPLUS.REXX ............................................................................................................. 109

17.1.1 Manual Running of SFTPPlus.rexx ......................................................................... 109

17.2 REX INTERPRETER ERROR MESSAGES ........................................................................... 111

17.2.1 REXX Message Convention ..................................................................................... 111

17.2.2 REXX Error Codes ..................................................................................................... 111

18 GLOBAL.CONF FILE PARAMETERS .............................................................................. 114

19 TRANSFER DEFINITION CONF FILE PARAMETERS .................................................. 119

20 PROTOCOL ERROR MESSAGES .................................................................................... 125

20.1 SFTP PROTOCOL ERROR CODES ................................................................................... 125

20.2 FTP PROTOCOL ERROR CODES ...................................................................................... 128

20.3 FTPS PROTOCOL ERROR CODES ................................................................................... 132

20.4 SCP PROTOCOL ERROR CODES ..................................................................................... 136

20.5 HTTP PROTOCOL ERROR CODES ................................................................................... 138

21 REFERENCES ....................................................................................................................... 158

22 TECHNICAL SUPPORT ....................................................................................................... 159

22.1 TRIAL SUPPORT ................................................................................................................ 159

22.2 ANNUAL MAINTENANCE SUPPORT ................................................................................... 159

22.3 GENERAL SUPPORT INFORMATION .................................................................................. 159

23 CONTACT INFORMATION ................................................................................................. 161



1 1 1 1 LEGAL NOTICESLEGAL NOTICESLEGAL NOTICESLEGAL NOTICES

1.1 Copyright

This product is copyright © Pro:Atria Limited 2005-2008. ALL RIGHTS RESERVED.

Portions of this product are copyright as follows;

apache is Copyright © The Apache Software Foundation 1999-2006

cURL is Copyright © 1996-2007, Daniel Stenberg

Cygwin DLL and utilities

is Copyright © 2000-2007,Red Hat, Inc

md5sum is Copyright © 2004 Free Foundation, Inc

MySQL is Copyright © MySQL AB and is provided under the General Public License (GPL) license agreement

openssh is Copyright © 1995,Tatu Ylonen

openssl is Copyright © 1998-2001,The OpenSSL Project

Regina is Copyright © 1992-1994 Anders Christensen

Regutils is Copyright © 1998, 2001 Patrick TJ McPhee

PuTTY is Copyright © 1997-2005 Simon Tatham

1.2 Trademarks

All products, company names and logos mentioned herein are the marks of their respective owners, including but not limited to, PuTTY, Regina, HP, IBM, Intel, Linux, Microsoft, Solaris, Tivoli, NetView, UNIX and Windows.

SFTPPlus is a trademark of Pro:Atria Ltd

Linux is a trademark of Linus Torvalds

UNIX is a trademark of the Open Group



1.3 License

SFTPPlus is not free software and may not be copied, distributed, sub-licensed, decompiled or used in any way except with express permission of the Licensor by License. 30 day free trials will normally be permitted by trial license on request. All license terms and conditions are available on request. SFTPPlus is licensed for use according to this documentation, in conjunction with the SFTPPlus license agreement.

1.4 Statutory Regulation Compliance

This document was produced by;

Pro:Atria Ltd

The Old Exchange, South Cadbury, Yeovil, Somerset BA22 7ET, UK

Registered in England – Company No: 4213930

1.5 Document Change History

Date Version History

30/03/2008 1.000 First Issue

17/11/2008 1.001 Minor updates.

25/04/2009 1.002 More updates

02/06/2009 1.003 Clarification of some items global.directoryscantime

Response directory automatically created.



2222 PREFACEPREFACEPREFACEPREFACE

The information in this manual is intended for personnel who install and configure the SFTPPlus Client software.

This manual describes how to install, configure and troubleshoot the SFTPPlus Client software product.



3333 INTRODUCTIONINTRODUCTIONINTRODUCTIONINTRODUCTION

SFTPPlusSFTPPlusSFTPPlusSFTPPlus

SFTPPlus Client – a tool for secure file transfers

SFTPPlus Client utilises open standards to implement secure file transfer with controls and audit suitable for the enterprise.

SFTPPlus Client provides a facility to allow any files placed into a directory to be transferred to a configured destination using sftp, ftp, ftps, http or https. All actions are audited, and alerts can be raised for certain conditions. Optionally, a response file can be retrieved after successful upload. All files can have a date and time stamp added to avoid duplicate names. All files are also archived after processing.

Pre and post processing is available for transfers.

Also;Also;Also;Also;

SFTPPlus Server (and SFTPPlus Client) is available for many platforms including;

Unix – (Intel) AIX, Solaris (Sparc & x86), HP-UX (Intel & Itanium), Tru64.

Linux – (Intel, PPC, Alpha, Sparc, Alpha) Red Hat, SUSE, Debian, etc.

Windows – 2000 Professional, 2000 Server, Server 2003 & XP.

Netware

z/OS

We have several platforms under development in 2008 so please check for availability.

Platforms under development are;

�� Vista

�� Mac

Please see PDF document “SFTPPlus 1.5.1 - Features and Benefits” for further details.



4444 DOCUMENT CONVENTIONSDOCUMENT CONVENTIONSDOCUMENT CONVENTIONSDOCUMENT CONVENTIONS

The following conventions are used in this document:

ConventionConventionConventionConvention UsageUsageUsageUsage ExampleExampleExampleExample

Bold Menu’s, GUI elements, strong emphasis or action

Click Apply or OK

-> Series of menu selections Select File -> Save

Monospace Filenames, commands, directories, URLs,

Refer to Readme.txt

Italics Information that the user must supply or type

dir /s

Double Quote Reference to other documents or products, emphasis

See “SFTPPlus User Manual”

Between bracket Optional items [ -s ] [ -f ] [ filename]

Between Chevrons

Parameter items <filename>

Please Note:Please Note:Please Note:Please Note:

Indicates neutral or positive information that emphasizes or supplements important points of the main text. Supplies information that may apply only in special cases.

Caution:Caution:Caution:Caution:

Advises users that failure to take or avoid a specific action could result in loss of data or system corruption.

Windows Only:Windows Only:Windows Only:Windows Only:

Linux Only:Linux Only:Linux Only:Linux Only:

Advises users of information that is platform specific. Other platform graphic logos can be shown.



5555 INSTALLING SFTPPLUS INSTALLING SFTPPLUS INSTALLING SFTPPLUS INSTALLING SFTPPLUS CLIENT CLIENT CLIENT CLIENT

For installation requirements and the installation procedure please refer to the appropriate installation guide for your platform which are available on request;

SFTPPlus Client 1.5.1 Installation Guide for Linux and Unix SFTPPlus Client 1.5.1 Installation Guide for OpenVM S SFTPPlus Client 1.5.1 Installation Guide for OS400

SFTPPlus Client 1.5.1 Installation Guide for Window s SFTPPlus for z/OS PuTTY User Manual 0.60

You must download the appropriate package for your platform.



6666 CONFIGURING SFTPPLUSCONFIGURING SFTPPLUSCONFIGURING SFTPPLUSCONFIGURING SFTPPLUS CLIENTCLIENTCLIENTCLIENT

This document assumes that you are familiar with the directory structure of SFTPPlus Client and understand the use of it’s sub-directories as explained in the “Installation structure” sub section of the document “SFTPPlus Client 1.5.1 Installation Guide” for your relevant platform.

There are a number of items that need to be configured in order for SFTPPlus Client to function.

• The main system configuration is performed by the editing global.conf file. This is a plain text file and can be changed with any editor, for example, vi or Kate in Linux, Notepad or WordPad in Windows. If you plan to use email notifications, then this file must be updated with the relevant SMTP information for your setup, otherwise it may be used as supplied but of course the email facility will not function until valid email details are entered and the appropriate parameters have valid entries.

The messages issued by SFTPPlus can be routed to a number of destinations; this can be based on message severity or controlled for individual messages. This file as supplied is suitable for most cases but it is easily modified using a text editor.

Transfers are defined with individual configuration files stored in the conf directory. Each transfer requires its own configuration file and matching inbox sub-directory. Two sample configurations (sample.conf and sampleget.conf) are provided, both of which are disabled when SFTPPlus is first installed. It is recommended to make the configuration file name match the inbox sub-directory name, for example, place sample.conf in the .conf directory, use;

C:\SFTPPlus\client\inbox\sample for Windows

or

/opt/SFTPPlus/inbox/sample for Linux/Unix

as the location for the transfer files, but these are only recommended locations.

The SFTPPlus Client service or daemon must be restarted to pick up any configuration change, see Chapter 9.1.3, Restart Services - Windows or Chapter 9.1.4, Restart Services - Linux UNIX for information on restarting the SFTPPlus Client system service. Changes include modification of an existing .conf file or placement of a new .conf file in the conf directory or changes to the global.conf or message.conf files.



6.1 SFTPPlus global.conf

The global.conf file contains all the main global configuration options. Most can be left at default, except the following parameters;

• global.smptaddress – the target address for email messages

• global.msghost – the host name of the SMPT server

• global.msgport – the port number of the SMTP port (the default is 25)

• global.msgfrom – the from address used for messages sent

Although the above parameters can be left to the default settings, email messaging will not function until your SMTP and email details are entered.

The parameters in the global.conf provide the foundation for the SFTPPlus system and its messaging system. This messaging system will become even more powerful with enhanced sophistication being planned for future releases.

For full details of the parameters used in the global.conf file, please see the Global.conf File Parameters chapter.



7777 PPPPROTOCOLSROTOCOLSROTOCOLSROTOCOLS

A protocol is a convention or standard that controls or enables the connection, communication, and data transfer between two computing endpoints. In its simplest form, a protocol can be defined as the rules governing the syntax, semantics, and synchronisation of communication. Protocols may be implemented by hardware, software, or a combination of the two. At the lowest level, a protocol defines the behaviour of a hardware connection.

It is difficult to generalise about protocols because they vary so greatly in purpose and sophistication. Most protocols specify one or more of the following properties:

•••• Detection of the underlying physical connection (wired or wireless), or the existence of the other endpoint or node

•••• Handshaking

•••• Negotiation of various connection characteristics

•••• How to start and end a message

•••• How to format a message

•••• What to do with corrupted or improperly formatted messages (error correction)

•••• How to detect unexpected loss of the connection, and what to do next

•••• Termination of the session or connection.

This communication layer has been stacked with more specific transport protocols which we use to move data from one computer to another.

7.1 Transfer Protocols

SFTPPlus Client can use a wide variety of transport protocols to ensure expedient and secure delivery of your valuable data.

7.1.1 SFTP

SSH File Transfer Protocol , a network protocol designed by the IETF to provide secure file transfer and manipulation facilities over the secure shell (SSH) protocol.

7.1.2 FTP

FTP or File Transfer Protocol is used to connect two computers over the Internet so that the user of one computer can transfer files and perform file commands on the other computer.



Specifically, FTP is a commonly used protocol for exchanging files over any network that supports the TCP/IP protocol (such as the Internet, extranet or an intranet).

7.1.3 FTPS

FTPS (commonly referred to as FTP/SSL) is a name used to encompass a number of ways in which FTP software can perform secure file transfers. Each way involves the use of a SSL/TLS layer below the standard FTP protocol to encrypt the control and/or data channels. It should not be confused with the SSH file transfer protocol.

The most common uses of FTP and SSL are:

• AUTH TLS or Explicit FTPS, named for the command issued to indicate that TLS security should be used. This is the preferred method according to the RFC defining FTP over TLS. The client connects to the server port 21 and starts an unencrypted FTP session as normal, but requests that TLS security be used and performs the appropriate handshake before sending any sensitive data.

• Implicit FTPS is an older, but still widely implemented style in which the client connects to a different port (usually 990), and an SSL handshake is performed before any FTP commands are sent.

7.1.4 SCP

Secure Copy or SCP is a means of securely transferring computer files between a local and a remote host or between two remote hosts, using the Secure Shell (more commonly known as SSH) protocol.

The term SCP can refer to one of two related things, the SCP protocol or the SCP program .

The SCP protocol is basically identical to the BSD RCP protocol. Unlike RCP, data is encrypted during transfer, to avoid potential packet sniffers extracting usable information from the data packets. However the protocol itself does not provide authentication and security; it expects the underlying protocol, SSH, to provide this function.

7.1.5 HTTP

Hypertext Transfer Protocol (HTTP) is a method used to transfer or convey information on the World Wide Web. Its original purpose was to provide a way



to publish and retrieve HTML pages but is also used to transfer file data as well.

Development of HTTP was coordinated by the World Wide Web Consortium and the Internet Engineering Task Force, culminating in the publication of a series of RFCs, most notably RFC 2616 (1999), which defines HTTP/1.1, the version of HTTP in common use today.

HTTP is a request/response protocol between clients and servers. The originating client, such as a web browser, spider, or other end-user tool, is referred to as the user agent. The destination server, which stores or creates resources such as HTML files and images, is called the origin server. In between the user agent and origin server may be several intermediaries, such as proxies, gateways, and tunnels.

7.1.6 HTTPS

HTTPS is a URI scheme which is syntactically identical to the http:// scheme normally used for accessing resources using HTTP. Using an https: URL indicates that HTTP is to be used, but with a different default port (443) and an additional encryption/authentication layer between HTTP and TCP. This system was designed by Netscape Communications Corporation to provide authentication and encrypted communication and is widely used on the World Wide Web for security-sensitive communication such as payment transactions and corporate logons.

7.2 Protocol Ports

As with most protocols, standards have evolved to ensure that connectivity utilises standard TCP port numbers. The protocols that SFTPPlus Client can use, with their relevant default port numbers, are as follows;

Protocol Port

SFTP 22

FTP 21

FTPS 21 (explicit mode)

FTPS 990 (implicit mode)

SCP 22

HTTP 80

HTTPS 443



8888 PPPPuuuuTTY TTY TTY TTY ---- CREATING CONNECTION CREATING CONNECTION CREATING CONNECTION CREATING CONNECTION FILESFILESFILESFILES

Windows Only:Windows Only:Windows Only:Windows Only:

8.1 PuTTY Introduction (Windows only)

PuTTY allows you to create connection definition files which SFTPPlus Client can use to connect to a remote computer for SSH connections (normally sftp on port 22). This section describes how to make such a connection definition file to use with a SFTPPlus transfer definition file (a .conf file found in the \SFTPPlus\Client\conf directory).

The PuTTY program is installed with the SFTPPlus Client installation and can be found in the SFTPPlus\Client directory.

8.2 Starting a Session

When you start PuTTY, you will see a dialog box as shown below.



This dialog box allows you to control everything PuTTY can do. See chapter 4 of the PuTTY User Manual 0.60 for details on what you can control. You don't usually need to change most of the configuration options. To start the simplest kind of session, all you need to do is to enter a few basic parameters.

In the `Host Name' field, enter the Internet host name of the server you want to connect to. You should have been told this by the provider of your login account. Now select a login protocol to use, from the `Protocol' buttons. For a login session, you should select Telnet, Rlogin or SSH (normally SSH). The fourth protocol, _Raw_, is not used for interactive login sessions; you would usually use this for debugging other Internet services. When you change the selected protocol, the number in the `Port' box will change. This is normal: it happens because the various login services are usually provided on different network ports by the server machine. Most servers will use the standard port numbers, so you will not need to change the port setting. If your server provides login services on a non-standard port, your system administrator should have told you which one.) Once you have filled in the `Host Name', `Protocol', and possibly `Port' settings, you are ready to connect. Give the profile a name in the ‘Saved Session’ field and press the ‘Save’ button. This will save the login profile details that you have entered for SFTPPlus to be used by the transfer definition conf file ‘savedprofile’ parameter. Press the `Open' button at the bottom of the dialog box, and PuTTY will begin trying to connect you to the server. If you enter any incorrect details, your connect session will fail. You can alter the settings, resave and ‘open’ a session to verify that any changes have worked.

8.3 Verifying the Host Key (SSH only)

If you are not using the SSH protocol, you can skip this section and indeed this chapter. If you are using SSH to connect to a server for the first time, you will probably see a message looking something like this:

The server's host key is not cached in the registry . You

have no guarantee that the server is the computer y ou

think it is.

The server's rsa2 key fingerprint is:

ssh-rsa 1024 7b:e5:6f:a7:f4:f9:81:62:5c:e3:1f:bf:8b :57:6c:5a

If you trust this host, hit ‘Yes’ to add the key to the PuTTY cache and carry on connecting. If you want to carry on connecting just once, without adding the key to the cache, hit No. If you do not trust this host, hit Cancel to abandon the connection. This is a feature of the SSH protocol. It is designed to protect you against a network attack known as ‘spoofing’. This is secretly redirecting your connection to a different computer, so that you send your password to the wrong machine. Using this technique, an attacker would be able to learn the password that guards your login account, and could then log in as if they



were you and use the account for their own purposes. To prevent this attack, each server has a unique identifying code, called a ‘host key’. These keys are created in a way that prevents one server from forging another server's key. So if you connect to a server and it sends you a different host key from the one you were expecting, PuTTY can warn you that the server may have been switched and that a spoofing attack might be in progress. PuTTY records the host key for each server you connect to, in the Windows Registry. Every time you connect to a server, it checks that the host key presented by the server is the same host key as it was the last time you connected. If it is not, you will see a warning, and you will have the chance to abandon your connection before you type any private information (such as a password) into it.

However, when you connect to a server you have not connected to before, PuTTY has no way of telling whether the host key is the right one or not. So it gives the warning shown above, and asks you whether you want to trust this host key or not. Whether or not to trust the host key is your choice. If you are connecting within a company network, you might feel that all the network users are on the same side and spoofing attacks are unlikely, so you might choose to trust the key without checking it. If you are connecting across a potentially hostile network (such as the Internet), you should check with your system administrator, perhaps by telephone or in person. (Some modern servers have more than one host key. If the system administrator sends you more than one fingerprint, you should make sure the one PuTTY shows you is on the list, but it doesn't matter which one you select.)

8.4 Logging in

After you have connected, and perhaps verified the server's host key, you will be asked to log in, usually using a username and a password. Your system administrator should have provided you with these. Enter the username and the password, and the server should grant you access and begin your session. If you have mistyped your password, most servers will give you several chances to get it right.

If you are using SSH, be careful not to type your username wrongly, because you will not have a chance to correct it after you press Return; many SSH servers do not permit you to make two login attempts using different usernames. If you type your username wrongly, you must close PuTTY and start again. If your password is refused but you are sure you have typed it correctly, check that Caps Lock is not enabled. Many login servers, particularly Linux/Unix computers, treat upper case and lower case as different characters when checking your password; so if Caps Lock is on, your password will probably be refused.



8.5 After logging in

After you log in to the server, what happens next is up to the server! Most servers will print some sort of login message and then present a prompt, at which you can type commands which the server will carry out. Some servers will offer you on-line help, others might not. If you are in doubt about what to do next, consult your system administrator.

8.6 Logging out

When you have finished your session, you should log out by typing the server's own logout command. This might vary between servers; if in doubt, try `logout' or `exit', or consult a manual or your system administrator. When the server processes your logout command, the PuTTY window should close itself automatically.

You can close a PuTTY session using the Close button in the window border, but this might confuse the server - a bit like hanging up a telephone unexpectedly in the middle of a conversation. We recommend you do not do this unless the server has stopped responding and you cannot close the window any other way.

8.7 Additional PuTTY Information

There are many other things that can be done with PuTTY, more than the scope of this document. If you require more in-depth information regarding the use of PuTTY or its companion programs, read the PuTTY User Manual available at our web site at www.proatria.com or visit the original developer’s website at;

http://www.chiark.greenend.org.uk/~sgtatham/putty/



9999 SETTING UP TRANSFER SETTING UP TRANSFER SETTING UP TRANSFER SETTING UP TRANSFER DEFINITION FILESDEFINITION FILESDEFINITION FILESDEFINITION FILES

Create a sub-directory of inbox (in this example, ‘targetsys’) if it does not already exist. Also create a sub-directory called ‘targetsys’ under the response directory if expecting a response file.

9.1 Example ‘put’ transfer

Please Note: If you are not using sftp or scp you can skip section 9.1.1 regarding “Connection definition ‘targetsys’ using PuTTY” and continue with “Example targetsys.conf setup”. A connection profile is optional for sftp and scp apart from an initial connection to the remote system to cache the host fingerprint key which should be done manually. A PuTTY profile is only required if you have unusual requirements.

9.1.1 Connection definition ‘targetsys’ using PuTTY

You need to pre-configure SFTP sessions using PuTTY. (a) Start putty.exe (Windows) or ./putty (Linux/Unix) putty (b) Create new session by typing a name in the saved sessions box

and pressing save, or load an existing session. (c) Set host name or IP address of the target system (d) Ensure ssh is selected (e) Set port to the correct ssh port (default 22) (f) Set proxy information as required (g) Save session as targetsys (used for savedprofile later). (h) Open session, accept key permanently when prompted and login

(if allowed). It is important that the remote host’s key is saved, as the SFTPPlus service has no way of asking the user to accept the key. There is no specific requirement for the logon to proceed, and it is possible that the remote system is configured to prevent such access. At this stage it is a good idea to create any required remote directories. If a full login is not permitted, then using psftp interactively is an option.

(i) Exit the remote system



9.1.2 Example targetsys.conf setup

Make a copy of sample.conf in the conf directory. Rename the new conf file targetsys.conf and edit (e.g. with Notepad or vi)

Please Note:

In a transfer definition file, a line that begins with /* and ends with */ is a comment line. If these are not in the above order or either of these is missing, the SFTPPlus service will not start.

You will have to set server, port, user, password etc. Each line should be in the format parameter = ’value’.

(a) Remove or comment out the disabled = ’y’ disabled line - this stops the definition being activated.

(b) subdir - the subdirectory of inbox that files will be placed in for transfer. All files placed here will be transferred. This directory has to exist.

(c) type of transfer, for this example use 'SFTP' (d) direction - get or put (put is default) (e) server - the server name or address of the target system port -

port to connect to, usually 22 for SFTP (f) user - the userid on the remote system (g) password - the password on the remote system (h) savedprofile - the profile NAME saved by putty earlier. Set this

parameter to '*notused*' if not used. (i) targetdir - the target directory on the remote system for transferred

files (for put only). This is a relative path. (j) forcelowercase - use lower case names for the transfer, ignores

the original case of the file (k) targettimestamp - include a timestamp at the target for

uniqueness ’y’ or ’n’ (default ’y’). This value must be set to ’n’ for systems that do not support long filenames.

(l) createmd5sum - will an md5sum file be created ’y’ or ’n’ (default ’y’)

(m) sendmd5sum - the md5sum of the file can also be transferred if required.



(o) preprocess - Allow customised processing before transfer if required. As an example, you may wish to copy the incoming file to another inbox directory to copy this file to multiple destinations.

(p) postprocesssuccess - Allow customised processing after a successful transfer if required.

(q) postprocessfail - Allow customised processing after a failed transfer if required.

(r) response - set to y if a response file is to be returned. This would typically be created by the remote system after processing the transferred file. The file will be placed in the SFTPPlus\Client\response\<subdir> directory (Windows) or /opt/SFTPPlus/respose/<subdir> directory (Linux/Unix), which must exist. <subdir> relates to the name of your transfer definition file if you are using our default method as outlined previously. With later versions of SFTPPlus client, this sub-directory will be created automatically is it does not exist. To check if this option is included in the build you are using, open the Changelog file with a text editor/viewer and if the following comment has been included, then the directory will be created - "Response sub-directory gets created automatically now."

(s) responsein - the filename that should be collected. This can be a plain file name or use %fname% and %ftype% for name and type matching. %ftype% does not include the ’.’ separator, e.g. if the file format is FNAME_rpt.FTYPE use: responsein = ’%fname%_rpt.%ftype%’

i. responsedir- the directory where the response file will be collected from on the remote system

ii. responsetimestamp - include a timestamp in the response file for uniqueness ’y’ or ’n’ (default ’y’).

iii. postprocessresponsesuccess - Allow customised processing after a successful transfer if required.

iv. postprocessresponsefail - Allow customised processing after a failed transfer if required.

(t) maxtry - maximum number of attempts for a transfer. If this is exceeded the transfer will be considered to have failed.

(u) waittime - the time to wait between attempts if a transfer fails (y) initialwait - the time to wait before looking for a response file. (v) smtpaddress - the smtp email address for email alerts.

9.1.3 Restart Services - Windows

In release version 1.5 of SFTPPlus Client, if you copy a new conf file into the SFTPPlus\Client\Conf directory or make changes to an existing one, you will need to stop and restart the SFTPPlus service.



Restart the SFTPPlus service by typing ‘Start -> Run” and entering services.msc in the field box marked ‘Open:’ as shown below;

Scroll down the list of system services. Single left click on the ‘SFTPPlus’ Service, then right click and select ‘Stop’ from the dropdown menu.

Then right click and select ‘Start’ from

the dropdown menu.



The SFTPPlus service will now pick up your transfer definition file and perform the file transfer. You can monitor this transfer by reading the message.log file with a text editor such as Notepad or WordPad in Windows or using tail in Linux/UNIX.

9.1.4 Restart Services – Linux/UNIX

In release version 1.5 of SFTPPlus Client, if you copy a new conf file into the /opt/SFTPPlus/Client/Conf directory or make changes to an existing one, you will need to stop and restart the SFTPPlus service.

To restart the SFTPPlus daemon in Linux, enter the following command;

/etc/init.d/rc.SFTPPlus restart

9.2 Example ‘get’ transfer

Please Note: If you are not using sftp on port 22 you can skip the next section regarding “Connection definition ‘targetsys’ using PuTTY” and continue with “Example targetsys.conf setup”

9.2.1 Connection definition ‘targetysys’ using PuTTY

If you have already carried this out in section 81.1. you can skip this section as connection profiles are re-usable for both put and get remote connections.

You need to pre-configure an SFTP sessions using PuTTY. (a) Start putty.exe (Windows) or ./putty (Linux/Unix) putty (b) Create new session by typing a name in the saved sessions box

and pressing save, or load an existing session. (c) Set host name or IP address of the target system (d) Ensure ssh is selected (e) Set port to the correct ssh port (default 22) (f) Set proxy information as required (g) Save session with targetsys (used for savedprofile later). (h) Open session, accept key permanently when prompted and login

(if allowed). It is important that the remote host’s key is saved, as the SFTPPlus service has no way of asking the user to accept the



key. There is no specific requirement for the logon to proceed, and it is possible that the remote system is configured to prevent such access. At this stage it is a good idea to create any required remote directories. If a full login is not permitted, then using psftp interactively is an option.

(i) Exit the remote system

9.2.2 Example gettargetsys.conf setup

Make a copy of getsample.conf in the conf directory. Rename the new conf file gettargetsys.conf and edit (e.g. with Notepad)

Please Note: In this file, a line that begins with /* and ends with */ is a comment and is ignored.

You will have to set server, port, user, password etc. Each line should be in the format parameter = ’value’

(a) Remove or comment out the disabled = ’y’ disabled line - this stops the definition being activated.

(b) subdir - the subdirectory of inbox that files will be placed in for transfer. All files placed here will be transferred. This directory has to exist.

(c) Type of transfer, currently only SFTP is supported. (d) direction - get or put (put is default) (e) server - the server name or address of the target system port -

port to connect to, usually 22 for SFTP (f) user - the userid on the remote system (g) password- the password on the remote system (h) savedprofile- the profile NAME saved by putty earlier (i) timestamp - include a timestamp on the received file for

uniqueness ’y’ or ’n’ (default ’y’) (j) remotedir - the directory the file is to be pulled from on the remote

system (k) remotefile - the file name to be pulled from the remote system



(l) starttime - Time for transfer to be started, format is hh:mm This will be repeated daily at the same time

(m) createmd5sum - will an md5sum file be created ’y’ or ’n’ (default ’y’)

(n) sendmd5sum - the md5sum of the file can also be transferred if required.

(o) preprocess - Allow customised processing before transfer if required. As an example, you may wish to copy the incoming file to another inbox directory to copy this file to multiple destinations.

(p) postprocesssuccess - Allow customised processing after a successful

transfer if required. (q) postprocessfail - Allow customised processing after a failed

transfer if required. (r) response- (put only) set to y if a response file is to be returned.

This would typically be created by the remote system after processing the transferred file. The file will be placed in the response\subdir directory, which must exist.

(s) responsein- the filename that should be collected. This can be a plain file name or use %fname% and %ftype% for name and type matching. %ftype% does not include the ’.’ separator, e.g. if the file format is FNAME_rpt.FTYPE use : responsein = ’%fname%_rpt.%ftype%’

i. responsedir- the directory where the response file will be collected from on the remote system

ii. responsetimestamp - (put only) include a timestamp in the response file for uniqueness ’y’ or ’n’ (default ’y’).

iii. postprocessresponsesuccess - Allow customised processing after a successful transfer if required.

iv. postprocessresponsefail - Allow customised processing after a failed transfer if required.

(t) maxtry- maximum number of attempts for a transfer. If this is exceeded the transfer will be considered to have failed.

(u) waittime - the time to wait between attempts if a transfer fails (v) initialwait- the time to wait before looking for a response file. (w) smtpaddress- the smtp email address for email alerts.

9.2.3 Initiate transfer

In release version 1.5 of SFTPPlus Client, if you copy a new conf file into the SFTPPlus\Client\Conf directory or make changes to an existing one, you will need to stop and restart the SFTPPlus service.



To restart the SFTPPlus service, open the Windows Services Control Panel by typing ‘Start -> Run” and entering services.msc in the field box marked ‘Open:’ as shown below;

Scroll down the list of system services. Single left click on the ‘SFTPPlus’ Service, then right click and select ‘Stop’ from the dropdown menu.

Then right click and select ‘Start’ from

the dropdown menu.



10101010 NOTIFICATIONS AND ALNOTIFICATIONS AND ALNOTIFICATIONS AND ALNOTIFICATIONS AND ALERTSERTSERTSERTS

The messages issued by SFTPPlus are controlled by message.conf. This provides the message text, severity, help and routing information. Please refer to the Audit chapter for further details.

Messages are routed based on severity. As supplied, all messages are written to the message.log file and important messages are also written to the system and application event log. The message route of ‘console’ will write to event log when running as a service.

The message route destinations available are;

• Log

• Eventlog

• Email

• console

10.1 Event Alerts for Windows

You need to have suitable tools installed to use this facility. This section includes brief details for using the tools supplied with Windows under ‘Management and Monitoring Tools’. To set up alerts, find the required message number in message.conf and ensure that this is routed to the event log, either specifically or by severity.

For example, to make message 51 (‘Response file | for | transfer id available’) route to the log and event log, add a line;

message.route.51 = ‘log,eventlog’

If using Microsoft tools, use the evntwin program to add a new trap for the required message number. The event source name is SFTPPlus.

To use evntwin, do the following;

a). start the Event to Trap Translator (evntwin)

Select Start -> Run



Then enter evntwin.exe in the ‘Open’ field

b). select Custom configuration

c). click on the Edit button to see the list of sources



d). Click on the ‘+’ sign to expand the Application event source

e). scroll down and select SFTPPlus, then select message 51 and the click Add button



f). click OK to confirm

g). click OK or Apply to activate these settings



You will now receive an alert when SFTPPlus retrieves a response file.

10.2 Event Alerts for Linux and Unix

In Linux and Unix distributions, we do not log to syslog, only to the message.log file. This will be included in a later release.

10.3 Email Alerts

Email alerts are sent using an SMTP server. The server settings are defined in the global.conf file.

By default no messages are routed to email. To setup email routing of messages;

a). update the global.conf for your site SMTP server

b). set the route in message.conf for the desired severity or individual message(s) to include email, e.g. to make message 51 (‘Response file | for | transfer id available’) route to the log and email, add a line;



message.route.51 = ‘log,email’

c). optionally, set the smtpaddress parameter (in your transfer conf file) for email destinations for specific transfers.

d). restart the service.

If the SFTPPlus service has any more errors talking to the SMTP server, it will not retry and will disable its email routing. This is to prevent recursive errors when reporting on such a problem. Instead, a message 74 will be issued, which is a severity “S”. For further details on error messages see 'SFTPPlus Client Message Format' and 'SFTPPlus Client Message List' for further details of message format conventions and message description list.



11 REMOTE SYSTEM COMMAND PROCESSING When a transfer has been completed, you can run a native command on the destination or remote system. To do this, you must use the transfer definition file parameter; runaftertransfer

For example;

Your destination system is Linux Using the ‘put’ command. You want to move a file from the directory “download1” and move to another folder within the remote system. If your destination system is Linux you would enter the following in your transfer conf file;

runaftertransfer = 'mv /home/kevin/download1/*.* /h ome/fred//'

and doing the same on Windows;

Your destination system is Windows Using the ‘put’ command. You want to move a file from the directory “download1” and move to another folder within the remote system. If your destination system is windows you would enter the following in your transfer conf file;

runaftertransfer = 'mv c: \home \kevin \download2 \*.* c: \home \fred \'

Caution: In the destination, do not specify a file name. This will cause the command to fail.

The ‘runaftertransfer’ parameter will only run commands that are available within an ftp or sftp connection shell at the remote system.



The commands that you can use depend on the remote Operating System, but can include any of the following;

del To delete a file on the server, type del <filename> mkdir To create a directory on the server, type mkdir <newdirectoryname> rmdir To remove a directory on the remote server, type rmdir <directoryname> ren To rename a file on the remote server, type ren <oldname> <newname> ls To list the files in your remote working directory, type ls . ! You can run local Windows commands using the ! Command.

help If you type help, you would normally be provided help text from the remote Operating System.

cd and pwd PSFTP maintains a notion of your "working directory" on the server.

lcp and lpwd As well as having a working directory on the remote server, PSFTP also has a working directory on your local machine.

dir This will list the files in your remote working directory.

chmod PSFTP allows you to modify the file permissions on files on the server. mv Move a file. cp Copy a file. Using these and other possible commands, you can create sophisticated scripts to pre or post process functions before or after a file/directory transfer.



12121212 AUDITAUDITAUDITAUDIT

Caution: Caution must be exercised when editing the message.conf file. Erroneous modification of this file can cause serious problems with SFTPPlus Client issuing accurate error messages. Do not edit the error messages listed after the message routing section.

12.1 Message.conf File SFTPPlus provides a full audit trail through its message system. All messages are written to the message log (unless specifically disabled, not recommended) and can optionally be routed to the Windows event log, emails and are easily extended for other systems. The file message.conf provides the text message listings, message routing and message control mechanism. This allows messages to be routed according to requirements either on a SFTPPlus Client global system basis or individual message basis. The messages from this file are included in a later chapter.

The message.conf file is located in /opt/SFTPPlus/client directory in Linux/UNIX or c:\SFTPPlus\client in Microsoft Windows. The file can be edited by using a text editor within your Operating System.

12.2 Message Details

To aid with explaining the message format, I will use message 7 as an example:

message.text.7 = ’Definition | disabled - ignoring’

message.severity.7 = ’E’

message.help.7 = ’The definition is specifically di sabled in the configuration file. The definition should be removed if not needed. It can be left as disabled i f it may be required in future.’

These messages are defined in the message.conf file located in SFTPPlus\Client (Windows) or /opt/SFTPPlus (Linux/Unix).



The message numbers are used as an index, where the message text can be translated.

The message.log file parameter 'message.log' can be changed to accommodate either a different location and/or a different log file name. The default value for message.log file is;

message.logfile = 'message.log'

You could, for example, change this to be;

message.logfile = 'e:\transferlogs\message.log'

Or;

message.logfile = 'f:\transferlogs\ftp-transfer-mes sages.log'

This provides the user with a flexible method of directing the message output to a suitable location and filename if the default is not suitable.

12.2.1 Message Severity

Message severity has four classifications;

• I - information - no action needed • W - warning - usually a retriable error, e.g. file not ready yet • E - Error - something has failed, but can continue • S - Severe error - cannot continue

Message text - the | symbol will be replaced with parameter information. Parameters will be appended to the string if there are no | characters.



12.2.2 Message Routes

Message routes are set using the following variables:

• message.route.I - the message route for severity I • message.route.W - the message route for severity W • message.route.E - the message route for severity E • message.route.S - the message route for severity S

An individual message can have its route overridden using it’s number, e.g. message.route.7 = ’log,email’

Available message routes are:

• ’console’ - display if interactive, or piped output • ’log’ - write to the log file (see message.log file) • ’eventlog’ - (Windows only) - event log entries are used for snmp • ’email’ - send email (see global.conf parameter details)

Please Note:

Multiple routes must be separated with a comma (’,’)

By default, messages always go to the message.log file (as predefined in the message.conf file at software installation) which can be manipulated to suit your requirements. However, the default message route to the message.log file can be removed or overridden; it is highly recommended that this is not done. The message.log file is the main log file for the SFTPPlus system. Disabling message output to the main message.log file could result in an inability to provide accurate audit trail information of transfers and would also remove the existence of essential information to diagnose any issues arising from failed transfers or system errors. It is recommended that users add their own preferred message routes in addition to the message.log file output as this provides the most flexible messaging system.



12.3 Message.log File

The message log file will normally always be in the program root directory. This allows the issue of messages before reading config files. If you change the log file here the initial messages will still be written to the file defined in SFTPPlus.rexx

12.3.1 Message Format

Messages are issued in the following format:

yyyymmdd hh:mm:ss product nnnns text

20050719 10:47:57 SFTPPlus 0007E Definition sample disabled - ignoring

This was message 7 issued with parameter ’sample’ at 10:47:57 on 19 July 2005.

12.3.2 Log control

The message log file will be saved at the end of each day with the date appended to the end of the file name, e.g. message.log.20050720 for July 20 2005. The message logs may then be archived and deleted.

12.4 Archive

All files processed and the commands used are archived for audit purposes. The files are saved in the Archive sub directory (C:\SFTPPlus\client\archive in Windows and /opt/SFTPPlus/archive in Linux/Unix). The files all have a date and time stamp in their names. Examples for a typical transfer: myfile.20050720.094817.489000.xml

myfile.20050720.094817.489000.md5sum

myfile.20050720.094817.489000.sftp

myfile.20050720.094817.489000.result

myfile.20050720.094817.489000.response.sftp

myfile.20050720.094817.489000.response.result

myfile.20050720.094817.489000_rpt.xml



The original file was myfile.xml. The file was sent at 09:48:17 on July 20 2005. The suffixes indicate the data:

• xml - the original or response file suffix- the response file in this case has extra characters _rpt inserted. This will match the original file type

• md5sum - contains the ms5sum of the original file • SFTP - contains the SFTP commands for the transfer (or response) • result - contains the output of the transfer (or response)

The archive files can be deleted at any time.



13131313 USING PGP (GPG)USING PGP (GPG)USING PGP (GPG)USING PGP (GPG)

This chapter is devoted to the use of PGP encryption/decryption with SFTPPlus Client 1.5.

We have chosen to integrate the popular GnuPG software (known as GPG) with SFTPPlus Client 1.5 and provide us the opportunity to enable PGP use across many platforms.

13.1 PGP Basics

In order to run the GPG commands mentioned in this chapter, you must be in the directory where the GPG programs are located. By default these locations are (if using the installation defaults);

Linux/UNIX

/opt/SFTPPlus/bin

Windows

C:\SFTPPlus\Client

13.2 Installation

The GPG software is provided as part of the SFTPPlus Client 1.5 distribution package for Microsoft Windows and no further installation for GPG is required.

All other packages will include GPG from SFTPPlus Client 1.5.1. If you require GPG for your platform and you are not using the Windows version, please contact us (Contact Information) for information on obtaining the GPG software for your platform.

13.3 PGP Public/Private Key Creation

The key pairs required for GPG file transfer are only required to be created once. Private Key – this must be kept safe and not sent to anyone Public Key – needs to be sent to your trading partner



Please Note: In order for your trading partners to encrypt files that they send to you, you will then need to import their public key(s) into your keystore database.

13.4 Create Public Key

Public key generation is performed by following this method. Initiate creating a private/public key pair database and create a public key, type gpg --gen-key This will ask you; “Please select what kind of key you want”

(1) DSA and Elgamal (default) (2) DSA (sign only) (3) RSA (sign only)

Enter 1 for DSA and Elgamal

and press the ‘return’ key This is a widely used algorithm and is the most common. Next, the program will ask you; “What keysize do you want”

1024 is the DSA standard size. However, if data security is of the upmost importance it might be better to choose 2048 and this is the keysize we would recommend. The longer the key the more secure it is against brute-force attacks, but for almost all purposes the default keysize is adequate since it would be cheaper to circumvent the encryption than try to break it. Also, encryption and decryption will be slower as the key size is increased, and a larger keysize may affect signature length. Once selected, the keysize can never be changed. Enter 1024 or 2048 as appropriate and press the ‘return’ key



You will now be asked; “Please specify how long the key should be valid” 0 = key does not expire <n> = key expires in n days <n>w = key expires in n weeks <n>m = key expires in n months <n>y = key expires in n years

The default value is 0 (zero), does not expire. For most users a key that does not expire is adequate. The expiration time should be chosen with care, however, since although it is possible to change the expiration date after the key is created, it may be difficult to communicate a change to users who have your public key. Select your option as appropriate. You will be asked to validate the key expiry; Is this correct? (y/n)

Enter y or n Answering n forces the program to answer the question again. At the next question you will need to enter identification information; enter as appropriate. (Examples are used below for illustration) User ID constructed in the form Real Name, comment and email address. For example, if you wanted “Heinrich Heine (Der Dichter) <[email protected]>” Real Name: Heinrich Heine Email Address: [email protected]

Comment: (Der Dichter) The entered details will be displayed to confirm. The program will display; You have selected this USER_ID:

“Heinrich Heine (Der Dichter) <[email protected]>” Change (N)ame, (C)omment, (E)mail or (O)kay/(Q)uit Enter n to change the name c to change the comment e to change the email address o to continue (no changes required) or q to quit the key pair generation



Although on screen the letters required to make a selection are in bold, you must actually select the letters in lowercase. Enter as appropriate. Next, you will be asked to enter a passphrase There is no limit on the length of a passphrase, and it should be carefully chosen. From the perspective of security, the passphrase to unlock the private key is one of the weakest points in GnuPG (and other public-key encryption systems as well) since it is the only protection you have if another individual gets hold of your private key. Ideally, the passphrase should not use words from a dictionary and should mix the case of alphabetic characters as well as use non-alphabetic characters. A good passphrase is crucial to the secure use of GnuPG. Enter your passphrase

You will be asked to repeat the passphrase.

Please Note:Please Note:Please Note:Please Note: Very Important. Do not forget your passphrase. If you do you will be unable to decrypt files sent to you. If you cannot remember your passphrase you will have to revoke your key, re-generate a new private/public key pair and supply the new public key to third parties that you send and receive files from.

After a short time your key pair will be generated. You must send the public key to third parties that you wish to send encrypted files to. To list the gpg keys you have in your database, enter the following command; gpg --list-keys This will list all the gpg keys in your gpg database file. To send a third party your public key you must export it from you gpg database file. To export a public key, do the following; gpg –o <public key name.gpg> --export IDENTITY



For example, using the information earlier in this document gpg –o hhpubkey.gpg --export heinrichh@duesseldo rf.de After a short while the key will be generated and the file hhpbkey.gpg (or whatever you have called it) must be sent to the third party partners who will receive encrypted files from you.

13.5 Create Private Key

To list your stored private (or secret) keys, type the following command. gpg --list-secret-keys You will be shown a list of the private keys in your gpg database file. To generate a private key for use in file transfers, enter the following command; gpg --export-secret-keys IDENTITY > <private key n ame>.gpg Where IDENTITY is the email address as used when generating the gpg key pairs. For example; gpg –export-secret-keys [email protected] > hhprivkey.gpg This private key, hhprivkey.gpg will be referenced in the transfer definition conf file to create the file encryption – it is imperative that the gpg key pairs are generated and used in the correct manner or the encrypted files will be unreadable by the third party. We would suggest copying the private (and public) key file to the c:\SFTPPlus\client directory. However, you can place these keys anywhere on your local file systems as long as SFTPPlus has read access your private key. On Windows, if there are multiple user logon profiles which are used, we recommend that you store your private and public gpg keys in an appropriate sub-directory under your Windows logon profile under ‘Documents and Settings’.



13.6 Generating a Revocation Certificate

After your key pair is created you should immediately generate a revocation certificate for the primary public key using the option --gen-revoke. If you forget your passphrase or if your private key is compromised or lost, this revocation certificate may be published to notify others that the public key should no longer be used. A revoked public key can still be used to verify signatures made by you in the past, but it cannot be used to encrypt future messages to you. It also does not affect your ability to decrypt messages sent to you in the past if you still do have access to the private key.

gpg --output revoke.asc --gen-revoke mykey

The argument mykey must be a key specifier, either the key ID of your primary key pair or any part of a user ID that identifies your key pair. The generated certificate will be left in the file revoke.asc. If the --output option is omitted; the result will be placed on standard output. Since the certificate is short, you may wish to print a hardcopy of the certificate to store somewhere safe such as your safe deposit box. The certificate should not be stored where others can access it since anybody can publish the revocation certificate and render the corresponding public key useless.

13.7 Global.conf Settings for GPG Parameters

The global.conf file has several additional lines to support gpg functions. This allows SFTPPlus Client 1.5 to find the gpg programs and execute automated functions within SFTPPlus Client automated transfers.

These additional parameters are;

global.gpg = mypath || 'gpg.exe'

global.gpgparms = '--yes --trust-mode always --batch --encrypt -a -o - --passphrase-fd 0 -r'

global.gpgkeyphrase = ''

global.gpg provides a default path where to locate the gpg.exe program

global.gpgparams provides SFTPPlus Client with the default parameters that should be passed to the gpg when a gpg parameter is called or required in a transfer definition file.

global.gpgkeyphrase will pass your passphrase to an automated transfer task as you can not do this interactively. In the global.conf file, the default value is null (no value).



It is recommended that the 'global.gpg' parameter is not changed as this instructs SFTPPlus Client as to the location of the gpg executable. Changing this parameter incorrectly will cause gpg functions to fail. It is recommended that you keep the gpg.exe file in the root of the SFTPPlus client application.

13.8 Import Public Keys from Trading Partners

A public key may be added to your public key ring with the --import option.

gpg --import blake.gpg gpg: key 9E98BC16: public key imported gpg: Total number processed: 1 gpg: imported: 1 gpg --list-keys /users/alice/.gnupg/pubring.gpg --------------------------------------- pub 1024D/BB7576AC 1999-06-04 Alice (Judge) <alice @cyb.org> sub 1024g/78E9A8FA 1999-06-04 pub 1024D/9E98BC16 1999-06-04 Blake (Executioner) <[email protected]> sub 1024g/5C8CBD41 1999-06-04

Once a key is imported it should be validated. GnuPG uses a powerful and flexible trust model that does not require you to personally validate each key you import. Some keys may need to be personally validated, however. A key is validated by verifying the key's fingerprint and then signing the key to certify it as a valid key. A key's fingerprint can be quickly viewed with the --fingerprint command-line option, but in order to certify the key you must edit it. alice% gpg --edit-key [email protected] pub 1024D/9E98BC16 created: 1999-06-04 expires: n ever trust: -/q sub 1024g/5C8CBD41 created: 1999-06-04 expires: n ever

(1) Blake (Executioner) <[email protected]>

(2) Command> fpr pub 1024D/9E98BC16 1999-06-04 Blake (Executioner) <[email protected]> Fingerprint: 268F 448F CCD7 AF34 183E 52D8 9BDE 1A 08 9E98 BC16

A key's fingerprint is verified with the key's owner. This may be done in person or over the phone or through any other means as long as you can guarantee that you are communicating with the key's true owner. If the fingerprint you get is the same as the fingerprint the key's owner gets, then you can be sure that you have a correct copy of the key.



After checking the fingerprint, you may sign the key to validate it. Since key verification is a weak point in public-key cryptography, you should be extremely careful and always check a key's fingerprint with the owner before signing the key.

Command> sign pub 1024D/9E98BC16 created: 1999-06-04 expires: never trust: -/q Fingerprint: 268F 448F CCD7 AF34 183E 52D8 9BDE 1A08 9E98 BC16 Blake (Executioner) <[email protected]> Are you really sure that you want to sign this key with your key: "Alice (Judge) <[email protected]>" Really sign?

Enter 'y' or 'n' as appropriate.

Once signed you can check the key to list the signatures on it and see the signature that you have added. Every user ID on the key will have one or more self-signatures as well as a signature for each user that has validated the key.

Command> check uid Blake (Executioner) <[email protected]> sig! 9E98BC16 1999-06-04 [self-signature] sig! BB7576AC 1999-06-04 Alice (Judge) <[email protected]>

13.9 GPG Procedure Summary

The above procedure will allow you to perform the following functions; Generate a public and private key pair. (Private key with passphrase) Import a public key from a trading partner Create a transfer definition file to;

1. Collect file exported from application 2. Convert file with gpg encryption 3. Transfer file to target system using the FTP protocol on port 15021 with

gpg encryption



Please Note: The port you use will vary depending on the configuration of the remote system you are connecting to. Please check with the administrator of the remote system to check which port and protocol you should be using.

13.10 GPG Commands and Options

Here is a comprehensive list of GPG commands and options that can be used with the gpg.exe program. Some of these can be used to customise the gpg parameter in a transfer definition conf file for individual transfers. These can also be used in the global.conf to set global parameters for SFTPPlus Client. These command and options can also be used when performing a task manually.

13.10.1 GPG.exe Commands

GPG Commands:

Short form parameter

Long form parameter Description

-s --sign [file] Make a signature

--clearsign [file] Make a clear text signature

-b --detach-sign Make a detached signature

-e --encrypt Encrypt data

-c --symmetric Encrypt only with symmetric cipher

-d --decrypt Decrypt data (default)

--verify Verify a signature

--list-keys List keys

--list-sigs List keys and signatures

--check-sigs List and check key signatures

--fingerprint List keys and fingerprints

-K --list-secret-keys List secret keys

--gen-key Generate a new key pair

--delete-keys Remove keys from the public key ring





--delete-secret-keys Remove keys from the secret key ring

--sign-key Sign a key

--lsign-key Sign a key locally

--edit-key Sign or edit a key

--gen-revoke Generate a revocation certificate

--export Export keys

--send-keys Export keys to a key server

--recv-keys Import keys from a key server

--search-keys Search for all keys on a key server

--import Import/merge keys

--card-status Print the card status

--card-edit Change data on a card

--change-pin Change a card’s PIN

--update-trustdb Update the trust database

--print-md algo [files] Print message digests

13.10.2 GPG.exe Options

GPG Options:



-a --armour Create small ascii armoured output

-r --recipient NAME Encrypt for NAME

-u --local-user Use this user ID to sign or decrypt

-z N Set compression level (0 disables)

--textmode Use canonical text mode

-o --output Use as output file

-v --verbose Verbose mode

-n --dryrun Do not make any changes

-i --interactive Prompt before overwriting

--openpgp Use strict OpenPGP behaviour

--pgp2 Generate PGP 2.x compatible message



13.11 Miscellaneous GPG information

Here is a selection of relevant information regarding the use of GnuPG.

13.11.1 Encrypting and Decrypting Documents

A public and private key each have a specific role when encrypting and decrypting documents. A public key may be thought of as an open safe. When a correspondent encrypts a document using a public key, that document is put in the safe, the safe shut, and the combination lock spun several times. The corresponding private key is the combination that can reopen the safe and retrieve the document. In other words, only the person who holds the private key can recover a document encrypted using the associated public key.

The procedure for encrypting and decrypting documents is straightforward with this mental model. If you want to encrypt a message to Alice, you encrypt it using Alice's public key, and she decrypts it with her private key. If Alice wants to send you a message, she encrypts it using your public key, and you decrypt it with your private key.

To encrypt a document the option --encrypt is used. You must have the public keys of the intended recipients. The software expects the name of the document to encrypt as input; if omitted, it reads standard input. The encrypted result is placed on standard output or as specified using the option --output. The document is compressed for additional security in addition to encrypting it.

gpg --output doc.gpg --encrypt --recipient blake@cy b.org <doc name>

The --recipient option is used once for each recipient and takes an extra argument specifying the public key to which the document should be encrypted. The encrypted document can only be decrypted by someone with a private key that complements one of the recipients' public keys. In particular, you cannot decrypt a document encrypted by you unless you included your own public key in the recipient list.

To decrypt a message the option --decrypt is used. You need the private key to which the message was encrypted. Similar to the encryption process, the document to decrypt is input, and the decrypted result is output.

gpg --output <doc name> --decrypt doc.gpg



You need a passphrase to unlock the secret key for

user: "Blake (Executioner) <[email protected]>"

1024-bit ELG-E key, ID 5C8CBD41, created 1999-06-04 (main key ID 9E98BC16)

Enter passphrase:

Enter the passphrase and the file will be decrypted with a .doc extension

Documents may also be encrypted without using public-key cryptography. Instead, you use a symmetric cipher to encrypt the document. The key used to drive the symmetric cipher is derived from a passphrase supplied when the document is encrypted, and for good security, it should not be the same passphrase that you use to protect your private key. Symmetric encryption is useful for securing documents when the passphrase does not need to be communicated to others. A document can be encrypted with a symmetric cipher by using the --symmetric option.

gpg --output doc.gpg --symmetric <doc name>

Enter passphrase:

The document will be exported using a symmetric cipher.

13.11.2 Defining Your Security Needs

GnuPG is a tool you use to protect your privacy. Your privacy is protected if you can correspond with others without eavesdroppers reading those messages.

How you should use GnuPG depends on the determination and resourcefulness of those who might want to read your encrypted messages. An eavesdropper may be an unscrupulous system administrator casually scanning your mail, it might be an industrial spy trying to collect your company's secrets, or it might be a law enforcement agency trying to prosecute you. Using GnuPG to protect against casual eavesdropping is going to be different than using GnuPG to protect against a determined



adversary. Your goal, ultimately, is to make it more expensive to recover the unencrypted data than that data is worth.

Customizing your use of GPG revolves around four issues:

• choosing the key size of your public/private key pair,

• protecting your private key,

• selecting expiration dates and using sub keys, and

• managing your web of trust.

A well-chosen key size protects you against brute-force attacks on encrypted messages. Protecting your private key prevents an attacker from simply using your private key to decrypt encrypted messages and sign messages in your name. Correctly managing your web of trust prevents attackers from masquerading as people with whom you communicate. Ultimately, addressing these issues with respect to your own security needs is how you balance the extra work required to use GnuPG with the privacy it gives you.

13.11.3 Choosing a Key Size

Selecting a key size depends on the key. In OpenPGP, a public/private key pair usually has multiple keys. At the least it has a master signing key, and it probably has one or more additional sub keys for encryption. Using default key generation parameters with GnuPG, the master key will be a DSA key, and the sub keys will be ElGamal keys.

DSA allows a key size up to 1024 bits. This is not especially good given today's factoring technology, but that is what the standard specifies. Without question, you should use 1024 bit DSA keys.

ElGamal keys, on the other hand, may be of any size. Since GnuPG is a hybrid public-key system, the public key is used to encrypt a 128-bit session key, and the private key is used to decrypt it. Key size nevertheless affects encryption and decryption speed since the cost of these algorithms is exponential in the size of the key. Larger keys also take more time to generate and take more space to store. Ultimately, there are diminishing returns on the extra security a large key provides you. After all, if the key is



large enough to resist a brute-force attack, an eavesdropper will merely switch to some other method for obtaining your plaintext data. Examples of other methods include robbing your home or office and mugging you. 1024 bits is thus the recommended key size. If you genuinely need a larger key size then you probably already know this and should be consulting an expert in data security.

13.11.4 Protecting Your Private Key

Protecting your private key is the most important job you have to use GnuPG correctly. If someone obtains your private key, then all data encrypted to the private key can be decrypted and signatures can be made in your name. If you lose your private key, then you will no longer be able to decrypt documents encrypted to you in the future or in the past, and you will not be able to make signatures. Losing sole possession of your private key is catastrophic.

Regardless of how you use GnuPG you should store the public key's ‘revocation certificate’ and a backup of your private key on write-protected media in a safe place. For example, you could burn them on a CD-ROM and store them in your safe deposit box at the bank in a sealed envelope. Alternatively, you could store them on a floppy and hide it in your house. Whatever you do, they should be put on media that is safe to store for as long as you expect to keep the key, and you should store them more carefully than the copy of your private key you use daily.

To help safeguard your key, GnuPG does not store your raw private key on disk. Instead it encrypts it using a symmetric encryption algorithm. That is why you need a passphrase to access the key. Thus there are two barriers an attacker must cross to access your private key: (1) he must actually acquire the key, and (2) he must get past the encryption.

Safely storing your private key is important, but there is a cost. Ideally, you would keep the private key on a removable, write-protected disk such as a floppy disk, and you would use it on a single-user machine not connected to a network. This may be inconvenient or impossible for you to do. For example, you may not own your own machine and must use a computer at work or school, or it may mean you have to physically disconnect your computer from your network every time you want to use GnuPG.



This does not mean you cannot or should not use GnuPG. It means only that you have decided that the data you are protecting is important enough to encrypt but not so important as to take extra steps to make the first barrier stronger. It is your choice.

A good passphrase is absolutely critical when using GnuPG. Any attacker who gains access to your private key must bypass the encryption on the private key. Instead of brute-force guessing the key, an attacker will almost certainly instead try to guess the passphrase.

The motivation for trying passphrases is that most people choose a passphrase that is easier to guess than a random 128-bit key. If the passphrase is a word, it is much cheaper to try all the words in the dictionaries of the world's languages. Even if the word is permuted, e.g., k3wldood, it is still easier to try dictionary words with a catalog of permutations. The same problem applies to quotations. In general, passphrases based on natural-language utterances are poor passphrases since there is little randomness and lots of redundancy in natural language. You should avoid natural language passphrases if you can.

A good passphrase is one that you can remember but is hard for someone to guess. It should include characters from the whole range of printable characters on your keyboard. This includes uppercase alphabetic characters, numbers, and special characters such as } and |. Be creative and spend a little time considering your passphrase; a good choice is important to ensure your privacy.



13.11.5 Selecting Expiration Dates and Using Sub Keys

By default, a DSA master signing key and an ElGamal encryption sub key are generated when you create a new key pair. This is convenient, because the roles of the two keys are different, and you may therefore want the keys to have different lifetimes. The master signing key is used to make digital signatures, and it also collects the signatures of others who have confirmed your identity. The encryption key is used only for decrypting encrypted documents sent to you. Typically, a digital signature has a long lifetime, e.g., forever, and you also do not want to lose the signatures on your key that you worked hard to collect. On the other hand, the encryption sub key may be changed periodically for extra security, since if an encryption key is broken, the attacker can read all documents encrypted to that key both in the future and from the past.

It is almost always the case that you will not want the master key to expire. There are two reasons why you may choose an expiration date. First, you may intend for the key to have a limited lifetime. For example, it is being used for an event such as a political campaign and will no longer be useful after the campaign is over or for use with a customer contract with a set completion or termination date. Another reason is that if you lose control of the key and do not have a revocation certificate with which to revoke the key, having an expiration date on the master key ensures that the key will eventually fall into disuse.

Changing encryption sub keys is straightforward but can be inconvenient. If you generate a new key pair with an expiration date on the sub key, then that sub key will eventually expire. Shortly before the expiration you will add a new sub key and publish your updated public key. Once the sub key expires, those who wish to correspond with you must find your updated key since they will no longer be able to encrypt to the expired key. This may be inconvenient depending on how you distribute the key. Fortunately, however, no extra signatures are necessary since the new sub key will have been signed with your master signing key, which presumably has already been validated by your correspondents.

The inconvenience may or may not be worth the extra security. Just as you can, an attacker can still read all documents encrypted to an expired sub key. Changing sub keys only protects future documents. In order to read documents encrypted to the new sub key, the attacker would need to mount a new attack using whatever techniques he used against you the first time.



Finally, it only makes sense to have one valid encryption sub key on a key ring. There is no additional security gained by having two or more active sub keys. There may of course be any number of expired keys on a key ring so that documents encrypted in the past may still be decrypted, but only one sub key needs to be active at any given time.

13.11.6 Key Integrity

When you distribute your public key, you are distributing the public components of your master and subordinate keys as well as the user IDs. Distributing this material alone, however, is a security risk since it is possible for an attacker to tamper with the key. The public key can be modified by adding or substituting keys, or by adding or changing user IDs. By tampering with a user ID, the attacker could change the user ID's email address to have email redirected to himself. By changing one of the encryption keys, the attacker would also be able to decrypt the messages redirected to him.

Using digital signatures is a solution to this problem. When data is signed by a private key, the corresponding public key is bound to the signed data. In other words, only the corresponding public key can be used to verify the signature and ensure that the data has not been modified. A public key can be protected from tampering by using its corresponding private master key to sign the public key components and user IDs, thus binding the components to the public master key. Signing public key components with the corresponding private master signing key is called self-signing, and a public key that has self-signed user IDs bound to it is called a certificate.



As an example, Chloe has two user IDs and three sub keys. The signatures on the user IDs can be checked with the command check from the key edit menu.

chloe% gpg --edit-key chloe Secret key is available. pub 1024D/26B6AAE1 created: 1999-06-15 expires: never trust: -/u sub 2048g/0CF8CB7A created: 1999-06-15 expires: never sub 1792G/08224617 created: 1999-06-15 expires: 2002-06-14 sub 960D/B1F423E7 created: 1999-06-15 expires: 2002-06-14 (1) Chloe (Jester) <[email protected]> (2) Chloe (Plebian) <[email protected]> Command> check uid Chloe (Jester) <[email protected]> sig! 26B6AAE1 1999-06-15 [self-signature] uid Chloe (Plebian) <[email protected]> sig! 26B6AAE1 1999-06-15 [self-signature] As expected, the signing key for each signature is the master signing key with key ID 0x26B6AAE1. The self-signatures on the sub keys are present in the public key, but they are not shown by the GnuPG interface.



14141414 MANUAL TRANSFERSMANUAL TRANSFERSMANUAL TRANSFERSMANUAL TRANSFERS

In addition to the automated data transfer that SFTPPlus Client provides, you can also perform manual data transfers or transfer testing. This chapter outlines the programs used to perform these operations, their parameters and a brief example.

14.1 SFTP

To perform a SFTP transfer, you would use the program psftp.exe. This program is located in the \SFTPPlus\Client directory for Windows and /opt/SFTPPlus/bin/ for Linux/Unix.

14.1.1 SFTP Usage

Command line usage is as follows;

psftp [options] [user@]host

Where;

[options] are the parameters required (as appropriate) list in the table below.

[user] is the username to be used for remote computer.

host is the IP address or name of the remote computer.

14.1.2 Starting PSFTP

The usual way to start PSFTP is from a command prompt, much like PSCP. To do this, it will need either to be on your PATH or in your current directory. Unlike PSCP, however, PSFTP has no complex command-line syntax; you just specify a host name and perhaps a user name: psftp server.example.com

Or perhaps

psftp [email protected]

Alternatively, if you just type psftp on its own you will see the PSFTP prompt, and a message telling you PSFTP has not connected to any server. For example in Windows, you would see;



C:\>psftp psftp: no hostname specified; use "open host.name" to connect psftp>

At this point you can type;

psftp> open server.example.com

Or;

psftp> open [email protected]

to start a session.

14.1.3 PSFTP start-up parameters

The following sections describe the various PSFTP command-line options.

-l

The -l option is an alternative way to specify the user name to log in as, on the command line. Instead of typing psftp user@host , you can also type;

psftp> host -l user

This option does not work in the open command once PSFTP has started.

-P If the host you specify is a saved session, PSFTP uses any port number specified in that saved session. If not, PSFTP uses the default SSH port, 22. The -P option allows you specify the port number to connect to for the PSFTP SSH connection.

-v

The -v option to PSFTP makes it print verbose information about the establishing of the SSH connection. The information displayed is equivalent to what is shown in the PuTTY Event Log.

This information may be useful for debugging problems with PSFTP.

-pw If a password is required to connect to the host, PSFTP will interactively



prompt you for it. However, this may not always be appropriate. If you are running PSFTP as part of some automated job, it will not be possible to enter a password by hand. The -pw option to PSFTP lets you specify the password to use on the command line.

Since specifying passwords in scripts is a bad idea for security reasons, you might want instead to consider using public-key authentication.

-b In normal operation, PSFTP is an interactive program which displays a command line and accepts commands from the keyboard.

If you need to do automated tasks with PSFTP, you would probably prefer to specify a set of commands in advance and have them executed automatically. The -b option allows you to do this. You use it with a file name containing batch commands. For example, you might create a file called myscript.scr containing lines like this:

cd /home/ftp/users/jeff del jam-old.tar.gz ren jam.tar.gz jam-old.tar.gz put jam.tar.gz chmod a+r jam.tar.gz quit

and then you could run the script by typing

psftp user@hostname -b myscript.scr

When you run a batch script in this way, PSFTP will abort the script if any command fails to complete successfully. To change this behaviour, you can use the -be option.

-bc The -bc option alters what PSFTP displays while processing a batch script. With the -bc option, PSFTP will display prompts and commands just as if the commands had been typed at the keyboard. So instead of seeing this:

Sent username "fred" Remote working directory is /home/fred Listing directory /home/fred/lib drwxrwsr-x 4 fred fred 1024 Sep 6 1 0:42 . drwxr-sr-x 25 fred fred 2048 Dec 14 0 9:36 .. drwxrwsr-x 3 fred fred 1024 Apr 17 2000 jed lrwxrwxrwx 1 fred fred 24 Apr 17 2000 timber drwxrwsr-x 2 fred fred 1024 Mar 13 2000 trn



You might see this:

Sent username "fred" Remote working directory is /home/fred psftp> dir lib Listing directory /home/fred/lib drwxrwsr-x 4 fred fred 1024 Sep 6 1 0:42 . drwxr-sr-x 25 fred fred 2048 Dec 14 0 9:36 .. drwxrwsr-x 3 fred fred 1024 Apr 17 2000 jed lrwxrwxrwx 1 fred fred 24 Apr 17 2000 timber drwxrwsr-x 2 fred fred 1024 Mar 13 2000 trn psftp> quit

-be When running a batch file, this option causes PSFTP to continue processing even if a command fails to complete successfully.

You might want this to happen if you wanted to delete a file and didn't care if it was already not present, for example.

-batch If you use the -batch option, PSFTP will never give an interactive prompt while establishing the connection. If the server's host key is invalid, for example, then the connection will simply be abandoned instead of asking you what to do next.

This may help behaviour of PSFTP when it is used in automated scripts: using -batch, if something goes wrong at connection time, the batch job will fail rather than hang.

14.1.4 Running PSFTP

Once you have started your PSFTP session, you will see a psftp> prompt. You can now type commands to perform file-transfer functions. See section 'PSFTP Parameters' for a list of all the available commands.

If you type help, PSFTP will give a short list of the available commands. If you type help with a command name - for example, help get - then PSFTP will give a short piece of help on that particular command.



When you have finished your session, type the command quit to terminate PSFTP and return to the command line (or just close the PSFTP console window if you started it from the GUI). You can also use the bye and exit commands, which have exactly the same effect.

14.1.5 PSFTP quoting rules

Most PSFTP commands are considered by the PSFTP command interpreter as a sequence of words, separated by spaces. For example, the command ren oldfilename newfilename splits up into three words: ren (the command name), oldfilename (the name of the file to be renamed), and newfilename (the new name to give the file).

Sometimes you will need to specify file names that contain spaces. In order to do this, you can surround the file name with double quotes. This works equally well for local file names and remote file names:

psftp> get "spacey file name.txt" "save it under th is name.txt"

The double quotes themselves will not appear as part of the file names; they are removed by PSFTP and their only effect is to stop the spaces inside them from acting as word separators.

If you need to use a double quote (on some types of remote system, such as Unix, you are allowed to use double quotes in file names), you can do this by doubling it. This works both inside and outside double quotes. For example, this command

psftp> ren ""this"" "a file with ""quotes"" in it"

Will take a file whose current name is "this" (with a double quote character at the beginning and the end) and rename it to a file whose name is a file with "quotes" in it.

(The one exception to the PSFTP quoting rules is the ! command, which passes its command line straight to Windows without splitting it up into words at all.



14.1.6 PSFTP Examples

Here are a few PSFTP examples to illustrate how psftp.exe is used.

Scenario 1 To download a file from the remote server and store it on your local PC, run the executable psftps.exe (for Windows) or psftps (Linux/UNIX) and use the get command. In its simplest form, you just use this with a file name:

get myfile.dat

If you want to store the file locally under a different name, specify the local file name after the remote one:

get myfile.dat newname.dat

This will fetch the file on the server called myfile.dat, but will save it to your local machine under the name newname.dat.

Scenario 2 To upload a file to the server from your local PC, you use the put command. In its simplest form, you just use this with a file name:

put myfile.dat

If you want to store the file remotely under a different name, specify the remote file name after the local one:

put myfile.dat newname.dat

This will send the local file called myfile.dat, but will store it on the server under the name newname.dat.



14.1.7 PSFTP Parameters

Parameter Parameter Description

-V Print version information and exit

-pgpfp print PGP key fingerprints and exit

-b <file> Use specified batch-file

-bc Output batchfile commands

-be Do not stop batch file processing if errors

-v Show verbose messages

-load <sessname> Load settings from saved session

-l Connect with specified username

-P <port number> Connect to specified port, normally port 22 but can be a custom port number. Substitute <port number> for the port number required, for example;

-P 15022

-pw <passwd> Login with specified password

-1 Force use of SSH protocol version 1


-4 Force use of IPv4

-6 Force use of IPv6

-C Enable compression

-i <key> Private key file for authentication

-batch Disable all interactive prompts



14.1.8 PSFTP Session commands

There are several other commands (as well as from 'get' and 'put') that can be executed whilst in an interactive manual PSFTP session. A summary of these commands follows;

help If you type help, PSFTP will give a short list of the available commands. If you type help with a command name - for example,

psftp> help get

Then PSFTP will give a short piece of help on that particular command.

cd and pwd PSFTP maintains a notion of your "working directory" on the server. This is the default directory that other commands will operate on. For example, if you type get filename.dat then PSFTP will look for filename.dat in your remote working directory on the server. To change your remote working directory, use the cd command. To display your current remote working directory, type;

psftp> pwd.

lcp and lpwd As well as having a working directory on the remote server, PSFTP also has a working directory on your local machine (just like any other Windows process). This is the default local directory that other commands will operate on. For example, if you type get filename.dat then PSFTP will save the resulting file as filename.dat in your local working directory. To change your local working directory, use the lcd command. To display your current local working directory, type;

psftp> lpwd.

reget and reput



If a file transfer fails half way through, and you end up with half the file stored on your disk, you can resume the file transfer using the reget and reput commands. These work exactly like the get and put commands, but they check for the presence of the half-written destination file and start transferring from where the last attempt left off. The syntax of reget and reput is exactly the same as the syntax of get and put:

psftp> reget myfile.dat psftp> reget myfile.dat newname.dat

dir This command will list the files in your remote working directory, just type dir. You can also list the contents of a different directory by typing dir followed by the directory name:

psftp> dir /home/fred psftp> dir sources

The ls command works exactly the same way as dir.

chmod PSFTP allows you to modify the file permissions on files on the server. You do this using the chmod command, which works very much like the UNIX chmod command. The basic syntax is chmod modes file, where modes represents a modification to the file permissions, and file is the filename to modify.

For example:

psftp> chmod go-rwx,u+w privatefile psftp> chmod a+r publicfile psftp> chmod 640 groupfile

The modes parameter can be a set of octal digits in the UNIX style. (If you don't know what this means, you probably don't want to be using it!) Alternatively, it can be a list of permission modifications, separated by commas.



Each modification consists of:

• The people affected by the modification. This can be u (the owning user), g (members of the owning group), or o (everybody else - "others"), or some combination of those. It can also be a ("all") to affect everybody at once.

• A + or - sign, indicating whether permissions are to be added or removed.

• The actual permissions being added or removed. These can be r (permission to read the file), w (permission to write to the file), and x (permission to execute the file, or in the case of a directory, permission to access files within the directory).

So the above examples would do:

• The first example: go-rwx removes read, write and execute permissions for members of the owning group and everybody else (so the only permissions left are the ones for the file owner). u+w adds write permission for the file owner.

• The second example: a+r adds read permission for everybody.

In addition to all this, there are a few extra special cases for UNIX systems. On non-Unix systems these are unlikely to be useful:

• You can specify u+s and u-s to add or remove the UNIX set-user-ID bit. This is typically only useful for special purposes; refer to your UNIX documentation if you're not sure about it.

• You can specify g+s and g-s to add or remove the UNIX set-group-ID bit. On a file, this works similarly to the set-user-ID bit (see your UNIX documentation again); on a directory it ensures that files created in the directory are accessible by members of the group that owns the directory.

• You can specify +t and -t to add or remove the UNIX "sticky bit". When applied to a directory, this means that the owner of a file in that directory can delete the file (whereas normally only the owner of the directory would be allowed to).

del To delete a file on the server, type del and then the filename: psftp> del oldfile.dat

The rm command works exactly the same way as del.



mkdir To create a directory on the server, type mkdir and then the directory name:

psftp> mkdir newstuff

rmdir To remove a directory on the server, type rmdir and then the directory name psftp> rmdir oldstuff

Most SFTP servers will probably refuse to remove a directory if the directory has anything in it, so you will need to delete the contents first.

ren To rename a file on the server, type ren, then the current file name, and then the new file name: psftp> ren oldfile newname

The rename and mv commands work exactly the same way as ren.

ls To list the files in your remote working directory, enter the command ls . You can also list the contents of a different directory by typing dir followed by the directory name:

psftp> dir /home/fred psftp> dir sources

The ls command works exactly the same way as dir .

! You can run local Windows commands using the ! command. This is the only PSFTP command that is not subject to the command quoting rules as previously mentioned. If any command line begins with the ! character, then the rest of the line will be passed straight to Windows without further translation.



For example, if you want to move an existing copy of a file out of the way before downloading an updated version, you might type:

psftp> !ren myfile.dat myfile.bak psftp> get myfile.dat

using the Windows ren command to rename files on your local PC.

14.1.9 Important PSFTP Notes

1. There are parameters which are in upper and lower case, you must enter the correct case or your transfer will fail on a parameter error.



14.2 FTP/FTPS & HTTP/HTTPS

To perform an FTP or FTPS manual transfer, you would use the program curl.exe (known as cURL). You can also perform a transfer for HTTP or HTTPS using curl. This program is located in the \SFTPPlus\Client directory for Windows and /opt/SFTPPlus/bin/ for Linux/Unix.

14.2.1 cURL Usage


curl [options...] <url>

Where;

[options] are the parameters required (as appropriate) listed in the table below.

<URL> is the username to be used for remote computer.

14.2.2 Starting cURL The usual way to start cURL is from a command prompt. To do this, it will need either to be on your PATH or in your current directory. CURL has a complex command-line syntax. This is because it can provide transport services for FTP(S) and HTTP(S). The parameters are shown in the table below and indicate which protocol each parameter can be used with. In its simplest form, to get a HTML page, enter the following; curl http://ww.example.com/

14.2.3 cURL Start-up Parameters

Here are the main start-up parameters;

-G

Get a file.

-o <file>

Write output file instead of stdout

-O



Write output to a file named as the remote file.

-P <port>

Use <port> with address instead of PASV

-T <file>

Upload the file specified in <file> parameter.

-v

Verbose mode, show all messages on screen

-V

Show version and quit

14.2.4 Running cURL

CURL must be run on one command line, there is no batch parameter that commands can be called from to execute file transfers. The next section includes some of the more common uses of cURL for FTP and HTTP file transfers.

14.2.5 cURL Examples

This section provides examples of using cURL with FTP and HTTP uploads and downloads. We have only provided a few examples here as there as so many possible permutations it would not be practical to list most of them.

Scenario 1 Uploading

FTP Upload all data on stdin to a specified ftp site:

curl -T - ftp://ftp.upload.com/myfile

Upload data from a specified file, login with user and password:

curl -T uploadfile -u user:passwd ftp://ftp.upload. com/myfile

Upload a local file to the remote site, and use the local file name remote too:



curl -T uploadfile -u user:passwd ftp://ftp.upload. com/

Upload a local file to get appended to the remote file using ftp:

curl -T localfile -a ftp://ftp.upload.com/remotefil e

Curl also supports ftp upload through a proxy, but only if the proxy is configured to allow that kind of tunnelling. If it does, you can run curl in a fashion similar to:

curl --proxytunnel -x proxy:port -T localfile ftp.u pload.com

HTTP Upload all data on stdin to a specified http site:

curl -T - http://www.upload.com/myfile

Note that the http server must have been configured to accept PUT before this can be done successfully.

Scenario 2

Downloading

FTP To ftp files using name and password, include them in the URL like:

curl ftp://name:[email protected]:port/full/pat h/to/file Or specify them with the -u flag like curl -u name:passwd ftp://machine.domain:port/full/ path/to/file FTPS It is just like for FTP, but you may also want to specify and use SSL-specific options for certificates etc. Note that using FTPS:// as prefix is the "implicit" way as described in the standards while the recommended "explicit" way is done by using FTP:// and the --ftp-ssl option.

HTTP



Curl also supports user and password in HTTP URLs, thus you can pick a file like: curl http://name:[email protected]/full/path/to /file Or specify user and password separately like in curl -u name:passwd http://machine.domain/full/path /to/file HTTP offers many different methods of authentication and curl supports several: Basic, Digest, NTLM and Negotiate. Without telling which method to use, curl defaults to Basic. You can also ask curl to pick the most secure ones out of the ones that the server accepts for the given URL, by using --anyauth.

NOTE! Since HTTP URLs don't support user and password, you can't use that style when using Curl via a proxy. You must use the -u style fetch during such circumstances. HTTPS Probably most commonly used with host certificates but possibly also private certificates.

14.2.6 FTP(S) & HTTP(S) Parameters

Parameter Protocol Use

Short Long

Use only with FTP

Use only with

SSL

(FTPS

or

HTTPS)

Use only with

HTTP Parameter Description

-a --append √ Append to target file when uploading (F)

-A --user-agent <string> √ User-Agent to send to server (H)

--anyauth √ Pick "any" authentication method (H)

-b --cookie <name=string/file> √ Cookie string or file to read cookies from (H

--basic √ Use HTTP Basic Authentication (H)




Short Long

Use only with FTP

Use only with

SSL

(FTPS

or

HTTPS)

Use only with


-B --use-ascii Use ASCII/text transfer

-c --cookie-jar <file> √ Write cookies to this file after operation (H)

-C --continue-at <offset> Resumed transfer offset

-d --data <data> √ HTTP POST data (H)

--data-ascii <data> √ HTTP POST ASCII data (H)

--data-binary <data> √ HTTP POST binary data (H)

--negotiate √ Use HTTP Negotiate Authentication (H)

--digest √ Use HTTP Digest Authentication (H)

--disable-eprt √ Inhibit using EPRT or LPRT (F)

--disable-epsv √ Inhibit using EPSV (F)

-D --dump-header <file> Write the headers to this file

--egd-file <file> √ EGD socket path for random data (SSL)

--tcp-nodelay Use the TCP_NODELAY option

-e --referer √ Referer URL (H)

-E --cert <cert[:passwd]> √ Client certificate file and password (SSL)

--cert-type <type> √ Certificate file type (DER/PEM/ENG) (SSL)

--key <key> √ Private key file name (SSL)

--key-type <type> √ Private key file type (DER/PEM/ENG) (SSL)

--pass <pass> √ Pass phrase for the private key (SSL)

--engine <eng> Crypto engine to use (SSL). "--engine list" for list

--cacert <file> √ CA certificate to verify peer against (SSL)

--capath <directory> √ CA directory (made using c_rehash) to verify peer against (SSL)

--ciphers <list> √ SSL ciphers to use (SSL)




Short Long

Use only with FTP

Use only with

SSL

(FTPS

or

HTTPS)

Use only with


--compressed Request compressed response (using deflate or gzip)

--connect-timeout <seconds>

Maximum time allowed for connection

--create-dirs Create necessary local directory hierarchy

--crlf Convert LF to CRLF in upload

-f --fail √ Fail silently (no output at all) on HTTP errors (H)

--ftp-create-dirs √ Create the remote dirs if not present (F)

--ftp-pasv √ Use PASV/EPSV instead of PORT (F)

--ftp-skip-pasv-ip √ Skip the IP address for PASV (F)

--ftp-ssl √ Enable SSL/TLS for the ftp transfer (F)

-F --form <name=content> √ Specify HTTP multipart POST data (H)

-- form-string <name=string>

√ Specify HTTP multipart POST data (H)

-g --globoff Disable URL sequences and ranges using {} and []

-G --get √ Send the -d data with a HTTP GET (H)

-h --help Will display this help text

-H --header <line> √ Custom header to pass to server (H)

--ignore-content-length Ignore the HTTP Content-Length header

-i --include √ √ Include protocol headers in the output (H/F)

-I --head Show document info only

-j --junk-session-cookies √ Ignore session cookies read from file (H)




Short Long

Use only with FTP

Use only with

SSL

(FTPS

or

HTTPS)

Use only with


--interface <interface> Specify network interface to use

--krb4 <level> √ Enable krb4 with specified security level (F)

-k --insecure √ Allow connections to SSL sites without certs (H)

-K /--config Specify which config file to read

-l --list-only √ List only names of an FTP directory (F)

--limit-rate <rate> Limit transfer speed to this rate

-L --location √ Follow Location: hints (H)

--location-trusted √ Follow Location: and send authentication even to other hostnames (H)

-m --max-time <seconds> Maximum time allowed for the transfer

--max-redirs <num> √ Maximum number of redirects allowed (H)

--max-filesize <bytes> √ √ Maximum file size to download (H/F)

-M --manual Display the full manual

-n --netrc Must read .netrc for user name and password

--netrc-optional Use either .netrc or URL; overrides -n

--ntlm √ Use HTTP NTLM authentication (H)

-N --no-buffer Disable buffering of the output stream

-o --output <file> Write output to <file> instead of stdout

-O --remote-name Write output to a file named as the remote file

-p --proxytunnel Operate through a HTTP proxy tunnel (using CONNECT)




Short Long

Use only with FTP

Use only with

SSL

(FTPS

or

HTTPS)

Use only with


--proxy-anyauth √ Pick "any" proxy authentication method (H)

--proxy-basic √ Use Basic authentication on the proxy (H)

--proxy-digest √ Use Digest authentication on the proxy (H)

--proxy-ntlm √ Use NTLM authentication on the proxy (H)

-P --ftp-port <address> √ Use PORT with address instead of PASV (F)

-q If used as the first parameter disables .curlrc

-Q --quote <cmd> √ Send command(s) to server before file transfer (F)

-r --range <range> Retrieve a byte range from a HTTP/1.1 or FTP server

--random-file <file> √ File for reading random data from (SSL)

-R --remote-time Set the remote file's time on the local output

--retry <num> Retry request <num> times if transient problems occur

--retry-delay <seconds> When retrying, wait this many seconds between each

--retry-max-time <seconds>

Retry only within this period

-s --silent Silent mode. Don't output anything

-S --show-error Show error. With -s, make curl show errors when they occur

--socks <host[:port]> Use SOCKS5 proxy on given host + port

--stderr <file> Where to redirect stderr. - means




Short Long

Use only with FTP

Use only with

SSL

(FTPS

or

HTTPS)

Use only with


stdout

-t --telnet-option <OPT=val> Set telnet option

--trace <file> Write a debug trace to the given file

--trace-ascii <file> Like --trace but without the hex output

--trace-time Add time stamps to trace/verbose output

-T --upload-file <file> Transfer <file> to remote site

--url <URL> Set URL to work with

-u --user <user[:password]> Set server user and password

-U --proxy-user <user[:password]>

Set proxy user and password

-v --verbose Make the operation more talkative

-V --version Show version number and quit

-w --write-out [format] What to output after completion

-x --proxy <host[:port]> Use HTTP proxy on given port

-X --request <command> Specify request command to use

-y --speed-time Time needed to trig speed-limit abort. Defaults to 30

-Y --speed-limit Stop transfer if below speed-limit for 'speed-time' secs

-z --time-cond <time> Transfer based on a time condition

-0 --http1.0 √ Use HTTP 1.0 (H)

-1 --tlsv1 √ Use TLSv1 (SSL)

-2 --sslv2 √ Use SSLv2 (SSL)

-3 --sslv3 √ Use SSLv3 (SSL)

--3p-quote √ Like -Q for the source URL for 3rd party transfer (F)

--3p-url √ source URL to activate 3rd party transfer (F)




Short Long

Use only with FTP

Use only with

SSL

(FTPS

or

HTTPS)

Use only with


--3p-user √ user and password for source 3rd party transfer (F)

-4 --ipv4 Resolve name to IPv4 address

-6 --ipv6 Resolve name to IPv6 address

-# --progress-bar Display transfer progress as a progress bar

14.2.7 Important cURL Notes

1. There are parameters which are in upper and lower case, you must enter the correct case or your transfer will fail on a parameter error.

2. If curl fails where it isn't supposed to, if the servers don't let you in, if you can't understand the responses: use the -v flag to get verbose fetching. cURL will output a lot of information, and what it sends and receives in order to let the user see all client-server interaction (but it won't show you the actual data).

curl -v ftp://ftp.upload.com/

To get even more details and information on what curl does, try using the --trace or --trace-ascii options with a given file name to log to, like this:

curl --trace trace.txt www.domain.com

Then edit the trace output file, trace.txt in the above example and view the output.

14.3 SCP

To perform an SCP transfer, you would use the program pscp.exe. This program is located in the \SFTPPlus\Client directory for Windows or /opt/SFTPPlus/bin/ for Linux/Unix



14.3.1 PSCP Usage


pscp [options] [user@]host:source target pscp [options] source [source...] [user@]host:targe t

Where;

[options] are the parameters listed in the table below headed “SCP Parameters” .

[user] is the username to be used.

host is the IP address or name of the remote computer.

source is the source directory (if required) and file(s)

target is the directory and or file name on the remote computer.

14.3.2 Starting PSCP PSCP is a command line application. This means that you cannot just double-click on its icon to run it and instead you have to bring up a console window or terminal window in Linux/UNIX. With Windows XP and 2000 it is called a ‘Command Prompt’. It should be available from the Programs section of your Start Menu. To start PSCP it will need either to be on your PATH or in your current directory.

In Microsoft Windows, you can the directory containing PSCP to your PATH environment variable (user or system). To add this for a user, type into the console window:

set PATH=C:\path\to\putty\directory;%PATH%

This will only work for the lifetime of that particular console window. To set your PATH more permanently on Windows XP, use the Environment tab of the System Control Panel.

14.3.3 PSCP Parameters These are the command line options that PSCP accepts.



-p By default, files copied with PSCP are time stamped with the date and time they were copied. The -p option preserves the original timestamp on copied files.

-q By default, PSCP displays a meter displaying the progress of the current transfer:

mibs.tar | 168 kB | 84.0 kB/s | ETA: 00 :00:13 | 13%

The fields in this display are (from left to right), filename, size (in kilobytes) of file transferred so far, estimate of how fast the file is being transferred (in kilobytes per second), estimated time that the transfer will take to complete, and the percentage of the file so far transferred. The -q option to PSCP suppresses the printing of these statistics.

-r By default, PSCP will only copy files. Any directories you specify to copy will be skipped, as will their contents. The -r option tells PSCP to act recursively into any directories you specify, and to copy them and their contents. This allows you to use PSCP to transfer whole directory structures between machines.

-batch If you use the -batch option, PSCP will never give an interactive prompt while establishing the connection. If the server's host key is invalid then the connection will simply be abandoned instead of asking you what to do next.

This may help PSCP's behaviour when it is used in automated scripts: using -batch, if something goes wrong at connection time, the batch job will fail rather than hang.

-v If you require verbose messages, the option -v will provide interactive messages.

-P <port>

This option allows you to specify a port number for the connection session. Substitute <port> with the port number required, for example 15022



-pw <passw>

This option will login with specified password.

-C This will enable compression on the transfer. -i <key>

Use a private key for authentication. The key <key> must be entered with the full directory location and filename or be located in the same directory as PSCP.

-noagent This will disable the use of Pageant (Windows only).

-agent This will enable the use of Pageant (Windows only).

-sftp or;

-scp There are two different file transfer protocols in use with SSH. Despite its name, PSCP (like many other ostensible scp clients) can use either of these protocols.

The older SCP protocol does not have a written specification and leaves a lot of detail to the server platform. Wildcards are expanded on the server. The simple design means that any wildcard specification supported by the server platform (such as brace expansion) can be used, but also leads to interoperability issues such as with filename quoting (for instance, where filenames contain spaces).

The newer SFTP protocol, which is usually associated with SSH 2 servers, is specified in a more platform independent way, and leaves issues such as wildcard syntax up to the client. This makes it more consistent across platforms, more suitable for scripting and automation, and avoids security issues with wildcard matching.



Normally PSCP will attempt to use the SFTP protocol, and only fall back to the SCP protocol if SFTP is not available on the server.

The -scp option forces PSCP to use the SCP protocol or quit.

The -sftp option forces PSCP to use the SFTP protocol or quit. When this option is specified, PSCP looks harder for an SFTP server...

14.3.4 Running PSCP Once you have a console window to type into, you can enter pscp on its own to bring up a usage message. This tells you the version of PSCP you're using, and gives you a brief summary of how to use PSCP: c:\SFTPPlus\Client>pscp PuTTY Secure Copy client Release SFTPPlus_1.5.0 Usage: pscp [options] [user@]host:source target pscp [options] source [source...] [user@]hos t:target pscp [options] -ls [user@]host:filespec Options: -p preserve file attributes -q quiet, don't show statistics -r copy directories recursively -v show verbose messages -load sessname Load settings from saved session -P port connect to specified port -l user connect with specified username -pw passw login with specified password -1 -2 force use of particular SSH protocol ve rsion -C enable compression -i key private key file for authentication -batch disable all interactive prompts -unsafe allow server-side wildcards (DANGEROUS) -V print version information -sftp force use of SFTP protocol -scp force use of SCP protocol

The PSCP interface is much like the UNIX scp command, if you're familiar with that.



14.3.5 PSCP Examples

Scenario 1 To receive (a) file(s) from a remote server:

So to 'get' the file /etc/hosts from the server example.com as user fred to the file c:\temp\example-hosts.txt, you would type; pscp [email protected]:/etc/hosts c:\temp\example-ho sts.txt

Scenario 2 To send (a) file(s) to a remote server: To copy the local file c:\documents\foo.txt to the server example.com as user fred to the file /tmp/foo you would type;

pscp c:\documents\foo.txt [email protected]:/tmp/foo

You can use wildcards to transfer multiple files in either direction, like this; pscp c:\documents\*.doc [email protected]:docfiles

pscp [email protected]:source/*.c c:\source



14.3.6 PSCP Parameters

Parameter Parameter Description

-V Print version information and exit

-pgpfp Print PGP key fingerprints and exit

-p Preserve file attributes

-q Quiet, don't show statistics

-r Copy directories recursively

-v Show verbose messages

-load <sessname> Load settings from saved session

-P port Connect to specified port

-l <user> Connect with specified username

-pw <passw> Login with specified password



-4 Force use of IPv4 or IPv6

-6 Force use of IPv4 or IPv6

-C Enable compression

-i key Private key file for authentication

-batch Disable all interactive prompts

-unsafe Allow server-side wildcards (DANGEROUS)

-sftp Force use of SFTP protocol

-scp Force use of SCP protocol



14.3.7 Important PSCP Notes

1. Please note that there are parameters which are in upper and lower case, you must enter the correct case or your transfer will fail on a parameter error.

2. In the second example scenario (using a wildcard for multiple remote files) you may see a warning saying something like this;

‘Warning: remote host tried to write to a file call ed 'terminal.c' when we requested a file called '*.c'. If this is a wildcard, consider upgrading to SSH 2 or using the '-unsafe' option. R enaming of this file has been disallowed’. This is due to a fundamental insecurity in the old-style SCP protocol: the client sends the wildcard string (*.c) to the server, and the server sends back a sequence of file names that match the wildcard pattern. However, there is nothing to stop the server sending back a different pattern and writing over one of your other files: if you request *.c, the server might send back the file name AUTOEXEC.BAT and install a virus for you. Since the wildcard matching rules are decided by the server, the client cannot reliably verify that the filenames sent back match the pattern. PSCP will attempt to use the newer SFTP protocol (part of SSH 2) where possible, which does not suffer from this security flaw. If you are talking to an SSH 2 server which supports SFTP, you will never see this warning. (You can force use of the SFTP protocol, if available, with -sftp) If you really need to use a server-side wildcard with an SSH 1 server, you can use the -unsafe command line option with PSCP:

pscp -unsafe [email protected]:source/*.c c:\source

This will suppress the warning message and the file transfer will happen. However, you should be aware that by using this option you are giving the server the ability to write to any file in the target directory, so you should only use this option if you trust the server administrator not to be malicious (and not to let the server machine be cracked by malicious people).



15151515 TROUBLESHOOTINGTROUBLESHOOTINGTROUBLESHOOTINGTROUBLESHOOTING

15.115.115.115.1 HelpHelpHelpHelp

15.1.1 Debug Mode

There are a few diagnostics methods available to you if things go wrong. Whilst there is not enough time to list them all here, we can provide some information as to a logical method in diagnosing transfer trouble.

General.

� When an automated transfer fails, check the message.log file for error codes. These are shown as severity classification 'E' (Error) or 'S' (Severe). With the help text of the error number, this often will provide clues as to the nature of the issue.

� Compare the error message(s) contained in the message.log file with its description as described in the 'SFTPPlus Client Message List' sub-section. The help text there provides an indication of the reason for the error.

� When making changes, don't make too many – make one change, re-run the transfer to see if it works. If not, try another change. If you make too many changes and a transfer suddenly works, you won't know which change provided the answer.

� Keep a list of the actions you have made in an attempt to correct an issue. This can be valuable in helping us assist you with any problems that may arise.

� If in the message.log file it shows the transfer definition file as 'disabled' and ignores it – Check the parameter 'disabled' is set to no ('n'), for example;

disabled = 'n'

� Check the credentials used in the transfer definition file. The important ones to pay special attention to are;

1. Check you are using the correct protocol

2. Remote server IP address or hostname (or FQDN)

3. Remote server port number

4. Remote username and password

� If using SSH or SSL please check that you have the correct certificates and or private keys and these are referenced correctly in the transfer definition file. See the chapter 'Transfer Definition Conf File Parameters' for details.

� When performing a put, the source directory must already exist otherwise Error number 11 will be issued;

'Missing subdir parameter in |, ignoring'



SFTP Transfers.

� Q: Can't get an automated transfer to work, yet when I perform it manually it does.

1. Are you using the same account for the manual transfer as the automated one? Host fingerprints are stored on a user account basis so if you try a manual connection, for example with PuTTY, you should try the same logged on account (at the client end in both cases) when performing the automated transfer.

2. Check the logon credentials are correct – username and password.

3. Check the remote system credentials are correct.

4. Check the port number of the remote system is correct. This must match the port number you use with the 'port' parameter.

5. The SFTPPlus Daemon (Linux/UNIX) or Service (Windows) must be run by the same account that is running the automated transfer.

� Q: Are SFTP transfers always performed on port 22?

1. Normally yes, but the port that the remote server is using can vary. If the remote system is using port 22 for SSH connection traffic the port will be different. If you have any doubt regarding the port you should be using, you should get in touch with the administrators of the remote system and ask which port their server is listening for SFTP traffic.

FTP Transfers. When troubleshooting an FTP problem, it is best to be methodical and look into each variable, one at a time.

� Q: I cannot connect to a server after having connected successfully in the past.

1. If you connect even once, your FTP settings are correct. When the same settings connect only part of the time, the reason is usually a server that goes offline or busy traffic on the network.

2. If you have not managed to connect to an FTP server before and are not able to get in, check that the following are correct;

� Are you sure it's FTP you should be using?



� Are you using the correct server name or IP address?

� Are you connecting on the correct port?

� Are you using the correct username and/or password – check the caps lock key on the keyboard.

� Q: Are FTP transfers always performed on port 21?

1. Normally yes, but the port that the remote server is using can vary. If the remote system is using port 21 for SSL connection traffic (FTPS) the port is usually the same for FTP Explicit mode (port 21). However, FTP Implicit mode normally uses a different port (normally port 990 but could be different). If you have any doubt regarding the port you should be using, you should get in touch with the administrators of the remote system and ask which port their server is listening for SFTP traffic.

� If you believe all the above are correct, get in touch with the Administrator of the FTP system you are trying to connect to.

The output from these listings can be valuable if the need arises to send us more information.

15.1.2 Message Interpretation

It is often difficult to decipher messages provided by a system when something goes wrong. With SFTPPlus Client, we have made every effort to ensure that when something does go wrong, the software will alert you in a timely fashion with a meaningful message. Numerous tables in this document are devoted to list and describe error messages that SFTPPlus Client can report on.

In the first instance, most issues can be solved by checking the meaning of the error message given within the tables in this document. However, we do realise that we can't cover every eventuality. If you cannot work determine the cause of an issue and decide on a course of corrective action, send us an email. We are most willing to help.

15.1.3 As a Service or Manually? One of the best features of SFTPPlus Client is its ability to provide automated transfers with a high level of traceability. This feature requires the SFTPPlus



service (Windows) or daemon (Linux/UNIX) to be running as a background process. But with SFTPPlus Client you have the best of both worlds - the ability to perform manual/ad-hoc transfers, and a highly efficient automated system with logging facilities. With its flexible automation and logging abilities together with ease of installation and use, this difference sets SFTPPlus Client apart from the other products in the market.



16 SFTPPPLUS CLIENT ERROR MESSAGES

The messages issued by SFTPPlus and the other various systems are listed here for your convenience.

16.1 SFTPPlus Client Message Format

SFTPPlus Client provides a comprehensive messaging system to inform users of tasks being executed. The message.conf file contains message routing and description information for SFTPPlus Client to use. Message routing can be defined against the severity level and provides a flexible method of application information to users.

Please Note:

The SFTPPlus message file (message.conf) can be found in the SFTPPlus\client directory in Windows and the /opt/SFTPPlus/ directory in Linux /Unix and may contain a more up-to-date set of messages than this document.

SFTPPlus messages can be directed to several reporting destinations;

Destination Description

console Display if interactive, or piped output.

log Write to the message.log file.

eventlog (Windows only) Write to the Eventlog and (if configured) MS Tools.

email Send email as defined in global.conf file.

snmp Send SNMP alert – This feature is not available in version 1.5 and planned for future release.



A SFTPPlus message is classified as one of four severities. These are described in the following table;

Severity Classification

Description

I Information – Information message only, no action required.

W Warning – Warning message, some user action may be required.

E Error – This is a non fatal error and is either a system error or SFTPPlus task error but will not terminate the current process.

S Severe - This is normally a fatal error and is either a system failure or a SFTPPlus task error and will terminate the current process.

16.2 SFTPPlus Client Message List

Below is an expanded list of SFTPPlus Client system error message codes.

Message ID 0

Severity I

Text

Help Messages issued before processing the global.conf file

Message ID 1

Severity I

Text Configuration read, startup continues

Help The global.conf file has been processed and startup continues

Message ID 2

Severity S

Text Unable to find conf files

Help SFTPPlus has failed to find the required configuration files. Consult message.log and check the runtime path. This may also indicate a problem with semaphore locking.



Message ID 3

Severity E

Text STDERR

Help Error output from a command issued.

Message ID 4

Severity I

Text STDOUT

Help Output from a command issued.

Message ID 5

Severity I

Text Config file

Help Configuration file is being read

Message ID 6

Severity I

Text Setting:

Help Setting from a configuration file

Message ID 7

Severity E

Text Definition | disabled - ignoring

Help The definition is specifically disabled in the configuration file. The definition should be removed if not needed. It can be left as disabled if it may be required in future.

Message ID 8

Severity E

Text Unable to scan | - ignoring

Help A defined directory was not able to be scanned. Check the directory exists and is accessible to the SFTPPlus service.



Message ID 9

Severity E

Text Command was

Help Command used to test a directory

Message ID 10

Severity I

Text Adding | to monitoring list

Help The definition listed has been added to the list of active definitions

Message ID 11

Severity E

Text Missing subdir parameter in |, ignoring

Help A definition has no subdir parameter. Add the correct subdir parameter to the definition. This must point to a sub-directory of inbox.

Message ID 12

Severity I

Text Using server | for

Help The server specified for a transfer

Message ID 13

Severity E

Text Missing server parameter |, ignoring

Help No server was specified for a transfer - the target server must be specified.

Message ID 14

Severity I

Text Using port | for

Help The port specified for a transfer.



Message ID 15

Severity I

Text Using port 22 for

Help Using the default port (22) for sftp

Message ID 16

Severity I

Text Using user | for

Help The user specified for the remote system for a transfer

Message ID 17

Severity E

Text Missing user parameter

Help A userid must be specified for the target system

Message ID 18

Severity I

Text Using password provided for

Help The password provided will be used.

Message ID 19

Severity E

Text Missing password parameter

Help No password has been provided for the remote system. This must be the password for the specified user on the remote system.

Message ID 20

Severity I

Text Using saved profile | for

Help The specified PuTTY profile will be used.



Message ID 21

Severity E

Text Missing savedprofile parameter

Help No PuTTY profile has been specified. The profile will be created by using the putty.exe gui, and saving a connection definition.

Message ID 22

Severity I

Text Using target directory | for

Help The remote directory where transferred files will be placed.

Message ID 23

Severity E

Text Missing targetdir parameter

Help A remote directory must be specified for storing transferred files.

Message ID 24

Severity I

Text Using response file | for

Help A response file as specified will be retrieved after a transfer

Message ID 25

Severity E

Text Missing responsein parameter

Help A response file name must be specified. This can include %FNAME% and %FTYPE% for filename and type



Message ID 26

Severity I

Text Using response directory | for

Help The response file will be retrieved from the specified remote directory.

Message ID 27

Severity E

Text Missing responsedir parameter

Help A remote directory where the response file will be found must be specified

Message ID 28

Severity I

Text Using maxtry | for

Help The maximum times a transfer will be attempted before considering as a Permanent failure.

Message ID 29

Severity I

Text Using global maxtry | for

Help Using the global maxtry value for this transfer.

Message ID 30

Severity I

Text Using waittime | for

Help The time between transfer attempts in seconds.

Message ID 31

Severity I

Text Using global waittime | for

Help Using the global waittime for this transfer.



Message ID 32

Severity I

Text Using initialwait | for

Help The initial wait time before attempting to retrieve a response file. This is intended to allow for processing time between sending a file and the output being created remotely.

Message ID 33

Severity I

Text Using global initialwait | for

Help The global initial waittime will be used for this transfer.

Message ID 34

Severity I

Text Looking for files

Help SFTPPlus is starting a directory scan.

Message ID 35

Severity I

Text Checking

Help SFTPPlus is checking for files for the specified transfer.

Message ID 36

Severity E

Text Unable to scan directory

Help SFTPPlus has failed to scan a directory - please check following messages for details.

Message ID 37

Severity I

Text pausing

Help SFTPPlus is waiting for further files.



Message ID 38

Severity S

Text sleep interrupted

Help SFTPPlus has received a signal and will shut down

Message ID 39

Severity S

Text unreachable code

Help Debugging information. If this message appears, please contact Technical Support.

Message ID 40

Severity I

Text Checking file size

Help Checking the size of a file before transfer, to ensure that it is not still being written to.

Message ID 41

Severity I

Text filesize | bytes

Help Report on the size of a file to be transferred

Message ID 42

Severity I

Text creating checksum

Help The md5sum hash of the file is being created

Message ID 43

Severity I

Text Sending file

Help The file is being sent



Message ID 44

Severity I

Text psftp returned

Help Return code from psftp

Message ID 45

Severity E

Text Secure ftp error - please see

Help An error has occurred in a transfer, and the indicated file will include more information.

Message ID 46

Severity I

Text File sent OK.

Help A transfer has completed

Message ID 47

Severity I

Text Adding response to queue

Help A response file will be retrieved at the appropriate time

Message ID 48

Severity I

Text Checking for response file for

Help An attempt to retrieve a response file is in progress

Message ID 49

Severity W

Text Failed to obtain response for

Help A response file has not been retrieved. This may indicate insufficient waittime.



Message ID 50

Severity I

Text Waiting | for response file for |, | attempts left

Help Information about the number of retries

Message ID 51

Severity I

Text Response file | for | transfer is available

Help A response file has been retrieved successfully

Message ID 52

Severity W

Text File Transfer message:

Help Report from a file transfer session.

Message ID 53

Severity I

Text Processing file | as

Help The original filename has had a timestamp added for uniqueness

Message ID 54

Severity I

Text Response received ok

Help A response file has been received

Message ID 55

Severity I

Text Preparing to send for

Help A file is being prepared for transfer



Message ID 56

Severity I

Text Waiting | to send file for |, | attempts left

Help Report on the number of retries for sending a file

Message ID 57

Severity I

Text Adding response to queue for

Help A response file transfer will be queued for later retrieval

Message ID 58

Severity E

Text Failed to send file for

Help transfer has failed - see following messages

Message ID 59

Severity E

Text Type | not supported, ignoring

Help An invalid transfer type has been specified, the transfer definition will not be used

Message ID 60

Severity E

Text Missing type parameter |, ignoring

Help No transfer type has been specified - the transfer definition will not be used

Message ID 61

Severity I

Text Transfer type | for

Help The specified transfer type will be used



Message ID 62

Severity I

Text md5sum will be sent for

Help The transfer will also include the md5sum file

Message ID 63

Severity I

Text md5sum will not be sent for

Help The transfer will not include the md5sum file

Message ID 64

Severity I

Text preprocess command for | is

Help The specified command will run before a transfer

Message ID 65

Severity I

Text no preprocess command for

Help There is no preprocess for a transfer

Message ID 66

Severity I

Text postprocess | command for | is:

Help The specified command will run after a transfer

Message ID 67

Severity I

Text no postprocess | command for

Help There is no postprocess for a transfer



Message ID 68

Severity I

Text Running | command for | ,

Help The specified command is being run

Message ID 69

Severity I

Text Command for | rc 0

Help The command had a return code of 0 (usually good)

Message ID 70

Severity W

Text Command for | rc

Help - The command had a return code other than 0 (usually bad)

Message ID 71

Severity I

Text Command for | stdout

Help The output for a command

Message ID 72

Severity W

Text Command for | stderr

Help The error messages for a command

Message ID 73

Severity S

Text Program interrupted, shutting down



Help An interrupt signal was received

Message ID 74

Severity S

Text SMTP Socket problem

Help A problem has occurred with a socket command for SMTP messaging. SMTP will be disabled

Message ID 75

Severity W

Text File still changing, postponing

Help A file in an inbox directory is still being updated, it will be retried later

Message ID 76

Severity I

Text Email messages for | will be sent to

Help The specified email address will receive messages related to this transfer

Message ID 77

Severity I

Text Email messages for | will be sent to default

Help The default global email address will receive messages related to this transfer

Message ID 78

Severity I

Text Failure writing file

Help A problem has occurred writing to a file. SFTPPlus will terminate



Message ID 79

Severity S

Text Failure reading file

Help A Problem has occurred reading from a file. SFTPPlus will terminate

Message ID 80

Severity I

Text md5sum will not be created for

Help No md5sum will be created for the transfer. This will reduce CPU load, but prevents use of the md5sum in the audit

Message ID 81

Severity I

Text Timestamp will not be used in the target filename

Help The target file name will not include the timestamp. This means that SFTPPlus will not be able to guarantee that files will not be overwritten

Message ID 82

Severity I

Text Timestamp will not be used in the local response filename

Help The local response file name will not include the timestamp. This means that SFTPPlus will not be able to guarantee that files will not be overwritten

Message ID 83

Severity I

Text Using remote directory | for

Help The remote directory where transfer files will be pulled from.

Message ID 84

Severity E

Text Missing remotedir parameter



Help A remote directory must be specified for pulling transfer files.

Message ID 85

Severity I

Text Using filename | for

Help The remote filename that will be pulled.

Message ID 86

Severity E

Text Missing remotefile parameter

Help A remote filename must be specified for pulling.

Message ID 87

Severity I

Text Using starttime | for

Help The starttime for pulling the file



17171717 REXX INTERPRETER

The processing engine of SFTPPlus Client is the Regina REXX interpreter. This section describes the use of the Regina interpreter, the SFTPPlus.rexx file and error codes that can be generated from the REXX interpreter. If you do receive Rexx Interpreter errors and you are unable to work out a solution, please get in touch with Pro:Atria technical support (see Technical Support for support information to collect and Contact Information for contact details).

These error codes are listed here for your convenience and would allow us to help troubleshoot if you have problems.

17.1 SFTPPlus.rexx

At the heart of SFTPPlus Client is the SFTPPlus.rexx file. The SFTPPlus.rexx file is a program file used by the Rexx interpreter. This performs the file transfer automation functions, audit logging and various facilities built within SFTPPlus Client. It also interfaces with ancillary programs that make up SFTPPlus Client 1.5 product.

17.1.1 Manual Running of SFTPPlus.rexx

The SFTPPlus.rexx file is run by entering the following command;

regina SFTPPlus.rexx <options> <parameter>

Options are;

Option Description

-h Shows help screen

-f <CONFFILE> Substitute <CONFFILE> to use a specified conf file instead of global.conf

-x TRANSFER, <FILE> Run a single defined send using <FILE>

-s <SERVICENAME> Specify service name (Windows only)

-g setting='value' Specify global setting, for example; -g !semignore='y'

encrypt <FILENAME> Encrypt a file called <FILENAME>

decrypt <FILENAME> Decrypt a file called <FILENAME>



Parameters are;

Parameter Description

With no parameter, run at console or as a daemon

start Start the service (Windows only)

stop Stop the service (via Windows stop) or daemon

install Install the service (Windows only)

remove Remove the service (Windows only)

post Stop the service (via program termination) or daemon

free Free stale mutex locks

wait Wait for mutex locks (debugging only)

Note:

1. Post will post the event semaphore that the program uses for waiting. This may not return immediately if a transfer or commend is in progress

2. Post and stop are identical for UNIX and Linux. For Windows, stop will invoke a call to the service controller which will in turn issue the post call



17.2 Rex Interpreter Error Messages

This section provides details on the message convention and error code descriptions that may be entered from the Rexx Interpreter. The errors report issues encountered within the SFTPPlus.rexx file which cannot be recovered; hence an error message is generated and reported. In such cases, we recommend that you get in touch with us providing as much detail as possible regarding the circumstance when the error occurred.

17.2.1 REXX Message Convention

The error codes comprise of two values;

1. Error code number

2. Error description

17.2.2 REXX Error Codes

Here are the descriptions that can be generated by SFTPPlus.rexx by the Regina Rexx interpreter. For Linux/UNIX these error messages would be displayed at the stdout device. For Windows, these would be listed in the Windows Application Event Log

Error Code Number

Error description

1

2

3

4 Program Interrupt

5 Machine resources exhausted

6 Unmatched “/*” or quote

7 WHEN or OTHERWISE expected



Error Code Number

Error description

8 Unexpected THEN or ELSE

9 Unexpected WHEN or OTHERWISE

10 Unexpected or unmatched END

11 Control stack full

12 Clause too long

13 Invalid character in program

14 Incomplete DO/SELECT/IF

15 Invalid hexadecimal or binary string

16 Label not found

17 Unexpected procedure

18 THEN expected

19 String or symbol expected

20 Symbol expected

21 Invalid data on end of clause

22 Invalid character string

23 Invalid data string

24 Invalid TRACE request

25 Invalid sub-keyword found

26 Invalid whole number

27 Invalid DO syntax

28 Invalid LEAVE or ITERATE

29 Environment name too long, or not found



Error Code Number

Error description

30 Name or string too long

31 Name starts with number or “.”

32

33 Invalid expression result

34 Logical value not 0 or 1

35 Invalid expression

36 Unmatched “(“ in expression

37 Unexpected “.” or “)”

38 Invalid template or pattern

39 Evaluation stack overflow (too many arguments)

40 Incorrect call to routine

41 Bad arithmetic conversion

42 Arithmetic overflow/underflow

43 Routine not found

44 Function did not return data

45 No data specified on function RETURN

46 Invalid variable reference

47

48 Failure in system service

49 Interpretation error

50



18 GLOBAL.CONF FILE PARAMETERS

This chapter provides a comprehensive list of parameters used in the global.conf file with additional information. These parameters control the behaviour of SFTPPlus Client whilst performing a transfer operation.

Category Parameter Default setting Description/Notes

Message settings

global.message

Path statement to location of message.conf file. This parameter should not be changed unless your message.conf file is located than specified in the default path installation.

global.smtpaddress Your SMTP email address.

global.msghost

Your SMTP mail host. This can be either the IP address or the long format name e.g. mail.domain.co.uk

global.smtptimeout

‘60’ Response time in seconds for SFTPPLus to stop communications with SMTP server if no response is received.

global.msgport

‘25’ TCP/IP port number for communicating with SMTP server. This is normally TCP port 25.

global.msgfrom

The email address that will appear in the email “From” field.

global.sftpplusaudit

Wait times global.maxtry

‘20’ Maximum number of attempts for SFTPPLus to try a file transfer.

global.waittime ‘10’ The maximum time in seconds to wait between file transfer




retries.

global.initialwait

‘20’ The initial wait time in seconds before attempting to retrieve a response file. This is intended to allow for processing time between sending a file and the output being created remotely.

global.directoryscantime

‘10’ Time in seconds to allow directory scanning on the local machine.

This parameter will make SFTPPlus client sleep for the specified number of seconds before performing a directory scan.

global.!timerunatstartup

N Set to Y to run timed transfers immediately at startup if time of day has already passed

global.!changechecktime

‘2’ Change the length of time that a file is checked for file size change. Time is specified as an integer in seconds

Working directories global.tmpdir mypath || 'tmp' || sepchar

Path used to define location of tmp directory.

global.inbox

mypath || 'inbox' || sepchar

Path used to define location of inbox directory.

global.outbox

mypath || 'outbox' || sepchar

Path used to define location of outbox directory.

global.archive

mypath || 'archive' || sepchar

Path used to define location of archive directory.

global.response

mypath || 'response' ||

sepchar

Path used to define location of response directory.




global.conf

mypath || 'conf' || sepchar

Path used to define location of conf directory.

global.retrydir mypath || 'retry' || sepchar

Path used to define location of retry directory.

global.faildir mypath || 'failed' || sepchar

Path used to define location of failed directory.

global.archive.subdir

Use a per transfer archive sub directory.

global.psftp mypath || 'psftp.exe'

Path to be used to locate psftp executable.

global.pscp mypath || 'pscp.exe'

Path to be used to locate pscp executable.

global.md5sum

mypath || 'md5sum.exe'

Path to be used to locate md5sum executable.

global.curl mypath || 'curl.exe'

Path used to locate curl executable.

gpg settings

global.gpg

mypath || 'gpg.exe'

Path used to locate gpg executable. We strongly suggest that you do not change this setting unless your gpg.exe does not exist in the SFTPPlus Client root directory.

global.gpgparams

'--yes --trust-mode always --batch --encrypt -

a -o - --passphrase-fd 0

-r'

Default gpg params to be used for file encryption if gpg encryption is invoked in transfer definition file.

global.gpgkeyphrase Passphrase for pgp private key

SNMP settings global.snmpsnmpname SFTPPlus

global.snmpversion 2 Snmp version number

global.snmppeername snpserver:162




global.snmpcommunity SFTPPlusClient Snmp community name

global.snmplocalname uname('N')

global.snmpspecifictype messagenum

global.snmpoid

'enterprises/ProAtria.proatriaSF

TPPlus'

global.snmpmibfile

Mypath || 'PROATRIA-SFTPPLUS-

MIB.txt'

Snmp file name – do not change

global.progressinterval

1 Allows the specification of the interval to be used to track the progress of a file transfer. The value is in seconds.

Special Use global.service SFTPPlus Denotes service name

global.!semprefix

use semaphore prefix, HOSTNAME will be replaced with the output from the hostname command

global.semignore

Ignore semaphore locks. Not in file by default, insert line;

global.semignore = ‘Y’

if you are having semiphore locking issues.

global.path Global path variable for SFTPPlus Client

global.sepchar

Global message separation character

global.!curldebug

0 Defines cURL debugging level where 0 = none (default)

and 7 = maximum

global.!curlopt Helps restrict output to STDERR on large files –




assists with issue mainly seen on AIX platform. Use '-s -S' as parameter to use this function.

Reserved global.!sys sys Reserved – do not use

global.!env env Reserved – do not use

global.!prog prog Reserved – do not use

global.!onceonly ' ' Reserved – do not use

global.!srcfile ' ' Reserved – do not use

global.!smtpmaxerr 1 Reserved – do not use

global.!smtperr 0 Reserved – do not use

global.!rexxre 0 Reserved – do not use

global.!curl 'lib' Reserved – do not use


global.conf boolean values should be in uppercase i.e. 'Y' or 'N'



19 TRANSFER DEFINITION CONF FILE PARAMETERS

This chapter provides a comprehensive list of parameters used in a conf file with additional information. These parameters control the behaviour of SFTPPlus Client whilst performing a transfer operation.

Rather than in the order that you will encounter them in a conf file, these parameters are in alphabetical order.

Parameter

Works with Put?

Works with Get?

Default setting

Description/Notes

archive √ 'y' Turn off copies to the archive directory ( 'n' ).

cacert √ √

When this parameter is set, SFTPPlus will accept a security certificate non-interactively. The parameter value must be the location and name of either a public or private certificate.

clientcert √ √ Optional parameter to specifiy client certificate file (for ftps only)

clientcertpass √ √

Optional parameter to specifiy client certificate file passphrase (for ftps only). Use with parameter ‘clientcert’

createmd5sum √ ‘y’ Create the local md5sum file.

customemail √ √

Custom template filename for use if sending as email attachment, replacable token names are; %DATE% %FILE% %MD5SUM% %SIZE% %TIME%

deleteaftertransfer √ After transfer the original file is deleted (get or get of response file only).

direction √ √ ‘put’

Direction of transfer, options are

- put (upload)

- get (download)

disabled √ √ ‘y’ Disable the transfer conf file. (All other values after this parameter in the conf file will be



Parameter

Works with Put?

Works with Get?

Default setting

Description/Notes

ignored).

emailbody √ √

Optional string to use as body of email for messages, can use %MSG% and %HELP% as replacable parameters for the message and help string from message.conf

emailsubject √ √

Optional string to use as body of email for messages, can use %MSG% and %HELP% as replacable parameters for the message and help string from message.conf

filemask √ Restrict files by mask, e.g. ‘*.pdf’ for all PDF file.

forcelowercase √ √ Forces use of lowercase filenames on case-insensitive platforms such as Windows.

ftpsmode √ √ explicit Specify ftpsmode = ‘implicit’. Only to be used when type = ‘ftps’.

getmd5sum √ ‘n’

Get an md5sum from the remote system (for example, <filename>.md5sum). This file must pre-exist on the remote system.

gpg √ √ Usepgp/gpg encryption / decryption with the email address specified here.

initialwait √ √

The initial wait time in seconds before attempting to retrieve a response file. This is intended to allow for processing time between sending a file and the output being created remotely.

keeponfail √ 'y' Option to not keep file(s) after a failed transfer ( 'n' ).

maxtry √ √ Number of times a transfer will be attempted before failing.

notifysuccess √ √ Send specific email on success. Use ‘y’ for default or specify filename for custom email,



Parameter

Works with Put?

Works with Get?

Default setting

Description/Notes

replacable token names are; %DATE% %FILE% %MD5SUM% %SIZE% %TIME% Use when not using email routing.

password √ √ Remote password associated with the remote user ID.

port √ √ ‘22’

The TCP/IP port number. Default options are;

- 22 (sftp ssh2)

- 21 (plain ftp)

- 80 (http)

- 443 (https)

postprocesssuccess √ √ Command to run after transfer succeeds.

postprocessfail √ √ Command to run after transfer fails. Use in conjunction with ‘maxtry’ parameter.

postprocessresponsefail √ √ Command to run if a response ‘get’ fails

postprocessresponsesuccess √ √ Command to run if a response ‘get’ succeeds

preprocess √ √ Specify a command to run before starting transfer.

recursive √

Enables directory recursive transfers. Takes recursive root from parameter ‘subdir’ for 'put' transfers or from parameter 'remotedir' with 'get' transfers.

remotedir √ Remote directory to get file from.

remotefile √ File to get.

response √ ‘n’ Enable a response file to be collected.

responsedir √

Directory name response file will be retrieved from. Directory must have forward slash at the end e.g.

responsedir = ‘results_download/’



Parameter

Works with Put?

Works with Get?

Default setting

Description/Notes

responsein √ Filename of the response file to be retrieved.

responseroot √ Use different location for response diretcory (default is ‘response’ under global root).

responsetimestamp √ ‘y’ Enable timestamp in response file name

runaftertransfer √(*) √(*)

Run a command after transfer. For example, to move a file from the upload directory to the directory ‘final’ use the format

runaftertransfer = ‘rename’ %file$ final/%file%

* Can only be used when type = ‘sftp’ or ‘ftp’ You can enter multiple commands separated by ';'

runbeforetransfer √(*) √(*)

Run a command before transfer. For example, to issue commands specific for IBM mainframe ftp;

runbeforetransfer = 'SITE REFCM=FB;SITE LRECL=80;SITE VOL=8;SITE PRIMARY=430:SITE SECONDARY=2000'

* Can only be used when type = ‘sftp’ or ‘ftp’ You can enter multiple commands separated by ';'

savedprofile √ √

The profile saved with PuTTY (Only required when type = ‘sftp’). When not using a saved PuTTY profile (for sftp), this parameter should be set to;

savedprofile = ‘*NOT USED*’

sendmd5sum √ ‘n’ Send an md5sum file with the main file.

server √ √ The name or IP address of the target server

smtpaddress √ √ SMTP address to be used for message notification (overrides



Parameter

Works with Put?

Works with Get?

Default setting

Description/Notes

setting global.smtpaddress in global.conf).

starttime √

Time to start a ‘get’ transfer using 24 hour clock, options are;

- hh:mm (at specified time)

- +hh:mm (at specified interval, e.g. +00:15 for fifteen minute intervals)

The value for this parameter must use the 24 hour clock format in the above specified mask layout.

subdir √ √ The name of the source (‘put’ transfer) or target (‘get’ transfer) sub-directory under Inbox.

suppressnomatcherror √ Don’t report no files as an error, Set to ‘y’

targetdir √ Remote target directory.

targettimestamp √ √ ‘y’ Add timestamp to file name to ensure unique file name.

transferroot √ √ response Use different location for inbox directory (default is ‘response’ under global root)

type √ √

Determines the protocol for the transfer. Options are

- type = ‘sftp’

- type = ‘ftp’

- type = ‘ftps’ – For implicit mode support contact Pro:Atria.

- type = ‘http’

- type = ‘https’

- type = ‘scp’

- type = ‘command’

(run a local



Parameter

Works with Put?

Works with Get?

Default setting

Description/Notes

command)

- type = ‘email’ (send transfer as email attachment)

user √ √ Remote user ID.

waittime √ √

Number of seconds between attempted transfers. Use in conjunction with maxtry parameter.


The Boolean values used in transfer definition file should be in lowercase i.e. 'y' or 'n'



20 PROTOCOL ERROR MESSAGES

These error codes are listed and described here for reference and your convenience. It may also help technical support at Pro:Atria to help diagnose issues that may arise.

20.1 SFTP Protocol Error Codes

Error Code

Error name Description

-1 SSH_ERROR_WRONG_MODE Attempt to call synchronous method in asynchronous mode and vice versa.

0 SSH_ERROR_OK Indicates successful completion of the operation

1 SSH_ERROR_EOF indicates end-of-file condition;

� Read: no more data is available in the file;

� ReadDirectory: no more files are contained in the directory.

2 SSH_ERROR_NO_SUCH_FILE A reference is made to a file which does not exist.

3 SSH_ERROR_PERMISSION_DENIED the authenticated user does not have sufficient permissions to perform the operation.

4 SSH_ERROR_FAILURE An error occurred for which there is no more specific error code defined.

5 SSH_ERROR_BAD_MESSAGE A badly formatted packet or protocol incompatibility is detected.

6 SSH_ERROR_NO_CONNECTION A pseudo-error which indicates that the client has no connection to the server.

7 SSH_ERROR_CONNECTION_LOST A pseudo-error which indicates that the connection to the server has been lost.

8 SSH_ERROR_OP_UNSUPPORTED An attempt was made to perform an operation which is not supported for the server.

9 SSH_ERROR_INVALID_HANDLE The handle value was invalid.

10 SSH_ERROR_NO_SUCH_PATH The file path does not exist or is invalid.



Error Code


11 SSH_ERROR_FILE_ALREADY_EXISTS The file already exists.

12 SSH_ERROR_WRITE_PROTECT The file is on read only media, or the media is write protected.

13 SSH_ERROR_NO_MEDIA The requested operation can not be completed because there is no media available in the drive.

14 SSH_ERROR_NO_SPACE_ON_FILESYSTEM The requested operation cannot be completed because there is no free space on the filesystem.

15 SSH_ERROR_QUOTA_EXCEEDED The operation cannot be completed because it would exceed the user's storage quota.

16 SSH_ERROR_UNKNOWN_PRINCIPAL A principal referenced by the request (either the 'owner', 'group', or 'who' field of an ACL), was unknown.

17 SSH_ERROR_LOCK_CONFLICT The file could not be opened because it is locked by another process.

18 SSH_ERROR_DIR_NOT_EMPTY The directory is not empty.

19 SSH_ERROR_NOT_A_DIRECTORY The specified file is not a directory.

20 SSH_ERROR_INVALID_FILENAME The filename is not valid.

21 SSH_ERROR_LINK_LOOP Too many symbolic links encountered.

22 SSH_ERROR_CANNOT_DELETE The file cannot be deleted. One possible reason is that the advisory READONLY attribute-bit is set.

23 SSH_ERROR_INVALID_PARAMETER On of the parameters was out of range, or the parameters specified cannot be used together.

24 SSH_ERROR_FILE_IS_A_DIRECTORY The specified file was a directory in a context where a directory cannot be used.

25 SSH_ERROR_BYTE_RANGE_LOCK_CONFLICT A read or write operation failed because another process's mandatory byte-range lock overlaps with the request.



Error Code


26 SSH_ERROR_BYTE_RANGE_LOCK_REFUSED A request for a byte range lock was refused.

27 SSH_ERROR_DELETE_PENDING An operation was attempted on a file for which a delete operation is pending.

28 SSH_ERROR_FILE_CORRUPT The file is corrupt; an filesystem integrity check should be run.

29 SSH_ERROR_OWNER_INVALID The principal specified can not be assigned as an owner of a file.

30 SSH_ERROR_GROUP_INVALID The principal specified can not be assigned as the primary group of a file.

100 SSH_ERROR_UNSUPPORTED_VERSION Sets of supported by client and server versions has no intersection.

102 SSH_ERROR_INVALID_PACKET Invalid packet was received.

103 SSH_ERROR_CONNECTION_CLOSED Connection is closed.



20.2 FTP Protocol Error Codes

Error Code


100 Series - Positive Preliminary Reply

(The user-process sending another command before the completion reply would be in violation of protocol; but server-FTP processes should queue any commands that arrive while a preceding command is in progress.) This type of reply can be used to indicate that the command was accepted and the user-process may now pay attention to the data connections, for implementations where simultaneous monitoring is difficult. The server-FTP process may send at most, one 1yz reply per command.

110 Restart marker reply. In this case, the text is exact and not left to the particular implementation; it must read: MARK yyyy = mmmm Where yyyy is User-process data stream marker, and mmmm server's equivalent marker (note the spaces between markers and "=").

120 Service ready in nnn minutes.

125 Data Connection already open, transfer starting.

150 File status okay, about to open data connection.

200 Series - Positive Completion reply

The requested action has been successfully completed. A new request may be initiated.

200 Command okay.

202 Command not implemented, superfluous at this site.

211 System status, or system help reply.

212 Directory status.

213 File status.

214 Help message. Help message on how to use the server or the meaning of a particular non-standard command. This reply is



Error Code


useful only to the human user.

215 NAME system type. NAME is an official system name from the list in the Assigned Numbers document.

220 Service ready for new user.

221 Service closing control connection. Logged out if appropriate.

225 Data connection open; no transfer in progress.

226 Closing data connection. Requested file action successful

For example; file transfer or file abort

227 Entering Passive Mode.

230 User logged in, proceed.

250 Requested file action okay, completed.

257 "PATHNAME" created.

300 Series - Positive Intermediate reply The command has been accepted, but the requested action is being held in abeyance, pending receipt of further information. The user should send another command specifying this information. This reply is used in command sequence groups.

331 User name okay, need password.

332 Need account for login.

350 Requested file action pending further information.

400 Series - Transient Negative Completion reply The command was not accepted and the requested action did not take place, but the error condition is temporary and the action may be requested again. The user should return to the beginning of the command sequence, if any. It is difficult to assign a meaning to "transient", particularly when two distinct sites (Server- and User-processes) have to agree on the interpretation. Each reply in the 4yz category might have a slightly different time value, but the intent is that the user-process is encouraged to try again. A rule of thumb in determining if a reply fits into the 4yz or the 5yz (Permanent Negative) category is that replies are 4yz if the commands can



Error Code


be repeated without any change in command form or in properties of the User or Server (e.g., the command is spelled the same with the same arguments used; the user does not change his file access or user name; the server does not put up a new implementation.)

421 Service not available, closing control connection.

This may be a reply to any command if the service knows it must shut down. This error may be due to service not available, closing control connection, user limit reached, or you are not authorized to make the connection, or the maximum number of connections have been exceeded.

425 Can't open data connection.

426 Connection closed; transfer aborted.

The command opens a data connection to perform an action, but that action is canceled, and the data connection is closed.

450 Requested file action not taken. File unavailable (e.g., file busy).

451 Requested action aborted: local error in processing.

452 Requested action not taken. Insufficient storage space in system.

500 Series - Permanent Negative Completion reply

The command was not accepted and the requested action did not take place. The User-process is discouraged from repeating the exact request (in the same sequence). Even some "permanent" error conditions can be corrected, so the human user may want to direct his user-process to reinitiate the command sequence by direct action at some point in the future (e.g., after the spelling has been changed, or the user has altered his directory status.)

501 Syntax error in parameters or arguments.

This may include errors such as command line too long.

502 Command not implemented. The server does not support this command.

503 Bad sequence of commands.

504 Command not implemented for that parameter.

530 Not logged in.



Error Code


532 Need account for storing files.

550 Requested action not taken. File unavailable

For example, file not found, no access.

552 Requested file action aborted. Exceeded storage allocation (for current directory or dataset).

553 Requested action not taken. File name not allowed.



20.3 FTPS Protocol Error Codes

Error Code


100 Series - Positive Preliminary Reply (The user-process sending another command before the completion reply would be in violation of the protocol; but server-FTP processes should queue any commands that arrive while a preceding command is in progress.) This type of reply can be used to indicate that the command was accepted and the user-process may now pay attention to the data connections, for implementations where simultaneous monitoring is difficult. The server-FTP process may send at most, one 1yz reply per command.

110 Restart marker reply. In this case, the text is exact and not left to the particular implementation; it must read: MARK yyyy = mmmm Where yyyy is User-process data stream marker, and mmmm server's equivalent marker (note the spaces between markers and "=").

120 Service ready in nnn minutes.

125 Data Connection already open, transfer starting.

150 File status okay, about to open data connection.

200 Series - Positive Completion reply

The requested action has been successfully completed. A new request may be initiated.

200 Command okay.

202 Command not implemented, superfluous at this site.

211 System status, or system help reply.



Error Code


212 Directory status.

213 File status.

214 Help message. Help message on how to use the server or the meaning of a particular non-standard command. This reply is useful only to the human user.

215 NAME system type. NAME is an official system name from the list in the Assigned Numbers document.

220 Service ready for new user.

221 Service closing control connection. Logged out if appropriate.

225 Data connection open; no transfer in progress.

226 Closing data connection. Requested file action successful

For example; file transfer or file abort

227 Entering Passive Mode.

230 User logged in, proceed.

235 Security data exchange has completed successfully

The security data exchange has completed successfully and does not require additional data.

250 Requested file action okay, completed.

257 "PATHNAME" created.

300 Series - Positive Intermediate reply The command has been accepted, but the requested action is being held in abeyance, pending receipt of further information. The user should send another command specifying this information. This reply is used in command sequence groups.

331 User name okay, need password.

332 Need account for login.

335 Server requires additional security data

The server has accepted the security data, and requires additional data.

350 Requested file action pending further information.



Error Code


400 Series - Transient Negative Completion reply The command was not accepted and the requested action did not take place, but the error condition is temporary and the action may be requested again. The user should return to the beginning of the command sequence, if any. It is difficult to assign a meaning to "transient", particularly when two distinct sites (Server- and User-processes) have to agree on the interpretation. Each reply in the 4yz category might have a slightly different time value, but the intent is that the user-process is encouraged to try again. A rule of thumb in determining if a reply fits into the 4yz or the 5yz (Permanent Negative) category is that replies are 4yz if the commands can be repeated without any change in command form or in properties of the User or Server (e.g., the command is spelled the same with the same arguments used; the user does not change his file access or user name; the server does not put up a new implementation.)

421 Service not available, closing control connection.

This may be a reply to any command if the service knows it must shut down. This error may be due to service not available, closing control connection, user limit reached, or you are not authorized to make the connection, or the maximum number of connections have been exceeded.

425 Can't open data connection.

426 Connection closed; transfer aborted.

The command opens a data connection to perform an action, but that action is cancelled, and the data connection is closed.

450 Requested file action not taken. File unavailable (e.g., file busy).

451 Requested action aborted: local error in processing.

452 Requested action not taken.



Error Code


Insufficient storage space in system.

500 Series - Permanent Negative Completion reply

The command was not accepted and the requested action did not take place. The User-process is discouraged from repeating the exact request (in the same sequence). Even some "permanent" error conditions can be corrected, so the human user may want to direct his user-process to re-initiate the command sequence by direct action at some point in the future (e.g., after the spelling has been changed, or the user has altered his directory status.)

501 Syntax error in parameters or arguments.

This may include errors such as command line too long.

502 Command not implemented. The server does not support this command.

503 Bad sequence of commands.

504 Command not implemented for that parameter.

530 Not logged in.

532 Need account for storing files.

535 Security data rejected Security data rejected, for example failed checksum.

550 Requested action not taken. File unavailable

For example, file not found, no access.

552 Requested file action aborted. Exceeded storage allocation (for current directory or dataset).

553 Requested action not taken. File name not allowed.



20.4 SCP Protocol Error Codes

Error Code


Host does not exist You may get this message when connecting to a server for following reasons:

• You may have typed a wrong hostname on login dialog (if using WinSCP) or defined an incorrect host in a transfer definition file.

• Your domain name is new and is not fully distributed to DNS servers yet.

• Connection was blocked by firewall. For local firewalls, particularly the one included in Windows XP SP2, note that the firewalls may not only block the port, but also a particular program (in this case, WinSCP).

Connection has been unexpectedly closed. Server sent command exit status 11

Status 11 is reported by OpenSSH SFTP server, when it encounters corrupted SFTP packet or packet larger than 256 kB. Some versions of WinSCP can eventually send such a large packet. Version 3.7.6 solves the issue.



Error Code


Received too large (???B) SFTPpacket. .Max supported packet size is 102400B

If ??? (from the subject) is a very large number then the problem is typically caused by a message printed from some profile/logon script. It violates the SFTP protocol. Some of these scripts are executed even for non-interactive (no TTY) sessions, so they cannot print anything (nor ask user to type something).

The number ??? represents the first four bytes read from the server. If your login scripts are printing words, this will be the first four characters cast into a number, and not an SFTP message at all.

To fix the problem find out what command in your login script prints text. Once you find it move the command to the proper interactive script, or remove it entirely. The scripts are usually hidden (their name starts with dot) and are located in your home directory on the server.

There are other possible sources of the message in addition to the profile script - some SSH servers print messages if they are unable to start the SFTP server, or encounter a fatal error. You should contact your server administrator.

Another possibility is that the server is configured to only allow the SCP protocol and not the SFTP protocol, in such a way that SCP fallback mechanism of WinSCP does not work. The solution is to choose SCP protocol on the login dialog.

Invalid access to memory This error message is not very useful to you as an end-user. It generally means that there is a bug in the SCP software.



Error Code


20.5 HTTP Protocol Error Codes

Error CodeError CodeError CodeError Code Error nameError nameError nameError name DescriptionDescriptionDescriptionDescription

1xx – Informational This class of status code indicates a provisional response, consisting only of the Status-Line and optional headers, and is terminated by an empty line. There are no required headers for this class of status code. Since HTTP/1.0 did not define any 1xx status codes, servers MUST NOT send a 1xx response to an HTTP/1.0 client except under experimental conditions.

A client MUST be prepared to accept one or more 1xx status responses prior to a regular response, even if the client does not expect a 100 (Continue) status message. Unexpected 1xx status responses MAY be ignored by a user agent.

Proxies MUST forward 1xx responses, unless the connection between the proxy and its client has been closed, or unless the proxy itself requested the generation of the 1xx response.

100 Continue The client SHOULD continue with its request. This interim response is used to inform the client that the initial part of the request has been received and has not yet been rejected by the server. The client SHOULD continue by sending the remainder of the request or, if the request has already been completed, ignore this response.




101 Switching protocols The server understands and is willing to comply with the client's request, via the Upgrade message header field, for a change in the application protocol being used on this connection. The server will switch protocols to those defined by the response's Upgrade header field immediately after the empty line which terminates the 101 response.

2xx – Successful

This class of status code indicates that the client's request was successfully received, understood, and accepted.

200 OK The request has succeeded. The information returned with the response is dependent on the method used in the request, for example:

GET an entity corresponding to the requested resource is sent in the response;

HEAD the entity-header fields corresponding to the requested resource are sent in the response without any message-body;

POST an entity describing or containing the result of the action;

TRACE an entity containing the request message as received by the end server.




201 Created The request has been fulfilled and resulted in a new resource being created. The newly created resource can be referenced by the URI(s) returned in the entity of the response, with the most specific URI for the resource given by a Location header field. The response SHOULD include an entity containing a list of resource characteristics and location(s) from which the user or user agent can choose the one most appropriate. The entity format is specified by the media type given in the Content-Type header field. The origin server MUST create the resource before returning the 201 status code.

202 Accepted The request has been accepted for processing, but the processing has not been completed. The request might or might not eventually be acted upon, as it might be disallowed when processing actually takes place. There is no facility for re-sending a status code from an asynchronous operation such as this.

The 202 response is intentionally non-committal. Its purpose is to allow a server to accept a request for some other process (perhaps a batch-oriented process that is only run once per day) without requiring that the user agent's connection to the server persist until the process is completed. The entity returned with this response SHOULD include an indication of the request's current status and either a pointer to a status monitor or some estimate of when the user can expect the request to be fulfilled.




203 Non-authoritative information

The returned meta information in the entity-header is not the definitive set as available from the origin server, but is gathered from a local or a third-party copy. The set presented MAY be a subset or superset of the original version. For example, including local annotation information about the resource might result in a superset of the meta information known by the origin server. Use of this response code is not required and is only appropriate when the response would otherwise be 200 (OK).

204 No content The server has fulfilled the request but does not need to return an entity-body, and might want to return updated meta information. The response MAY include new or updated meta information in the form of entity-headers, which if present SHOULD be associated with the requested variant.

If the client is a user agent, it SHOULD NOT change its document view from that which caused the request to be sent. This response is primarily intended to allow input for actions to take place without causing a change to the user agent's active document view, although any new or updated meta information SHOULD be applied to the document currently in the user agent's active view.

The 204 response MUST NOT include a message-body, and thus is always terminated by the first empty line after the header fields.

205 Reset content The server has fulfilled the request and the user agent SHOULD reset the document view which caused the request to be sent. This




response is primarily intended to allow input for actions to take place via user input, followed by a clearing of the form in which the input is given so that the user can easily initiate another input action.

206 Partial content The server has fulfilled the partial GET request for the resource. The request MUST have included a Range header field indicating the desired range, and MAY have included an If-Range header field to make the request conditional.

The response MUST include the following header fields:

- Either a Content-Range header field (section 14.16) indicating the range included with this response, or a multipart/byteranges Content-Type including Content-Range fields for each part. If a Content-Length header field is present in the response, its

value MUST match the actual number of OCTETs transmitted in the message-body.

- Date

- ETag and/or Content-Location, if the header would have been sent in a 200 response to the same request

- Expires, Cache-Control, and/or Vary, if the field-value might differ from that sent in any previous response for the same variant

If the 206 response is the result of an If-Range request that used a strong cache validator, the response SHOULD NOT include other entity-headers. If the response is the result of an If-Range request that used a weak




validator, the response MUST NOT include other entity-headers; this prevents inconsistencies between cached entity-bodies and updated headers. Otherwise, the response MUST include all of the entity-headers that would have been returned with a 200 (OK) response to the same request.

3xx – Redirectional

This class of status code indicates that further action needs to be taken by the user agent in order to fulfil the request. The action required MAY be carried out by the user agent without interaction with the user if and only if the method used in the second request is GET or HEAD. A client SHOULD detect infinite redirection loops, since such loops generate network traffic for each redirection.

300 Multiple choices The requested resource corresponds to any one of a set of representations, each with its own specific location, and agent- driven negotiation information is being provided so that the user (or user agent) can select a preferred representation and redirect its request to that location.

Unless it was a HEAD request, the response SHOULD include an entity containing a list of resource characteristics and location(s) from which the user or user agent can choose the one most appropriate. The entity format is specified by the media type given in the Content- Type header field. Depending upon the format and the capabilities of the user agent, selection of the




most appropriate choice MAY be performed automatically. However, this specification does not define any standard for such automatic selection.

If the server has a preferred choice of representation, it SHOULD include the specific URI for that representation in the Location field; user agents MAY use the Location field value for automatic redirection. This response is cacheable unless indicated otherwise.

301 Moved permanently The requested resource has been assigned a new permanent URI and any future references to this resource SHOULD use one of the returned URIs. Clients with link editing capabilities ought to automatically re-link references to the Request-URI to one or more of the new references returned by the server, where possible. This response is cacheable unless indicated otherwise.

The new permanent URI SHOULD be given by the Location field in the response. Unless the request method was HEAD, the entity of the response SHOULD contain a short hypertext note with a hyperlink to the new URI(s).

If the 301 status code is received in response to a request other than GET or HEAD, the user agent MUST NOT automatically redirect the request unless it can be confirmed by the user, since this might change the conditions under which the request was issued.

Note: When automatically redirecting a POST request after receiving a 301 status code, some existing HTTP/1.0 user agents will erroneously change it into a GET




request.

302 Found The requested resource resides temporarily under a different URI. Since the redirection might be altered on occasion, the client SHOULD continue to use the Request-URI for future requests. This response is only cacheable if indicated by a Cache-Control or Expires header field.

The temporary URI SHOULD be given by the Location field in the response. Unless the request method was HEAD, the entity of the response SHOULD contain a short hypertext note with a hyperlink to the new URI(s).


Note: RFC 1945 and RFC 2068 specify that the client is not allowed to change the method on the redirected request. However, most existing user agent implementations treat 302 as if it were a 303 response, performing a GET on the Location field-value regardless of the original request method. The status codes 303 and 307 have been added for servers that wish to make unambiguously clear which kind of reaction is expected of the client.

303 See other The response to the request can be found under a different URI and SHOULD be retrieved using a GET method on that resource. This method exists primarily to allow the




output of a POST-activated script to redirect the user agent to a selected resource. The new URI is not a substitute reference for the originally requested resource. The 303 response MUST NOT be cached, but the response to the second (redirected) request might be cacheable.

The different URI SHOULD be given by the Location field in the response. Unless the request method was HEAD, the entity of the response SHOULD contain a short hypertext note with a hyperlink to the new URI(s).

Note: Many pre-HTTP/1.1 user agents do not understand the 303 status. When interoperability with such clients is a concern, the 302 status code may be used instead, since most user agents react to a 302 response as described here for 303.

304 Not modified If the client has performed a conditional GET request and access is allowed, but the document has not been modified, the server SHOULD respond with this status code. The 304 response MUST NOT contain a message-body, and thus is always terminated by the first empty line after the header fields.

The response MUST include the following header fields:

- Date, unless its omission is required

If a clock-less origin server obeys these rules, and proxies and clients add their own Date to any response received without one (as specified by RFC 2068), caches will operate correctly.




- ETag and/or Content-Location, if the header would have been sent in a 200 response to the same request

- Expires, Cache-Control, and/or Vary, if the field-value might differ from that sent in any previous response for the same variant

If the conditional GET used a strong cache validator (see section 13.3.3), the response SHOULD NOT include other entity-headers. Otherwise (i.e., the conditional GET used a weak validator), the response MUST NOT include other entity-headers; this prevents inconsistencies between cached entity-bodies and updated headers.

If a 304 response indicates an entity not currently cached, then the cache MUST disregard the response and repeat the request without the conditional.

If a cache uses a received 304 response to update a cache entry, the cache MUST update the entry to reflect any new field values given in the response.

305 Use proxy The requested resource MUST be accessed through the proxy given by the Location field. The Location field gives the URI of the proxy. The recipient is expected to repeat this single request via the proxy. 305 responses MUST only be generated by origin servers.

306 (Unused) The 306 status code was used in a previous version of the specification, is no longer used, and the code is reserved.

307 Temporary redirect The requested resource resides temporarily under a different URI.




Since the redirection MAY be altered on occasion, the client SHOULD continue to use the Request-URI for future requests. This response is only cacheable if indicated by a Cache-Control or Expires header field.

The temporary URI SHOULD be given by the Location field in the response. Unless the request method was HEAD, the entity of the response SHOULD contain a short hypertext note with a hyperlink to the new URI(s) , since many pre-HTTP/1.1 user agents do not understand the 307 status. Therefore, the note SHOULD contain the information necessary for a user to repeat the original request on the new URI.





4xx – Client error

The 4xx class of status code is intended for cases in which the client seems to have erred. Except when responding to a HEAD request, the server SHOULD include an entity containing an explanation of the error situation, and whether it is a temporary or permanent condition. These status codes are applicable to any request method. User agents SHOULD display any included entity to the user.

If the client is sending data, a server implementation using TCP SHOULD be careful to ensure that the client acknowledges receipt of the packet(s) containing the response, before the server closes the input connection. If the client continues sending data to the server after the close, the server's TCP stack will send a reset packet to the client, which may erase the client's unacknowledged input buffers before they can be read and interpreted by the HTTP application.

400 Bad request The request could not be understood by the server due to malformed syntax. The client SHOULD NOT repeat the request without modifications.

401 Unauthorized The request requires user authentication. The response MUST include a WWW-Authenticate header field containing a challenge applicable to the requested resource. The client MAY repeat the request with a




suitable Authorization header field. If the request already included Authorization credentials, then the 401 response indicates that authorization has been refused for those credentials. If the 401 response contains the same challenge as the prior response, and the user agent has already attempted authentication at least once, then the user SHOULD be presented the entity that was given in the response, since that entity might include relevant diagnostic information.

402 Payment required Reserved for future use

403 Forbidden The server understood the request, but is refusing to fulfil it. Authorisation will not help and the request SHOULD NOT be repeated. If the request method was not HEAD and the server wishes to make public why the request has not been fulfilled, it SHOULD describe the reason for the refusal in the entity. If the server does not wish to make this information available to the client, the status code 404 (Not Found) can be used instead.

404 Not found The server has not found anything matching the Request-URI. No indication is given of whether the condition is temporary or permanent. The 410 (Gone) status code SHOULD be used if the server knows, through some internally configurable mechanism, that an old resource is permanently unavailable and has no forwarding address. This status code is commonly used when the server does not wish to reveal exactly why




the request has been refused, or when no other response is applicable.

405 Method not allowed The method specified in the Request-Line is not allowed for the resource identified by the Request-URI. The response MUST include an Allow header containing a list of valid methods for the requested resource.

406 Not acceptable The resource identified by the request is only capable of generating response entities which have content characteristics not acceptable according to the accept headers sent in the request.

Unless it was a HEAD request, the response SHOULD include an entity containing a list of available entity characteristics and location(s) from which the user or user agent can choose the one most appropriate. The entity format is specified by the media type given in the Content-Type header field. Depending upon the format and the capabilities of the user agent, selection of the most appropriate choice MAY be performed automatically. However, this specification does not define any standard for such automatic selection.

Note: HTTP/1.1 servers are allowed to return responses which are not acceptable according to the accept headers sent in the request. In some cases, this may even be preferable to sending a 406 response. User agents are encouraged to inspect the headers of an incoming response to determine if it is acceptable.

If the response could be




unacceptable, a user agent SHOULD temporarily stop receipt of more data and query the user for a decision on further actions.

407 Proxy authentication required

This code is similar to 401 (Unauthorized), but indicates that the client must first authenticate itself with the proxy. The proxy MUST return a Proxy-Authenticate header field containing a challenge applicable to the proxy for the requested resource. The client MAY repeat the request with a suitable Proxy-Authorization header field.

408 Request timeout The client did not produce a request within the time that the server was prepared to wait. The client MAY repeat the request without modifications at any later time.

409 Conflict The request could not be completed due to a conflict with the current state of the resource. This code is only allowed in situations where it is expected that the user might be able to resolve the conflict and resubmit the request. The response body SHOULD include enough information for the user to recognize the source of the conflict. Ideally, the response entity would include enough information for the user or user agent to fix the problem; however, that might not be possible and is not required.

Conflicts are most likely to occur in response to a PUT request. For example, if versioning were being used and the entity being PUT included changes to a resource which conflict with those made by




an earlier (third-party) request, the server might use the 409 response to indicate that it can't complete the request. In this case, the response entity would likely contain a list of the differences between the two versions in a format defined by the response Content-Type.

410 Gone The requested resource is no longer available at the server and no forwarding address is known. This condition is expected to be considered permanent. Clients with link editing capabilities SHOULD delete references to the Request-URI after user approval. If the server does not know, or has no facility to determine, whether or not the condition is permanent, the status code 404 (Not Found) SHOULD be used instead. This response is cacheable unless indicated otherwise.

The 410 response is primarily intended to assist the task of web maintenance by notifying the recipient that the resource is intentionally unavailable and that the server owners desire that remote links to that resource be removed. Such an event is common for limited-time, promotional services and for resources belonging to individuals no longer working at the server's site. It is not necessary to mark all permanently unavailable resources as "gone" or to keep the mark for any length of time -- that is left to the discretion of the server owner.

411 Length required The server refuses to accept the request without a defined Content- Length. The client MAY repeat the request if it adds a valid Content-




Length header field containing the length of the message-body in the request message.

412 Precondition failed The precondition given in one or more of the request-header fields has been evaluated to false when it was tested on the server. This response code allows the client to place preconditions on the current resource meta information (header field data) and thus prevent the requested method from being applied to a resource other than the one intended.

413 Request entity too large The server is refusing to process a request because the request entity is larger than the server is willing or able to process. The server MAY close the connection to prevent the client from continuing the request.

If the condition is temporary, the server SHOULD include a Retry- After header field to indicate that it is temporary and after what time the client MAY try again.

414 Request-URI too long The server is refusing to service the request because the Request-URI is longer than the server is willing to interpret. This rare condition is only likely to occur when a client has improperly converted a POST request to a GET request with long query information, when the client has descended into a URI "black hole" of redirection (e.g., a redirected URI prefix that points to a suffix of itself), or when the server is under attack by a client attempting to exploit security holes present in some servers using fixed-length buffers for reading or manipulating the Request-URI.




415 Unsupported Media Type The server is refusing to service the request because the entity of the request is in a format not supported by the requested resource for the requested method.

416 Requested range not satisfiable

A server SHOULD return a response with this status code if a request included a Range request-header field, and none of the range-specifier values in this field overlap the current extent of the selected resource, and the request did not include an If-Range request-header field. (For byte-ranges, this means that the first- byte-pos of all of the byte-range-spec values were greater than the current length of the selected resource.)

When this status code is returned for a byte-range request, the response SHOULD include a Content-Range entity-header field specifying the current length of the selected resource

417 Expectation failed The expectation given in an Expect request-header field could not be met by this server, or, if the server is a proxy, the server has unambiguous evidence that the request could not be met by the next-hop server.




5xx – Server error Response status codes beginning with the digit "5" indicate cases in which the server is aware that it has erred or is incapable of performing the request. Except when responding to a HEAD request, the server SHOULD include an entity containing an explanation of the error situation, and whether it is a temporary or permanent condition. User agents SHOULD display any included entity to the user. These response codes are applicable to any request method.

500 Internal Server error The server encountered an unexpected condition which prevented it from fulfilling the request.

501 Not implemented The server does not support the functionality required to fulfil the request. This is the appropriate response when the server does not recognize the request method and is not capable of supporting it for any resource.

502 Bad gateway The server, while acting as a gateway or proxy, received an invalid response from the upstream server it accessed in attempting to fulfil the request.

503 Service unavailable The server is currently unable to




handle the request due to a temporary overloading or maintenance of the server. The implication is that this is a temporary condition which will be alleviated after some delay. If known, the length of the delay MAY be indicated in a Retry-After header. If no Retry-After is given, the client SHOULD handle the response as it would for a 500 response.

Note: The existence of the 503 status code does not imply that a server must use it when becoming overloaded. Some servers may simply refuse the connection.

504 Gateway timeout The server, while acting as a gateway or proxy, did not receive a timely response from the upstream server specified by the URI (e.g. HTTP, FTP, LDAP) or some other auxiliary server (e.g. DNS) it needed to access in attempting to complete the request.

Note: Some deployed proxies are known to return 400 or 500 when DNS lookups time out.

505 HTTP version not supported

The server does not support, or refuses to support, the HTTP protocol version that was used in the request message. The server is indicating that it is unable or unwilling to complete the request using the same major version as the client, other than with this error message. The response SHOULD contain an entity describing why that version is not supported and what other protocols are supported by that server.



21 REFERENCES

There are other documents available to help you with the trial or usage of the SFTPPlus Client product. These documents may also be referenced within this document for further information.

SFTPPlus Client 1.5.1 Installation Guide for Linux and UNIX

SFTPPlus Client 1.5.1 Installation Guide for OpenVM S SFTPPlus Client 1.5.1 Installation Guide for OS/400 SFTPPlus Client 1.5.1 Installation Guide for Window s

SFTPPlus for z/OS PuTTY User Manual version 0.60

Also available;

SFTPPlus 1.5.1 – Features and Benefits

For an up-to-date list of documents, please see our website www.proatria.com or email us at [email protected]



22 TECHNICAL SUPPORT

First and foremost, we would like to thank you for using SFTPPlus products.

Technical support is a vital part of the total Pro:Atria customer experience. We want you to get the most from our products long after the initial sale and installation. We are dedicated to ensure that every issue is resolved expediently and to your satisfaction. To enable you to maximise the return on your investment, we offer a suite of support offerings designed to meet your business needs.

This chapter provides an overview of the SFTPPlus support offerings and how to use them.

22.1 Trial support

Whilst you are trialling SFTPPlus Client, you are entitled to full technical support to enable you to install, configure and perform test transfers on your platform(s). We will endeavour to help you at every step to ensure you can complete your trial successfully. Our normal terms for trials are 30 days but this can be extended on agreement. We will always make reasonable efforts to assist you to integrate and setup SFTPPlus in your business during the trial period.

22.2 Annual Maintenance Support

Payment of the annual maintenance fee entitles you to full technical support via email, telephone support and software updates.

22.3 General Support Information

We would normally conduct technical support via various media but we have preferred routing in the order of;

• Email

• Telephone

And where applicable/practical/possible

• Site visit

To help us asses any issues that may arise, it will be helpful to us, and speed up diagnostics, if you would send relevant information pertaining to the issue. This should include;

• The platform that SFTPPlus Client is running on



• As much information possible on the he target platform you are connecting to

• Version of SFTPPlus Client you are running

• Rexx version – using vi or kate (Linux) or WordPad (Windows), look at the first line of SFTPPlus.rexx, please supply the details after the $Id, for example

/* $Id: SFTPPlus.rexx, v x.xx yyyy/mm/dd

• Copy of message.log

• Copy of global.conf

• Copy of message.log

• Any screen output that you may have to illustrate the issue you are experiencing

• Trace output from debug mode (this can be switched on manually but please speak to us first regarding this)

In the first instance, sending us this information should help us diagnose the problem and identify a solution for you as quickly as possible.

Upon receipt of the above information, we will respond by confirming that we have received your enquiry and it is receiving attention. We will then look through the information supplied and diagnose the problem. When a solution is found we will email or telephone you with a detailed solution.



23 CONTACT INFORMATION

Address

Pro:Atria Limited

The Old Exchange

South Cadbury

Yeovil

Somerset

BA22 7ET

UK

Telephone/Fax

Telephone:

Fax:

+44 (0)1963 441311

+44 (0)1963 441312

Email

Sales:

Technical Support:

[email protected] [email protected]

Website http://www.proatria.com

Documentation

If you have any comments or suggestions regarding this or any other Pro:Atria document, please send an email to the following address ;

[email protected]