WS FTP Proftp.ipswitch.com/ipswitch/manuals/wsftp70.pdf · Introduction 1 WS_FTP Pro Chapter 1:...

WS_FTP Pro

User’s Guide

Software Version 7.0

Ipswitch, Inc.

Ipswitch, Inc. Phone: 781-676-5700

81 Hartwell Ave Fax: 781-676-5710

Lexington, MA 02421-3127 Web: http://www.ipswitch.com

The information in this document is subject to change without notice and should not be construed as a

commitment by Ipswitch, Inc. While every effort has been made to assure the accuracy of the informa-

tion contained herein, Ipswitch, Inc. assumes no responsibility for errors or omissions.

Ipswitch, Inc. assumes no liability for damages resulting from the use of the information contained in

this document.

The software described in this document is furnished under a license and may be used or copied only in

accordance with the terms of that license.

Copyright © 2001 by Ipswitch, Inc. All rights reserved. IPing, the IPing logo, WS_FTP, the WS_FTP

logos, Ipswitch, and the Ipswitch logo are trademarks of Ipswitch, Inc. Other products or company

names are or may be trademarks or registered trademarks and are the property of their respective com-

panies.

No part of this publication may be reproduced, photocopied, stored on a retrieval system, or transferred

without the expressed prior written consent of Ipswitch, Inc.

Printing History

May 1996 First EditionDecember 1996 Second EditionJuly 1997 Third EditionFebruary 1998 Fourth EditionOctober 1998 Fifth EditionMay 2000 Sixth EditionJune 2001 Seventh Edition

Table of Contents

Chapter 1: Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1Why FTP? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1How FTP Works . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1New in WS_FTP Version 7.0 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2System Requirements. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2Installing WS_FTP Pro . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3Logging Onto an FTP Site . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3Interfaces for Windows 95, 98, 2000, ME and NT . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4

The Classic Interface of WS_FTP Pro . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5The Explorer Interface of WS_FTP Pro . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5

Browser Integration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6Other Ipswitch WS_FTP Products . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7

WS_FTP Server. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7WS_FTP Pro Development Kit. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8

Getting Updates and Giving Feedback . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8Uninstalling . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9Accessibility. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9

Chapter 2: Getting Started . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11Making your First Connection . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11

Connection Dialog Toolbar and Buttons. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12Connection Dialog Boxes and Options . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12

Transferring a file. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14WS_FTP Pro Toolbar . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15

Anonymous Connections . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16Using the Help System. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16

Chapter 3: Transferring Files. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17Ways to Transfer Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17

Using the Transfer Arrows . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17Drag and Drop. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17Copy and Paste . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18Batch Mode . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18Using the Transfer Manager . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18

Transfer Modes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18Passive Transfers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19

Chapter 4: Managing Files and Folders . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21Viewing and Navigating . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21Working with Files and Folders. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22

Click and Drag for Organization. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 24

Contents

WS_FTP Proiii

iv

Changing the Permissions for UNIX Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 24Background Information . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 24

Chapter 5: Explorer Interface . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27Using the Explorer Interface . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 28

Configuring a Site . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 28Making a Connection . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 28Transferring Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 28

Chapter 6: WS_FTP Transfer Manager . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 29What is the Transfer Manager? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 29Transfer Manager Dialogs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 29

Transfers Manager Dialog. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 29Request Properties. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 30Log Window . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31

Chapter 7: SSL Utility . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 33What is SSL? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 33How to make an SSL connection. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 35

Client Certificate Verification. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 35Generating a Certificate . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 36Selecting a Certificate . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 37Trusted Authorities . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 38

Adding a Certificate . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 39Exporting a Certificate . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 39Removing a Certificate . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 39

Non-Trusted Certificate . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 40

Chapter 8: Synchronizing Files and Folders . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 41A Word of Caution. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 41Using the Synchronize Utility . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 41Example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 42Exclusions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 43Using the Synchronize Utility from the Command Line . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 44

Chapter 9: The Find Utility . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 45Using the Find Utility . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 45

Using the Search Results. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 46Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 47

Finding a File When You Are Not Sure of Its Name . . . . . . . . . . . . . . . . . . . . . . . . . . . . 47Finding a File Modified During a Specific Time Period . . . . . . . . . . . . . . . . . . . . . . . . . 48Finding a File in a Particular Folder . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 48Finding a File Smaller Than a Certain Size . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 49

WS_FTP Pro

Contents

Chapter 10: Scripting . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 51Using Scripting . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 51Writing and Debugging Scripts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 52Executing Scripts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 52

Executing a Script from the Command Prompt . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 52Running a Script from the Scripting Utility. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 52Example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 53

Chapter 11: Scheduler. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 55Using the Scheduler . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 55Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 56

Adding a Script to the Scheduler. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 56Updating a Web Site on a Nightly Basis. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 57

Chapter 12: Using Firewalls . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 59Multiple Firewalls . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 59Firewall Types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 60Configuring a Firewall . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 60Using a Configured Firewall . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 62

Chapter 13: Using the Command Line . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 63Basic Command Line Syntax. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 63

Site Information. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 63Transfer Source . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 64Transfer Destination . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 64

File Transfer Options . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 65Uploading Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 65Downloading Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 65Transferring multiple files from the same location. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 66Converting File Names to Lower Case . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 66File Transfer Modes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 66

Transferring Files with Spaces in the File Names . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 66Enclosing the Command Line in Quotes. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 67Using the MS-DOS Name. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 67

Using a Batch File . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 67Multiple Folders or Commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 68Pre-scheduled Transfers (“Automated Transfers”) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 68Transferring a Folder Containing Subfolders . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 69Using a Site Profile with a Host Name . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 70Extras . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 70Summary . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 70

Appendix A: FireScript Editor . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 73What is a FireScript? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 73

Contents

WS_FTP Prov

vi

FireScript Components . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 73The fwsc Section . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 74The Comment Section. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 75The Script Section . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 75

The Connection Sequence . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 76The FireScript Language . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 76FireScript Variables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 77String Expansion . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 79Function Expressions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 80FireScript Statements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 80Switch Statements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 81Case Statements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 81

Examples of Case Statements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 82Continue . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 83Jumps and Labels . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 84Return. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 84Autodetect . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 84SSL Statements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 85FireScript Key Words . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 86

FireScript reserved words . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 86FireScript statements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 87FireScript intrinsic functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 87FireScript intrinsic variables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 87

Appendix B: Textual Error Messages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 89“Blocking call canceled” . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 89“Cannot create file” . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 90“Can’t get ‘xxx’ host entry” . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 90“Can’t set guest privileges” . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 90“Connection refused” . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 90“Directory identifier unavailable” . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 90“Disk quota exceeded”. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 91“Failed data channel” . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 91“File too large to download” . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 91“Illegal port command” . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 91“Invalid page fault” . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 91“Logon failure; Quitting.” . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 91“MDTM” . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 91“Port command failed”. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 92“User access denied” . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 92

Index . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 93

WS_FTP Pro

Contents

Chapter 1: Introduction

This chapter offers an introduction to WS_FTP Pro, a brief description of File Transfer Protocol, system requirements, the installation procedure, information about software updates, and instructions for giving feedback to Ipswitch, Inc.

Why FTP?

A vast store of software applications, games, images, and other types of files are available on FTP sites all over the world. An FTP site is a computer system (“host”) that uses an Internet protocol called FTP, File Transfer Protocol. FTP offers fast and accurate transfer of large files or collections of files between computers on the Internet.

Many Web sites on the World Wide Web (which is based on another Internet protocol called HTTP) also provide links to files you can download -- that is, copy to your PC. Especially for large files, WS_FTP Pro will speed up the time it takes to copy such files to your PC. For more information, see “Browser Integration” on page 6.

WS_FTP Pro also allows you to upload files -- that is, copy files from your PC to other computers. For example, you would upload files if you need to place your Web pages on a computer system designated by your ISP (Internet Service Provider), or if you want to store a picture of something you want to sell through an online auction site.

How FTP Works

File Transfer Protocol uses the client–server model: one computer (the FTP Host) runs a server program “serving up” information to other computers. The other computers run client programs requesting information and receiving replies from the server.

WS_FTP Pro turns your PC into an FTP client, allowing it to communicate with virtually all types of FTP sites. When your PC is connected to the Internet (via a modem or local area network), WS_FTP Pro can connect to any system that has a valid Internet Address and contains an FTP server program. Once connected to an FTP site, you can download files, upload files, and copy files from one FTP site to another.

Using This Book

The WS_FTP User’s Guide is a resource you should use to familiarize yourself with the different features of WS_FTP Version 7.0.

1IntroductionWS_FTP Pro

2

New in WS_FTP Version 7.0

• Redesigned interface.

• Explorer interface is no longer tightly integrated with Windows Explorer but navigation remains similar for familiarity.

• New Wizard interface for adding new sites. (Classic and Explorer)

• Improved firewall support, allows scripting of custom firewall types.

• Transfer Manager allows pausing, restarting, scheduling and deleting transfers.

• Multiple transfers can be executed simultaneously or sequentially.

• Scheduler interface uses Windows scheduler to schedule transfers for future execution.

• URL bar in Classic allows a user to connect to an FTP site with minimal effort.

• New button bar in Classic allows quick access to common functions.

System Requirements

WS_FTP Pro requires the following system resources:

• An Intel 386, 486, or Pentium processor

• Windows 95, 98, 2000, ME or NT

• Internet Explorer 4.02 or newer (does not have to be your default browser)

FTP site A FTP site B

Your PC

User’s Guide

WS_FTP Pro

Installing WS_FTP Pro

The installation of WS_FTP Pro is the same for new users, those who are upgrading from a previous version of WS_FTP Pro, and those who are replacing an evaluation version with a purchased version.

To install WS_FTP Pro from a downloaded file:

1 Double-click the file you downloaded. (ftpproec.exe)

2 Follow the directions on your screen.

To install WS_FTP Pro from a CD-ROM:

1 If you already have a previous version of WS_FTP Pro on your system, make sure you are not running the application (either Classic or Explorer).

2 Insert the WS_FTP Pro CD-ROM into a CD-ROM drive.

3 If the CD-ROM does not automatically display a “Welcome” screen, click the Start button and select Run.

4 Enter the CD-ROM drive letter followed by autorun. For example: d:autorun

5 Follow the instructions on your screen.

Please refer to the file named whatsnew.txt or relnotes.txt for information regarding enhancements or changes that may have been made to the software since this manual was printed.

Logging Onto an FTP Site

The FTP process begins when a connection is made between an FTP client and an FTP site. After establishing communication, the client “logs on” with a user ID and password. The user ID and password identify you to the site.

If you are upgrading from a previous version of WS_FTP Pro, or replacing an evaluation version, be sure to install the purchased version in the same location as your previous or evaluation version.

You can install both the Classic and Explorer interfaces and use them interchangeably.

The two interfaces can share the FTP site configurations you create in either interface.


4

Most public FTP sites are set up with an “Anonymous” account: when you connect to one of these FTP sites, you need only identify yourself as “Anonymous” and use an e–mail address as a password. Normally, when you log on anonymously, you see a public folder (usually named something like /pub or /apps) containing the information and software that can be downloaded to your PC. (Access to other folders on the site is usually restricted.)

On anonymous FTP sites, look for files called readme, readme.txt, index, or 00index. Many sites use a file like this to provide a catalog of the information available on the site as well as other information about the site, such as a mission statement or operating hours.

In addition, an FTP site administrator can give certain users “accounts” with special permissions. For example, a user with an account may be able to upload, download, delete, and edit files: while an “anonymous” user can usually only download files. To log on to a site on which you have an account, you will need to enter the Host Name, User ID, and Password that the site administrator has assigned to your account.

Interfaces for Windows 95, 98, 2000, ME and NT

WS_FTP Pro provides two user interfaces: the Classic user interface, which runs as a standard Windows application, and the Explorer interface, which has the look of Windows Explorer.

User’s Guide

WS_FTP Pro

The Classic Interface of WS_FTP Pro

The Classic interface is a standard Windows application that looks similar to a two-paned window. When your PC (the “Local System”) connects to an FTP server (the “Remote System”), the WS_FTP Pro Classic interface displays a window with your PC’s files and folders on the left and the FTP site’s files and folders on the right. With the contents of both systems displayed, you can easily locate files on one system and transfer them to a specific folder on the other system. The Classic interface looks similar to this:

The buttons to the right of each list box provide file and folder operations for that list box.

The Explorer Interface of WS_FTP Pro

The second interface of WS_FTP Pro is the Explorer interface. The Explorer interface uses the same software engine as the Classic interface, but it lets you copy and move files within a system that has the same look and feel as Windows Explorer.

The current folder on the FTP site is shown under the words Remote System.

The current folder on your PC is shown under the words Local System.

This list box shows the files and folders in the current folder on the FTP site.

This list box shows the files and folders in the current local folder.


6

The WS_FTP Pro Explorer interface looks similar to one of the following:

Browser Integration

You can set up WS_FTP Pro Classic so that it automatically handles FTP URLs when you click them in your browser or in an e-mail message. (A URL, Uniform Resource Locator, is an Internet address describing an Internet resource. For example, the Web URL for the Ipswitch web site is http://www.ipswitch.com/; the FTP URL for the FTP site of WS_FTP Pro Patches is ftp://ftp.ipswitch.com.)

WS_FTP Pro handles FTP URLs as follows:

• If the URL is the name of an FTP server, such as ftp.ipswitch.com, WS_FTP Pro “handles” the URL by starting the Classic interface of WS_FTP Pro and connecting to the site.

Files and folders in the current folder

The appearance of the Explorer window is determined by your View menu options.

Explorer interface

Browser Integration is NOT compatible with Netscape 6.

User’s Guide

WS_FTP Pro

• If the URL includes the path and name of a file, such as ftp.ipswitch.com/French/ftp605F.txt, WS_FTP Pro attempts to download the file to your PC, and prompts you for a location to save or execute the file.

• If the URL includes the path and name of a folder (and not a file), such as ftp.ipswitch.com/French, WS_FTP Pro “handles” the URL by starting the Classic interface, connecting to the site, and navigating to the folder.

To turn on Browser Integration:

1 Select Browser Integration from the Tools menu.

2 If you use Netscape Navigator and want WS_FTP Pro to handle FTP URLs, select the first check box.

3 If you use Microsoft Internet Explorer and want WS_FTP Pro to handle FTP URLs, select the second check box.

4 If you want to be prompted each time you click an FTP URL so you can choose whether or not to use WS_FTP Pro, select Ask before using WS_FTP.

Other Ipswitch WS_FTP Products

WS_FTP Server and the WS_FTP Pro Development Kit can be purchased separately at www.ipswitch.com.

WS_FTP Server

The WS_FTP Server is a full-featured, secure (using SSL) FTP server for Windows NT/2000 systems. WS_FTP server lets you create an FTP site that makes files and folders on your PC available to other users. WS_FTP Server offers many features not found in most commercial servers today, including automatic resumption of interrupted transfers.


8

WS_FTP Pro Development Kit

You can develop custom applications using the WS_FTP Pro Development Kit. It lets you create programs to work with WS_FTP Pro for transferring files to or from FTP sites or between FTP sites. The Development Kit lets you create an FTP application without being concerned with the intricacies of network programming.

Getting Updates and Giving Feedback

Ipswitch frequently makes patches and upgrades available on our Web site. For the latest version information, please visit www.ipswitch.com.

To access upgrades on the Ipswitch FTP site:

1 In the WS_FTP Pro window, click the Connect button.

2 In the Connection dialog box, open the Ipswitch folder and select the site named WS_FTP Pro Patches.

3 Click Connect. WS_FTP Pro connects to the WS_FTP Pro folder.

4 Select the desired patch file; the last three digits of the file name indicate the version number. For example, wsftp606.exe is the patch file to update earlier versions to WS_FTP Pro 6.06. Read the accompanying text file (for example, wsftp606.txt) to verify that you have located the correct file.

5 Transfer the patch file and place it in a folder other than your WS_FTP Pro folder or your Windows Temp folder. To update the software, double-click the patch file and follow the instructions.

To access patches on the Ipswitch Web site:

1 In your Web browser, go to: http://www.ipswitch.com

2 Click the Service & Support link at the top right of the Web page.

3 Click Patches and Upgrades, and then click the link for the product.

User’s Guide

WS_FTP Pro

4 Save the patch file in a folder other than your WS_FTP Pro folder or your Windows Temp folder.

5 Run the patch file to update the software.

We welcome your feedback on WS_FTP Pro. Please e–mail any comments and suggestions to [email protected].

Uninstalling

The uninstall function can remove all files associated with WS_FTP Pro from your PC, including your configured sites. It also removes the WS_FTP Pro Explorer icon from your desktop.

To uninstall WS_FTP Pro:

1 Click the Start button and select Programs -> WS_FTP Pro Uninstall.

2 When prompted, choose WS_FTP Pro Uninstall.

3 Follow the on–screen instructions to uninstall WS_FTP Pro.

Accessibility

WS_FTP Pro is designed for use by all computer users, including those with certain disabilities that make using a mouse impossible. Every operation and feature included in WS_FTP Pro has a shortcut key, or series of keystrokes that allow the user to use their keyboard to execute the command.

The image below shows the WS_FTP Button bar:

Notice that each of the button labels have a letter that is underlined. To access the command performed by the button, hold the Alt key on your keyboard and press the underlined letter on the button you want to use. For example, Alt + C will disconnect you from the current FTP site, and Alt +X will close the program.


10
User’s Guide
WS_FTP Pro

Chapter 2: Getting Started

This chapter describes how to get started using WS_FTP Pro. The two main windows are mapped out for you, and in the sidebar are step-by-step instructions on the basic functions of WS_FTP Pro.

Making your First Connection

The first time WS_FTP Pro is run, the Classic Interface opens with the Connection dialog box displayed.

Some sites are set up for you when you install WS_FTP Pro. You can connect to one of these or configure your own.

When you select a configured site, the host information for that site is displayed here. When you create a site of your own, this is where you set the host information.

Make your first connection:

Before you make your first connection, you need to create a site profile for that FTP server.

1. From the Connection dialog, select the folder you want to create the site profile in.

2. Click the New Site icon in the Toolbar.

3. In the Create a Site Profile named box enter what you want to call the site.

4. In the Host Name or IP address box, enter the internet address for the FTP site you want to connect to.

5. Click Next.

6. Enter the UserID and Password for that site.

7. Click Finish, or click Next to enter optional information about the site (described later in the User’s Guide and in the Online help.)

Your new site profile will now appear in the folder you selected.

8. Click Save to save the information with the site profile.

9. Click Connect.

When you click connect, the Connection Dialog box disappears and the WS_FTP Pro Classic Interface attempts to make the connection.

How to...

11Getting StartedWS_FTP Pro

12

Connection Dialog Toolbar and Buttons

Save. Click this button to save the site information. You should do this when the site is first configured, and any time host information is edited.

Advanced Properties. Click this button for more site configuration options. See the Online help for more information on the Site properties.

Connect. Click this button to connect to the selected site.

Cancel. Click this button to close the Connection dialog box.

Connection Dialog Boxes and Options

Configured Sites. This box lists all of your configured sites.

Host Name. Every system (computer) on the Internet has an official host name and Internet (IP) address. In order to connect to an FTP site, you must know the official name or address of the site. For example, a system might have a host name of superserv.ipswitch.com

Connect. After selecting or creating a site, click this icon to connect to that site.

New Site. Click this icon to create a new site in the folder you select in the Configured Sites box.

New Folder. Click this icon to create a new folder in the Configured Sites box.

Delete Site or Folder. Click this icon to delete the folder or site you select in the Configured Sites box.

Help. Click this icon to access the WS_FTP Pro online help system.

When a folder has a + next to it, it means that there may be folders or sites within this folder.

Select a site to connect to that site or to view the host information for that site. To rename a site, right click on the site name and type the new name.

User’s GuideWS_FTP Pro

and an IP address of 123.124.125.126. In WS_FTP Pro, you can use either the host name or the IP address to specify a particular FTP site.

UserID. If you have an account on the FTP server you are connecting to, enter your user identification name here. For information on connecting to sites you do not have an account on, see ‘Anonymous Connections on page 16.’

Password. Enter your password for the site you are connecting to.

Account. Some FTP sites, notably VM/CMS hosts, require an account in order to authenticate the client and provide access to a default directory for the user. For many sites, however, no account is required.

Anonymous. Select this option if you are making an anonymous connection to the selected site. For information on anonymous connections, see ‘Anonymous Connections on page 16.’

Save Password. When you select this option, the password will be saved with the site information. It is recommended that you do not select this option if other people have access to your computer.

Save Account. Select this option to save the account information entered in the Account box with the site information.

Firewall. If you have to use a Firewall script to connect to an FTP server, select the type from this list. For more information on Firewalls, see “Chapter 12: Using Firewalls” on page 59.

Passive Mode. Normally, when you connect to an FTP site, the site establishes the data connection to your PC (the client). However, if the site allows passive transfers, you can have your PC establish the data connection.

We recommend that you use passive mode for most transfers. Note that passive mode may be required for users who are behind some types of router-based firewalls or behind a gateway requiring passive transfers.

Secure (SSL). Select this option to make a secure SSL connection to the selected site. For more information on SSL, see “Chapter 7: SSL Utility” on page 33.


14

Local Folder. If there is a folder on your PC that you want to use as your starting location when you connect to this FTP site, enter the path of the folder here. (For example, C:\WS_FTP Pro)

Comment. Enter any comment you would like to make about the site.

Transferring a file

After making your connection, WS_FTP closes the Connection dialog, leaving the WS_FTP Pro window. The image below shows how the WS_FTP Pro window looks once you have connected to a site.

The following are boxes and window structures that are important in learning how to make an FTP transfer:

Local System. This box displays the directory set as your default local directory, and all of the files and folders in it. You can change directories by selecting it from the list, by clicking the Browse (...) button next to the Local System box, or by typing the folder path in the box.

Remote System. This box displays the default directory for the FTP site you connect to. You can change directories by selecting it from the list, by clicking the Browse (...) button next to the Remote System box, or by typing the folder path in the box.

How to...Transfer a file:

Once you have connected to a site, you are ready to transfer a file.

Downloading a File

1 Select the directory you want to download the file to in the Local System list.

2 In the Remote System list, find the file by clicking on the folder it is stored in (unless the file is in the directory you connected to.)

3 Select the file you want to download

4 Click the download transfer arrow. It is the one that looks similar to: <--

5 When the file is downloaded, it will appear in the Local System list.

Uploading a File

1 Select the directory you want to upload the file to in the Remote System list.

2 In the Local System list, select the file you want to upload.

3 Click the upload transfer arrow. It is the one that looks similar to: -->

4 When the file is uploaded, it will appear in the Remote System list.


Address. The Address bar displays the complete path of the FTP Site you are connected to. If you type this address in manually, the Address bar will record the last ten sites and folders you have connected to.

Transfer Arrows. Click these icons to transfer a file:

WS_FTP Pro Toolbar

Upload Arrow

Download Arrow

Connect. Click this icon to select or configure a site to connect to, using the Connection Dialog box.

Disconnect. Click this icon to disconnect from a site.

FTP Manager. Click this icon to display the Transfer Manager. For more information, see “Chapter 6: WS_FTP Transfer Manager” on page 29.

Batch Mode. Click this icon to place WS_FTP in Batch Mode. In this mode, selected files will be added to the Transfer Manager to be transferred later.

Options. Click this icon to access WS_FTP Program Options.

Large Icons. Click this icon to change the layout of the list pane to show file names along with large icons associated with the file type.

Small Icons. Click this icon to change the layout of the list pane to show file names along with small icons associated with the file type.

List. Click this icon to change the layout of the list pane to show an ordered list of files in a selected directory.

Details. Click this icon to change the layout of the list pane to show an ordered list of files with the name, size, type, time of last modification, and attributes listed.

Help. Click this icon to access the WS_FTP Pro online help system.


16

Anonymous Connections

To log on to any FTP site, you must identify yourself with a user ID and password. For many FTP sites, you can use the word anonymous as a User ID, and your E-mail address as your password; this is known as an "anonymous login." (All of the Ipswitch preconfigured FTP sites are set up as anonymous logins.)

FTP sites that allow anonymous logins usually exist to provide files that can be downloaded by the general public; anyone on the Internet can log onto the site anonymously and copy files to their PC. This is similar to logging on to a file server as a "guest."

Anonymous logins have access to a vast store of software, games, music, and numerous other resources. However, if you log in anonymously, you usually are not allowed to do more than view public folders and download files. (You are usually unable to view private folders or to upload files.)

Using the Help System

Our Online Help system contains detailed descriptions and directions on how to use each and every function available in WS_FTP Pro. It should be the first place you look if you have any question using the product.

Individual topics are organized into books that relate to a spe-cific function.Some books have other books listed in-side.

Use the Index tab to look up keywords, and use the Search tab to search for words in the body of the topics.

The body of the help topic appears in this pane.

Click on blue words to ‘jump’ to another topic. Click green to access a ‘drop down’ list.


Chapter 3: Transferring FilesTransferring means moving or copying files or folders between computers. If you transfer a file from your computer (local system) to an FTP Site (remote system) it is called an upload. If you transfer a file from a remote system to your local system, it is called a download.

This chapter includes the following topics:

• Ways to Transfer Files

• Transfer Modes

• Doing Passive Transfers

Ways to Transfer Files

WS_FTP Pro allows you several ways to transfer a file.

Using the Transfer Arrows

Select a file or folder and click the Upload or Download Arrow to transfer it. You can select multiple files by holding down the Ctrl button while selecting.

Drag and Drop

With a file or folder selected, click and hold your left-mouse button and drag the file to where you want it transferred to. You can select multiple files by holding down the Ctrl button while selecting. As you drag the file, your cursor changes.

Upload Arrow

Download Arrow

When your cursor looks like this, you are at a place where you can transfer a file.

When your cursor looks like this, you cannot drop a dragged file there.

Look for more information in the Transferring Files section of the Online help.

Restarting Transfers!

Some FTP Servers allow clients to restart transfers that have failed or been interrupted due to a lost connection, cancellation, or other reason.

For specific directions on this process, see the Transferring Files section of the Online help.

17Transferring FilesWS_FTP Pro

18

When you release the mouse button, WS_FTP Pro attempts to transfer the file to that location.

Copy and Paste

Right-mouse click a file, then select Copy from the pop-up menu. This will copy your file to the clipboard. Right-click where you want to transfer the file to, and from the right-mouse menu select Paste. WS_FTP Pro then attempts to make the transfer.

Batch Mode

If you want to transfer multiple files from different sites, you can put WS_FTP Pro in Batch Mode.

While in batch mode, WS_FTP Pro will place all transfers in the Transfer Manager for download. If you want to make an immediate transfer while in Batch Mode, without having it go through the Transfer Manager queue, select the file and drag it to the destination folder.

Using the Transfer Manager

The WS_FTP Pro Transfer Manager is used to view the progress of transfers, to schedule the transfer of multiple files, and to view logs for individual transfers. For more information, see “Chapter 6: WS_FTP Transfer Manager” on page 29.

Transfer Modes

There are three modes that WS_FTP Pro uses to transfer a file from place to place. Depending on the type of file, you may have to select this mode before you attempt to transfer a file.

Confirming Overwrites

Most sites allow you to overwrite or replace a file without giving you any kind of visual warning. Through WS_FTP Pro, you can set it up so that a dialog box is displayed to warn you that you are about to overwrite a file.

For specific directions on this feature, see the Transferring Files section of the Online help.

Transfer Mode


These modes are called ASCII, Binary, or Auto. The following chart shows the icon that should be chosen for the described type of file.

Passive Transfers

Normally, when you connect to an FTP site, the site establishes the data connection to your PC. However, some FTP sites allow passive transfers. This means that your PC establishes the data connection.

By default, passive mode is turned on in WS_FTP Pro; we recommend that you use it for transfers to and from FTP sites that support it. Note that passive mode may be required in the following instances:

• For users on networks behind some types of router-based firewalls

• Users on networks behind a gateway requiring passive transfers

• If transfers are erratic

• If you keep getting failed data channel errors

Ascii Mode

A file that is text, HTML, postscript, other ASCII format (.txt, .html, .htm, .cgi), or EBCDIC should be transferred in ASCII mode. If you transfer a binary file in ASCII mode, you will not get the entire file.

Binary Mode

A file that is a bitmap, an executable, or compressed (.bmp, .jpg, .exe, .zip) should be transferred in binary mode. (Binary mode should also be used if there is no file extension or the file extension is not registered.) This is the default mode.

Auto Mode

If you turn on Auto mode, WS_FTP Pro checks to see if the file has an extension that is listed on the Extensions tab of the Options dialog. If so, ASCII mode is used; if not, binary mode is used.

19Transferring FilesWS_FTP Pro

20

Chapter 4: Managing Files and Folders

This chapter deals with using WS_FTP Pro to manage files and folders on both local and remote systems. Managing files and folders includes:

• Viewing and navigating

• Working with files and folders

Viewing and Navigating

WS_FTP provides many tools and techniques for viewing and navigating files and folders.

This section points out various structures on the WS_FTP Pro window that allow you to view files and folders, and to navigate both local and remote systems.

The Address bar displays the complete path to the FTP site directory you are currently connected to. You can edit this path manually to navigate to the folders listed in the Remote Directory listing. When you do this, the Address bar stores the last five paths that have been entered.

Look for more information in the Viewing and Navigating section of the Online help.

Local System

Display Icons

Up one Level

Remote System

Address Bar

Remote Directory

Local Directory

Refresh Buttons

Mapped Drives

Change Directory Button

21Managing Files and FoldersWS_FTP Pro

22

The left side of the WS_FTP Pro window shows your local system, and where on that system you are. The Local Directory listing displays everything that is visible in the folder identified in the Local System box.

Click on one of the Mapped Drives icons in the Local Directory listing to access that drive.

The right side of the WS_FTP Pro window shows the Remote System (FTP site) you are connected to. The Remote Directory listing displays everything that is visible in the folder identified in the Remote System box.

The way these listings look can be changed by the Display Icons, and can be refreshed (to make sure you are looking at the most up-to-date list of files and folders) by clicking the Refresh button next to the directory list box.

You can use the ChgDir (Change Directory) button to navigate by doing one of the following:

• Select the desired folder and click the ChgDir button. A dialog box appears, allowing you to enter the name of the directory you want to move to.

• To get a dialog box that asks for the folder name, make sure nothing is selected in the list box and click the ChgDir button.

When you see the dialog box, you can also change drives by entering a drive letter followed by a colon (for example, d:).

Working with Files and Folders

WS_FTP Pro gives you a variety of features that make it quick and easy to organize, manipulate, and delete files and folders.

Look for more information in the Working with files and folders section of the Online help.


The graphic below points out key features used during these tasks.

The Connection buttons are very important to managing your files. The following is a description of the buttons that pertain to this section:

MkDir - Make Directory. The Make Directory command allows you to create a folder/directory on your PC or on the FTP site if possible. (Not all FTP sites allow you to create folders; you must have an account on the site and "create" permissions.) When you select this command, you are prompted for a folder name that is valid for the current system.

View. The View command allows you to view a file. If you select a filename on an FTP site and then click View, the file is transferred to your temporary folder and is opened in the default text viewer.

Execute. The Execute command allows you to open an application on a remote server. When you select this command, WS_FTP Pro downloads the file to your Windows Temp directory and runs the application from there.

Delete. The Delete command allows you to delete a file or folder on your PC or on the current FTP site, if you have the appropriate permissions.

DirInfo - Directory Information. The Directory Info command opens a text document that displays information about the current directory. This document opens in the default Text Viewer (as specified on the General tab of program options). WS_FTP

Folder

Files

Connection buttons (Connection Bars)


24

displays as much information as the FTP site delivers. Depending on the site, for each file or folder within the current directory, the following information may be shown: size, type, permission, creation date, date last modified, and name.

Click and Drag for Organization

You can organize your files by clicking on the files and dragging them to the folder you want to move them to. This is not an FTP transfer when you move the file from one folder to another on the same system.

Changing the Permissions for UNIX Files

You can change modes for a UNIX file on an FTP site, provided you have permission.

1 Select the file, select FTP Commands from the right-mouse menu, and then select chmod (UNIX).

2 Do one of the following:

• Select the desired options by clicking the appropriate check boxes.

• Enter a three- or four-digit number that represents the options (as described in the table below).

3 Click the OK button.

Background Information

Permissions can also be expressed as three- or four-digit values; for example: 1644.

• The first digit is interpreted as follows:

The selected options do not necessarily indicate the current permissions for the selected file or folder.

If you attempt to change permissions, check the message area or the log to see if you were successful.


• If the first digit is 1 (known in UNIX circles as the “sticky bit”), it sets the link permission to directories or sets the “save-text” attribute for a file.

• If the first digit is 2, it sets the group ID on execution.

• If the first digit is 4, it sets the user ID on execution.

• The second digit expresses Owner permissions

• The third, Group permissions

• The fourth, Other.

Four-digit values are used in the WS_FTP Pro log, in the message area, and by some system administrators and ISPs.

The table below shows how WS_FTP Pro check box options correspond to the last three digits. The third column shows the possible values for Owner, Group, and Other as viewed in the ten-position value in the first column of a directory list for a UNIX site.

In the directory list, the first position indicates whether the item is a file (-, s, S, or t) or directory (d), while positions two through ten show the permissions for Owner, Group, and Other.

For example, the value 751 corresponds to drwxr-x--x in the

Selected options in WS_FTP Pro

2nd, 3rd, or 4th digit of 4-digit number

Permissions in directory list

none 0 ---Execute 1 --xWrite 2 -w-Write, Execute 3 -wxRead 4 r--Read, Execute 5 r-xRead, Write 6 rw-Read, Write, Execute 7 rwx


26

directory list. This expression is comprised of four parts:

d rwx r-x --xFirst position indicates whether item is a file (-,s,S, or t) or directory (d)

Positions 2-4indicateOwner

permissions:read, write,

execute.

Positions 5-7 indicate Group permissions:

read and execute.

Positions 8-10 indicate Other permissions: execute only.


Chapter 5: Explorer InterfaceUnlike previous versions of WS_FTP Pro, version 7.0 contains an Explorer Interface that runs independently of Microsoft Windows Explorer. Now, most of the functions of the interface work like the Classic Interface, and the speed and performance of the Explorer Interface has greatly increased.

Overview

The following graphic points out key features in the Explorer Interface that make it different from the Classic Interface. The graphic represents the appearance of the interface after you make a successful connection to an FTP server.

Display buttons change the way the files are displayed.

This pane displays the remote directory when connected to an FTP site.

The site icon changes when connected.

Site Icon

Site folders. The + means that there are configured sites in the folder.

The status bar displays the current state of the interface.

Look for more detailed information in the Online Help. Most sections are applicable to the Explorer Interface.

27Explorer InterfaceWS_FTP Pro

28

Using the Explorer Interface

The following describes how to get started using the Explorer Interface.

Configuring a Site

Before making a connection, you must either select a preconfigured site, or configure a new site. To configure a new site:

1 Select the folder you want the site configured in.

2 In the right-pane, select New.

3 Follow the directions on the dialog to create a new site.

4 Click Finish once you have gone through the process.

Once you click Finish, the site will be added to the folder.

Making a Connection

Once you have a site configured, you can connect to the site. To do this, all you have to do is click on the site name in the left-pane. If the settings are correct, and the FTP site is accepting connections, the right-pane will display the remote directory once connected.

Transferring Files

Transferring files in the Explorer Interface is very much like the drag-and-drop feature of the Classic interface. To transfer a file:

1 Connect to a site.

2 Open Windows Explorer.

3 Move to the directory that holds the file you want to upload, or to the directory in which you want to place a downloaded file.

4 Select the file or folder you want to transfer (You can select multiple files by holding down the Ctrl key while you click on a file.) Files to be uploaded can be selected from the desktop or from a Windows Explorer window.

5 With the file(s) selected, drag them to where you want them transferred to. If you are uploading them, drag them to your remote directory on the FTP site. If you are downloading the files, drag them to your Windows Explorer window.


Chapter 6: WS_FTP Transfer ManagerThis chapter includes the following topics:

• What is the Transfer Manager

• Transfer Manager Dialogs

What is the Transfer Manager?

The WS_FTP Pro Transfer Manager is used to view the progress of transfers, to schedule the transfer of multiple files, and to view logs for individual transfers.

Transfer Manager Dialogs

The following sections describe each of the dialog boxes that are encountered while using the Transfer Manager.

Transfers Manager Dialog

The Transfer Manager dialog displays a list of all pending, paused, and completed transfers. To access this dialog from either WS_FTP Pro interface: From the View menu, select Transfer Manager

• Source. The path and name of the file or folder that is to be transferred.

• Status. The current status code of the listed item.

• Transferred. The number of bytes transferred.

• Rate (KB/S). The number of Kilobytes being transferred per second.

• Size. The actual size of the file in bytes.

• Time Left. The estimated time left until the transfer is complete.

You can remove completed items individually, or you can select Remove Completed Requests from Transfer Manager on the General tab of the Options dialog.

Use the Batch Mode.

You can use the Batch Mode to add requests to the Transfer Manager (Classic Interface only.)

Batch mode (Classic Interface only)

1 Connect to an FTP server.

2 Click the Batch Mode button.

3 Select a file or files and click the transfer arrow. The file will be placed in the FTP Transfer Manager.

4 Once you have added all of the files to the ’batch,’ click the Batch Mode button to take WS_FTP Pro out of batch mode.

5 In the Transfer Manager, select the requests you want to execute. Hold down the Ctrl key to select multiple requests.

6 From the Transfer menu, select Start.

How to...

29WS_FTP Transfer ManagerWS_FTP Pro

30

Request Properties

You can double click any item on the Transfer Manager dialog to view the Request Properties dialog for that item.

The following information appears on the Request Properties dialog.

• Source Host. The name, URL, or IP address of the transfer’s source.

• Destination Host. The name, URL, or IP address of the transfer’s destination.

• Type. The type of transfer being performed. Either Upload or Download.

• Status. The current status code of the listed item.

• Submit Time. The date and time the file was submitted.

• Start Time. The date and time the file transfer began.

• Total Bytes. The actual size (in bytes) of the file.

• Transferred Bytes. The number of bytes transferred.

• Transfer Rate. The number of Kilobytes being transferred per second.

• End Time. The date and time the transfer ended.

• Transfer Mode. The mode the file was transferred in.

• Source. The path name of the source of the transfer.

• Destination. The path name of the destination of the transfer.

How to...Schedule a transferTo schedule a transfer from the Transfer Manager:

1 Select a request, file, or folder.

2 From the Transfers menu, select Schedule.

3 In the Schedule Item Properties dialog, the date, time, and frequency of the transfer.

4 Click OK to add the item to Scheduler.

How to...Pause a transfer

To pause an active transfer from the Transfer Manager:

1 Select the entry.

2 From the Transfers menu, select Pause.

How to...Remove an itemTo remove an item from the Transfer Manager:

1 Select the file you want removed.

2 From the Transfers menu, select Delete.


Log Window

To view the log for an item, select the item, then from the Transfer menu, select Log. The following window appears:

The log window will contain all actions that have been initiated for the selected transfer, including pause and resume.

Refer to Appendix B for descriptions of error messages that may appear in the log.

31WS_FTP Transfer ManagerWS_FTP Pro

32

Chapter 7: SSL Utility

This chapter describes what SSL is and how you can configure WS_FTP Pro to make secure (SSL) connections.

What is SSL?

SSL (Secure Socket Layer) is a protocol for encrypting and decrypting data sent across direct internet connections. When a client makes an SSL connection with a server, all data sent to and from that server is encoded with a complex mathematical algorithm that makes it extremely difficult to decode anything that is intercepted.

The following is a step by step illustration of how SSL works.

Step 1. The client makes the initial connection with the server and requests that an SSL connection be made.

Step 2. If the server is properly configured, the server will send to the client its certificate and public key.

Step 3. The client compares the certificate from the server to a trusted authorities database. If the certificate is listed there, it means the client trusts the server and will move to step 4. If the certificate is not listed there, the user must add the certificate to the trusted authorities database before going to step 4.

33SSL UtilityWS_FTP Pro

34

Step 4. The client uses that public key to encrypt a session key and sends the session key to the server. If the server asks for the client’s certificate in Step 2, the client must send it at this point.

Step 5. If the server is set up to receive certificates, it compares the certificate it received with those listed in its trusted authorities database and either accepts or rejects the connection.

If the connection is rejected, a fail message is sent to the cli-ent. If the connection is accepted, or if the server is not set up to receive certificates, it decodes the session key from the cli-ent with its own private key and sends a success message back to the client, thereby opening a secure data channel.

The key to understanding how SSL works is in understanding the parts that make SSL itself work. The following is a list of these parts and the role each plays.

Client. In this case, the client is WS_FTP Pro.

Certificate. The Certificate file holds the identification information of the client or server. This file is used during connection negotiations to identify the parties involved. In some cases, the client’s certificate must be signed by the server’s certificate in order to open an SSL connection. Certificate files have the.crt ending.

Session Key. The session key is what both the client and the server use to encrypt data. It is created by the client.

Public Key. The public key is the device with which the client encrypts a session key. It does not exist as a file, but is a by-product of the creation of a certificate and private key. Data encrypted with a public key can only be decrypted by the private key that made it.

Private Key. The private key decrypts the client’s session key that is encrypted by a public key. The private key file has the.key ending. Private keys should NEVER be distributed to anyone.

Certificate Signing Request. A certificate signing request is generated each time a certificate is created. This file is used when you need to have your certificate signed. Once the Certificate Signing Request file is signed, a new certificate is made and can be used to replace the unsigned certificate.

User’s Guide

WS_FTP Pro

How to make an SSL connection

To make an SSL connection with a server configured for SSL that you have an account on:

1 Be sure to select the Secure (SSL) option when you follow the directions for configuring a site.

2 After you click Connect, WS_FTP Pro tells the server that you want to make an SSL connection. The server then transmits to you an identifying certificate, letting the client know who the server is. If that certificate is already listed in your Trusted Authority database, the connection is made.

3 If that certificate is not listed as a trusted authority, the Non-Trusted Authority dialog box appears.

4 Select the option you need and click OK. If the server does not require a certificate to be returned, the secure connection will be established. All data transmitted between you and the server will be encrypted.

If the server you are attempting to make a connection to asks WS_FTP Pro to send back a certificate, follow the direction for Client Certificate Verification.

Client Certificate Verification

If the server you are attempting to make a connection to requires your client to send an identifying certificate back to the server, you must:

1 Configure the site with the Secure (SSL) option selected.

2 Create a certificate. Refer to the section “Generating a Certificate” on page 36 for more information.

3 Send the Certificate Signing Request file to your server administrator.

4 Once the server administrator signs the Certificate Signing Request, it will be sent back to you.

5 When you receive the file, follow the directions for “Selecting a Certificate” on page 37, selecting the new certificate to go in the Certificate box.

6 Connect to the server.


36

Generating a Certificate

To create an SSL certificate:

1 From the Tools menu, select Configure SSL. The SSL Utilities window appears.

2 Click the Certificate Creation tab.

3 Enter a name in the Certificate Set Name box. This will be the name of the certificate that is generated by WS_FTP Pro.

4 Click the Browse (…) button in the Output Location box to select the folder you want the certificate created in.

5 Enter information in all of the Certificate Information boxes:

City/Town. City or town where you are located. (Ex. Augusta)

State/Province. State or Province where you are located. (Ex. Georgia)

Organization. Company or individual user name.

Common Name. This can be either the name of the person creating the certificate or the fully qualified domain name of the server associated with the host.

Pass Phrase. Pass phrase that is to be used to encrypt the private key. It is important to remember this pass phrase. The pass phrase can be any combination of words, symbols, spaces, or numbers.

Pass Phrase Confirmation. Re-enter the same pass phrase as above.

User’s Guide

WS_FTP Pro

Country. The country you are in. This must be a valid two letter country code. (Ex. US)

E-mail. E-mail address of the person the certificate belongs to.

Unit. Name of organizational unit. (Ex. Research and Development)

6 After all of the boxes are filled in correctly, click Create to generate the keys, certificate, and certificate signing request. Note If all of the boxes are not filled in, you cannot create the certificate.

If you are creating a certificate to be used by WS_FTP Pro, you should send the certificate signing request (by E-mail) to your server administrator. If they require it, they will sign the certificate and return it to you. The returned certificate should be the one you identify in the Certificate Selection tab.

Selecting a Certificate

The Certificate Selection tab is used to choose which private key and certificate you want to use during SSL connection negotiations. If a new certificate has not been created, follow the directions for “Generating a Certificate” on page 36.

To select an SSL Certificate:

7 Click the Browse (…) button next to the Private Key box to select the private key you want to use during SSL negotiation.


38

8 Click the Browse (…) button next to the Certificate box to select the certificate you want to use during SSL negotiation. The certificate you use must have been created using the key you selected for the Private Key box.

9 Enter the pass phrase associated with that certificate in both the Pass Phrase and the Pass Phrase Confirmation boxes. A pass phrase can be any combination of words, symbols, spaces or numbers. It is case sensitive and must be written exactly the same way each time it is used.

Without the correct pass phrase in both boxes, the certificate and private key cannot be verified and the selection cannot be saved.

10 Click Apply to save your entries.

Clicking the Reset button erases what you have done since the last time new settings were applied.

Trusted Authorities

The Trusted Authorities tab stores a list of certificate names that are recognized by WS_FTP Pro.

Certificate Display:

Issued To. Who the certificate was issued to.

Issued By. Who the certificate was signed by.

Expires. Date on which the certificate expires.

User’s Guide

WS_FTP Pro

Adding a Certificate

To add a certificate to the database:

1 Click the Import button and select the path and file name for the certificate. The Add Certificate? dialog box appears.

2 Review the information on that dialog box and click Yes to add the certificate to the database.

Exporting a Certificate

To export a certificate from the Trusted Authorities database:

1 Select the certificate you want to copy out of your database.

2 Click the Export button.

Select the folder you want to copy the certificate to and enter the name you want to save the certificate file as.

3 Click OK.

Removing a Certificate

To remove a certificate:

1 Select the certificate to be removed.

2 Click Remove.

3 A warning appears advising you to export the certificate before you remove it. Removing the certificate deletes the certificate file.

4 Click OK to remove the certificate.


40

Non-Trusted Certificate

When you connect to a server using the SSL connection option, that server sends you a certificate. If that certificate is not listed on the Trusted Authority tab, or if it was not signed by a certificate on this list, this dialog box appears.

Certificate Information:

Issued To. Name of the person or company who the certificate belongs to.

Issued By. Name of the person or company who signed the certificate.

Active From. The date on which this certificate was activated.

Expires On. The date the displayed certificate will no longer be a valid certificate.‘

Options

Allow this connection only. If this option is selected, the connection will be made, but WS_FTP Pro will still not recognize the certificate as a trusted authority. The next time you attempt to connect to this server, this dialog box appears once again.

Trust this certificate. If this option is selected, the connection will be made and the certificate will be added to the trusted authority database in the Trusted Authority tab, so future connections can be made without you being prompted.

Do not allow this connection. If this option is selected, the connection will be terminated.

User’s Guide

WS_FTP Pro

Chapter 8: Synchronizing Files and Folders

The WS_FTP Synchronize Utility lets you synchronize (or “mirror”) directory structures between your system and a remote FTP server with minimal intervention.

It lets you keep remote sites up-to-date by automatically uploading files which have changed while deleting files that have been removed from the master directory. This is especially useful for quickly and efficiently updating Web sites.

This chapter gives an overview of the Synchronize Utility and some examples of how you might use it. For detailed instructions on using the Synchronize Utility, start the Synchronize Utility and use its online Help.

A Word of Caution

The Synchronize Utility can easily erase or overwrite large numbers of files without prompting you.

To verify that the Synchronize Utility will do what you want, please run any new control files in “test mode” before running them for real. You can then view the contents of the status window to verify that the control file will do what you expect.

You should look for lines such as:

# deleting filea.ext# sending fileb.ext 19960217/00:00 (19950217/00:00)# receiving filec.ext 19960217/00:00 (19950217/00:00)

Using the Synchronize Utility

Start the Synchronize Utility by doing one of the following:

• From the Tools menu, select Synchronize.

• Click the Windows Start button and select Programs -> WS_FTP Pro -> WS_FTP Pro Synchronize Utility.

41The Synchronize UtilityWS_FTP Pro

42

Example

The following is an example of how you might use the WS_FTPSynchronize Utility.

When you click the Go button, the control file named rarmstrong (it is at the end of the path in the Control file name box) is executed according to the parameters set on the WS_FTP Synchronize Utility screen:

• Synchronize makes a connection with the FTP site defined in the Site name box and logs on with the user name and password supplied.

• Once the connection is made, the program navigates to the ‘/idstuff’ directory on the FTP site and the ‘C:\docutorials’ directory on your PC.

• According to the options selected, the FTP site directory is made to mirror the local directory by creating folders not already there, and copying or updating files that need to be changed or added in order to make the directories mirror each other.

• Since the Force update of destination option is selected, all files that do not match are copied over or added regardless of the version date on the destination folder.

User’s Guide

WS_FTP Pro

• Since the Secure Connection (SSL) option is selected, Synchronize attempts to make an SSL connection with the FTP server, using the settings you set in the SSL Configuration Utility. For more information on SSL see “Chapter 7: SSL Utility” on page 33. If the SSL Connection fails, the Synchronize job will fail.

• If you want to schedule this task to run at on a regular basis, or at a certain time of day, click the Schedule button. The Schedule Item Properties dialog appears. Use this dialog to set the time, date, and frequency of the synchronize job. For more information on using the WS_FTP Scheduler, see “Using the Scheduler” on page 55.

Exclusions

WS_FTP Synchronize has the ability to exclude directories and/or files during the synchronize process. This exclusion information is entered in the Exclude box. The entered information is in the form of a comma separated set of values. Spaces are interpreted as part of the exclusion, so do not put spaces after (or before) a comma unless they are part of the files/directories you wish to exclude. Wildcards consisting of * and? can be used in directory and file names. An example of this is shown below:

/mydir/*.exe,mydir\,m*ir\,\m?dir\,/mydir/nextdir/myfil?.*,mydir\*.exe

An explanation of each exclusion follows:

/mydir/*.exe

An absolute file exclusion. This will exclude all .exe files in the mydir directory, but the path is taken from the root of the file system.

mydir\

A relative directory exclusion. This will exclude any directory named mydir anywhere in the file system.

\m?dir\

An absolute directory exclusion. This will exclude all directories that match the mask m?dir, but the path is taken from the root of the file system. The ? is a substitute for any single character.

m*ir\

43The Synchronize UtilityWS_FTP Pro

44

A relative directory exclusion. This will exclude any directory that matches the mask m*ir from anywhere in the file system. The * means that the name can have any number and value of character in between the "m" and the "ir."

/mydir/nextdir/myfil?.*

An absolute file exclusion. This will exclude any file beginning with myfil with one arbitrary character and any extension in the directory /mydir/nextdir.

mydir\*.exe

A relative file exclusion. This will exclude any .exe files in any directory named mydir anywhere in the file system.

Using the Synchronize Utility from the Command Line

The Synchronize Utility has been designed to be a command line utility that can be scheduled and run unattended. To do this, you must first use the user interface to set up and test a control file for the synchronization task.

Once this has been done, you can run the Synchrionize Utility directly from the command line by using the following syntax:

ftpsync -f controlfile.ctl

You can also add this command to a batch file and schedule it using WS_FTP Pro Scheduler. For more information on using command line batch files, see “Using a Batch File” on page 67. For more information on using the WS_FTP Scheduler, see “Using the Scheduler” on page 55.

User’s Guide

WS_FTP Pro

Chapter 9: The Find Utility

The WS_FTP Find Utility lets you search an FTP site for files that match your criteria, and then transfer the found files to your PC. This is especially useful for anyone who is looking for one particular file on a large, complex FTP site.

This chapter gives an overview of the Find Utility and some examples of how you might use it. For detailed instructions on using the Find Utility, start the Find Utility and use its online Help.

Using the Find Utility

To find a file on an FTP site:

1 Start the Find Utility by doing one of the following:

• From the Tools menu, select Find.

• Click the Windows Start button and select Programs -> WS_FTP Pro -> WS_FTP Find Utility.

2 Use the Look in list box to select a site previously searched or click the Browse button to specify the site to which you will connect and search. You can also type in a host name or FTP URL.

3 Enter your search criteria. You can search by name, date modified, size, or any combination of the three.

4 Click Find Now. The Find Utility connects to the FTP site and searches according to your criteria.

45The Find UtilityWS_FTP Pro

46

For example, if you search the Ipswitch FTP site for a file named filelist.txt, the following results are displayed.

Using the Search Results

Once you locate a file on an FTP site, you can:

• Transfer it.

• Schedule it for transfer at a later time, by selecting Send to Scheduler from the right-mouse menu.

To transfer a file:

1 In the dialog box above, select the file you want to transfer, and select Transfer from the right-mouse menu. A browse window appears.

2 Select the folder to which you want to download the file.

The search found this file.

User’s Guide

WS_FTP Pro

Examples

The following are examples of different types of searches.

Finding a File When You Are Not Sure of Its Name

The graphic below shows how to search for a file when you are not sure of the correct full name. In this case, the name begins with ws_f, but the rest of the name is unknown. The * at the end is a “wildcard” that takes the place of the missing characters. When this search is run, the Find Utility locates every file on the site that begins with ws_f.

The results of the search are shown below.

Search text


48

You can also use wildcard characters (* and ?) at the beginning of a name if you are unsure about the beginning characters. For example, searching for *.exe returns all files ending with the .exe file extension.

Finding a File Modified During a Specific Time Period

To search for a file modified during a specific time period, click the Date Modified tab and set the options you need. In the example below, the WS_FTP Find Utility will search for all files modified between April 10, 2001 and April 20, 2001.

Finding a File in a Particular Folder

If you know the name of the folder in which the file you are looking for is stored, you can narrow your search by having the Find Utility look only in that folder.

User’s Guide

WS_FTP Pro

To locate a particular folder:

1 Click the Browse button next to the Look In field to connect to the selected site and display a list of the available folders.

2 Select the folder that you want to search.

3 Click OK. The Look In box is filled in with the path of the selected folder.

4 Click Find Now to search through the files in that folder.

Finding a File Smaller Than a Certain Size

If you want to limit the size of the files found in a given search, enter the FTP site and file name on the Name & Location tab, then click the Advanced tab.

In the Size is box, you can select At least or At Most then enter the file size in kilobytes in the KB box.


50
User’s Guide
WS_FTP Pro

Chapter 10: Scripting

The WS_FTP Scripting Utility allows you to group any number of file transfer tasks into a script that can be executed with one action. This can be especially useful for file transfers that you do repeatedly.

This chapter gives an overview of the Scripting Utility and some examples of how you might use it. For detailed instructions on using the Scripting Utility, start the Scripting Utility and use its online Help.

Using scripts, you can:

• Connect to FTP sites

• Upload or download files

• Set the transfer mode

• Make, delete, and rename folders

• Delete and rename files

• Execute a DOS command

Scripts can also have some limited flow control. They can:

• Check for the success or failure of the previous command

• Jump to another point in the script if either success or failure is detected

Suppose you post weekly reports on your company’s FTP server for your co-workers in other cities to download. Let’s assume you place the current week’s reports in a folder named Current. You could create a script that:

• Changes the name of last week’s Current folder to Prior.

• Creates a new folder named Current.

• Uploads your current weekly reports to the Current folder.

You can also create scripts for downloads that you do repeatedly.

Using Scripting

Start the Scripting Utility by doing one of the following:

• From the Tools menu, select Script.

51The Scripting UtilityWS_FTP Pro

52

• Click the Windows Start button and select Programs -> WS_FTP Pro -> WS_FTP Pro Scripting Utility.

Writing and Debugging Scripts

To write and/or debug a script, start the Scripting Utility.

The Script Editor/Debugger window appears.

An MS-DOS window is automatically opened behind the Editor/Debugger window to show you the output of SHELL commands.

Executing Scripts

You can execute scripts from either the Command Prompt or from the Scripting Utility itself.

Executing a Script from the Command Prompt

Go to the Command Prompt and type ftpscrpt followed by the appropriate command line parameters. For example:

ftpscrpt -f script1.scp

There are other parameters you can use with the ftpscrpt command. For detailed information, go to the Scripting Utility online Help and see “Executing Scripts.”

To be able to run a script from any location on your hard disk, we recommend that you place the Scripting Utility folder in the Path statement in your Autoexec.bat file – if you are running Windows 95, Windows 98, and Windows ME. If you’re using Windows NT or Windows 2000, add the WS_FTP Pro folder to the path variable in the System Environment.

Running a Script from the Scripting Utility

To run a script from the Scripting Utility, start the utility, open the script, and click Go.

User’s Guide

WS_FTP Pro

Example

In the following example, the script:

1 Turns on the Trace command to send detailed information to the transfertrace.txt file.

2 Creates a log called transferlog.txt in the C:\ directory.

3 Logs onto the server with the user name sdavis.

4 Logs onto the server with the password fourthandgoal.

5 Connects to the FTP server ftp.mywebprovider.com.

6 Changes the remote directory to /user/sdavis/images.

7 Changes the local directory to C:\My Documents\My Pictures

8 If the MGET is successful, the script executes the FILEDELETE label.

9 If the MGET fails, the script executes the DISCONNECT label.

10 All files ending in .jpg are copied from the remote directory to the local directory.

11 This line identifies the FILEDELETE label.

12 All files ending in .jpg are deleted from the /user/sdavis/images remote folder.

13 This line identifies the DISCONNECT label.

14 Disconnects from the FTP server.

53The Scripting UtilityWS_FTP Pro

54
User’s Guide
WS_FTP Pro

Chapter 11: Scheduler

The WS_FTP Pro Scheduler lets you create FTP tasks or “jobs” for transfers that you need to perform repeatedly or manually at a particular time. Each task can consist of any number of uploads and downloads of files and folders.

This chapter gives an overview of the Scheduler and some examples of how you might use it. For detailed instructions on using the Scheduler, start the Scheduler and use its online Help.

Using the Scheduler

To access the Scheduler window, do one of the following:

• Select WS_FTP Scheduler from the Utilities menu in the WS_FTP Pro Classic interface.

• Click the Windows Start button and select Programs -> WS_FTP Pro -> WS_FTP Pro Scheduler.

Once you are in the Scheduler window, you are ready to set up a file transfer task. You can:

• Add a pre-existing script to run at a particular time. (For more information on creating scripts, see “Chapter 10: Scripting” on page 51.)

• Drag and drop a file from the WS_FTP Pro Classic or Explorer Interface to the Scheduler window to create an upload task.

• Create a task from within WS_FTP Pro, WS_FTP Pro Find Utility by right-clicking the file and selecting Send to Scheduler.

• Create a task from the Synchronize Utility or the Transfer Manager.

55SchedulerWS_FTP Pro

56

The WS_FTP Pro Scheduler will run the task at the time you schedule it to run, or you can make the task run on demand by using the Run Now option.

Examples

The following are examples of how you might use the WS_FTP Scheduler.

Adding a Script to the Scheduler

To add a script to the scheduler:

1 From the File menu, select New > Custom.

A Schedule Item Properties dialog appears.

2 In the Start Date and End Date boxes, set the dates for when you want this recurring task to begin and when you want it to end.

3 In the Start Time box, enter the time of day you want the task to be run.

4 In the Executable box, enter the full path to the ftpscript.exe application.

5 In the Command box, enter -f followed by the full path to the script you want WS_FTP Scheduler to run.

6 If you are on an NT workstation, you must enter your NT user login and password in the boxes provided.

7 Select the frequency of the recurring transfer in the Schedule Frequency area.

User’s Guide

WS_FTP Pro

8 Click OK to add this task to the scheduler.

Updating a Web Site on a Nightly Basis

If you have a Web site you would like to update every night, without having to manually upload all of the files you have recently changed, you can set up a scheduled task to have it run as frequently as you like.

Scheduling Multiple items:

1 Select the files in WS_FTP Pro and select Send to Scheduler from the right-mouse menu.

You can select multiple files or folders by holding the Ctrl key and clicking the name.

The Schedule Item Properties dialog appears.

.



4 The Executable, Command, and Task Name boxes are filled in for you. (Note that in the Command box, there is a .tmp file identified. This file tells the application which files to download and where to transfer them to and from.)


57SchedulerWS_FTP Pro

58



Scheduling a single item (this can be a folder with multiple items inside)

1 Select the file in WS_FTP Pro and select Send to Scheduler from the right-mouse menu.

The Schedule Item Properties dialog appears.






User’s Guide

WS_FTP Pro

Chapter 12: Using Firewalls

Some organizations separate their local networks from the rest of the Internet by installing a firewall or “gateway.” A firewall is a system or software which is configured to prevent particular types of access or information from entering the network. Most firewalls block the flow into the local area network, but allow individuals to access most resources outside of the network.

WS_FTP Pro lets you enter information about a particular firewall into a firewall configuration, which you can then use when connecting to a particular FTP site from behind that firewall. You can configure the firewall once, and then assign that firewall configuration to those sites that require it.

With the FireScript editor, you can edit firewall scripts to work the way you want them to work. For more information, see “Appendix A: FireScript Editor” on page 73.

Multiple Firewalls

There are several reasons you might want to create more than one firewall configuration. If you use a laptop computer in different locations that have different firewalls, you will want to set up a firewall configuration for each location, so you can switch to the appropriate firewall configuration when you are in each location.

Another reason you might want to set up multiple firewall configurations is that your network could have more than one router configured as a firewall. In this case, you would assign a different firewall configuration to an FTP site depending on which part of the network you are working from.

Furthermore, you might have a number of trusted sites (for example, FTP sites owned by your company) for which you would use a different firewall (or no firewall).

59Using FirewallsWS_FTP Pro

60

Firewall Types

The following table lists all conventional firewall types and the information about each that you will need to procure and enter into WS_FTP Pro.

Configuring a Firewall

To enter firewall information, you will need to get data about your firewall from your network administrator. For more information, see Firewall Types above.

In the Classic Interface, on the Connection dialog, configure a firewall as follows:

1 Click the Firewall tab.

2 Select New Firewall from the File menu.

3 Enter a name for the firewall as well as the firewall’s official host name or IP address.

4 Click OK. The new firewall appears in the Configured Firewalls list.

Type of Firewall Information you need to enter in WS_FTP Pro

Proxy OPEN Host Name (or Address)

SITE hostname Host Name (or Address), User Name (ID)

Transparent User Name (ID), Password

USER after logon Host Name (or Address), User Name (ID), Password

USER fireID@remoteHost Host Name (or Address), User Name (ID), Password

USER remoteID@fireID@remoteHost

Host Name (or Address), User Name (ID), Password

USER remoteID@remoteHost fireID

Host Name (or Address), User Name (ID), Password

USER with no logon Host Name (or Address)

For some router-based firewalls, you will want to use passive mode, in which the data connections are established by the FTP client (WS_FTP Pro) rather than by the FTP site.


5 Enter the firewall User ID or leave blank if not used.

6 Enter a Password. We do not recommend turning on Save Password unless you are the only user with access to your computer.

7 Select a Type.

8 Enter a Port number.

9 Click Save.

You can now assign the firewall configuration to the site, as described in Using a Configured Firewall below.

In the Explorer interface, configure a firewall as follows:

1 If you are not already on the Firewall tab:

• Select a site on which you want to use the firewall.

• Select Properties from the File menu.

• Click the Firewall tab.

2 Click the New button.

3 Enter a name for the firewall configuration.

4 Enter the firewall Host Name or IP Address.

5 Enter the firewall User ID (User Name) and Password.

If you use the name Firewall as the name of a firewall configuration, you can apply the firewall configuration named Firewall only by selecting the name “default” when you attempt to use the configuration as described below.

61Using FirewallsWS_FTP Pro

62

6 Select the firewall Type from the drop-down list.

7 Enter the Port number.

8 Click Save.

You can now assign the firewall configuration to the site, as described below.

Using a Configured Firewall

Once you have configured a firewall, you can then apply the firewall configuration to an FTP site.

In the Classic interface, on the Connection dialog box:

1 Make sure you are on the Host Info tab (not the Firewall tab).

2 In the Firewall box, select a firewall configuration.

In the Explorer Interface:

1 Select a site.

2 Select Site Properties from the File menu.

3 Make sure you are on the Host Info tab (not the Firewall tab).

4 In the Firewall box, select a firewall configuration.


Chapter 13: Using the Command Line

You can use the command line from the MS-DOS prompt to run the WS_FTP Pro Classic interface.

When you use the command line, you are actually running a subset of the functionality of the Classic interface. Using the command line, you can:

• Upload and download files

• Specify ASCII or binary transfer mode

• Convert file names to lowercase when uploading

• Set up pre-scheduled transfers

• Create batch files that will handle multiple commands

Basic Command Line Syntax

The following illustrates the correct command line syntax, broken down by argument type.

(command name: wsftppro) (source) (destination)

Written out, a command using this format would look like this:

wsftppro -s local:c:\tartan.bmp -d robert!border:/pub/tartan.bmp

The section below shows the breakdown of that command into the parts illustrated above. The command name wsftppro must always be placed in the beginning of the command.

Site Information


If you use a configured site from the command line, WS_FTP Pro uses the User ID, Password, and Account Name you saved in the site configuration. To do this, place the site folder and site profile in front of the remote directory (this can be either the source or the destination). The site folder and site profile has to be separated by the ! symbol. In the example above, we use the border site profile stored in the robert folder.

If you have saved a password with the site, WS_FTP logs you on using the saved password. If you have not saved a password with the site, you will receive the regular password prompt, unless you use the -u and -w

So you can use the command line from any location on your hard disk, we recommend that you place the WS_FTP Pro folder in the Path statement in your Autoexec.bat file, if you are running Windows 95, 98, 2000, or ME. If you are using Windows NT, add the WS_FTP Pro folder to the path variable in the System Environment. Otherwise, change to your WS_FTP Pro folder when you use the commands.

63Using the Command LineWS_FTP Pro

64

arguments. For example:

wsftppro -u username -w password -s robert!border:/pub/tartan.bmp -d local:c:\armstrong\

If you have saved an account name in the site configuration, the command line logs you on using the saved account name. If you have not saved an account name, you can use the -c argument to specify the account name when you enter the command line. For example:

wsftppro -c account -s robert!border:/pub/tartan.bmp -d local:c:\armstrong\

If you do not use a configured site profile, you must put the IP address, URL, or host name in the source or destination argument to connect to that site. See the Transfer Source and Transfer Destination sections for examples of command line commands that use this.

Transfer Source


The transfer source argument begins with the -s argument, followed by the label for the source, and the path to the item or items being transferred. If the source of the transfer is your local system, the source label is local. If you are doing a download, the source label is either the site folder!site name or the IP address, FTP URL, or Host name of the FTP site. For example:

wsftppro -s robert!border:/pub/tartan.bmp -d local:c:\tartan.bmp

or

wsftppro -s ftp://username:[email protected]/pub/tartan.bmp -d local:c:\armstrong\

or

wsftppro -u username -p password -s 156.21.50.78:/pub/tartan.bmp -d local:c:\

Transfer Destination


The transfer destination argument begins with the -d argument, followed by the label for the destination, and the path to where item or items are being transferred to. If the destination is your local system, the destination label is local. If you are doing an upload, the destination label is either the site folder!site name (as in the example above) or the IP address, FTP URL, or Host name of the FTP site. For example:

User’s Guide

WS_FTP Pro

wsftppro -s local:c:\tartan.bmp -d ftp://username:[email protected]/pub/tartan.bmp

or

wsftppro -s local:c:\tartan.bmp -u username -w password -d 156.21.50.78:/pub/

tartan.bmp

File Transfer Options

Uploading Files

To upload a file, use the basic command syntax with the file or files you want to upload identified in the source argument. For example; if you want to copy the file tartan.bmp from the armstrong folder on your C: drive and place it in the /pub/ folder on the site identified in the border site profile use:

wsftppro -s local:c:\armstrong\tartan.bmp -d robert!border:/pub/tartan.bmp

or,

wsftppro -s local:c:\armstrong\tartan.bmp -d robert!border:/pub/

Notice that the second option omits the file name from the destination location. You can do this when you want the transferred file to have the same name as it does in the source location. However, note that you must enter the trailing slash after the destination folder in order for this to work.

Downloading Files

Use the same command syntax as described above for downloading files, except that, the source of the transfer is the remote system instead of your local system.

wsftppro -s border:/pub/tartan.bmp -d robert!local:c:\armstrong\tartan.bmp

In the example above, we are connecting to the remote system using the border site profile and downloading the tartan.bmp file to the armstrong folder on our C: drive.

Renaming Files

To rename a file as you upload it, enter a new file name after the destination folder. For example, to upload the Tag.doc file and rename it NewTag.doc on the FTP site, type:

wsftppro -s local:c:\sports\Tag.doc -d robert!border:/pub/drop/NewTag.doc


66

Transferring multiple files from the same location

If all the files you want to transfer are in the same folder, you can use the wildcard characters, * and ?, in the file name. For example, if you want to upload all of the files in C:\Sports\ use:

wsftppro -s local:c:\sports\*.* -d robert!border:/pub/drop/

Or, to transfer all .doc files in the same folder, enter (at the MS-DOS prompt or in a batch file):

wsftppro -s local:c:\sports\*.doc -d robert!border:/pub/drop/

To transfer multiple files not in the same folder, see “Multiple Folders or Commands” on page 68.

Converting File Names to Lower Case

When uploading files, you can have WS_FTP Pro convert file names to lower case by adding the -lower argument at the end of the command line. For example, if the file you want to transfer is named Tag.doc, WS_FTP Pro can upload it as tag.doc by using:

wsftppro -s local:c:\sports\Tag.doc -d robert!border:/pub/drop/ -lower

File Transfer Modes

You can transfer files in binary mode or in ASCII mode. We recommend using binary mode to transfer all files unless you know the file contains only text, then you are able to use ASCII mode.

To specify the transfer mode, you use the -binary or -ascii argument at the end of the command string.

When you do not specify the transfer mode in the command line, WS_FTP Pro transfers the file in whatever file transfer mode is the default in the WS_FTP Pro Classic interface. Therefore, if you plan on using the command line more than just occasionally, set the Startup Transfer Mode to Auto Detect.

Transferring Files with Spaces in the File Names

If you are transferring a file whose name has spaces in it, you have two options. You can enclose that portion of the command line in quotes, or use the MS-DOS name of the file (as shown in the Dir listing you get from the MS-DOS prompt.)

User’s Guide

WS_FTP Pro

Enclosing the Command Line in Quotes

If the file you want to transfer is named my tartan.bmp, use:

wsftppro -s "local:c:\armstrong\my tartan.bmp" -d "robert!border:/pub/my tartan.bmp"

Using the MS-DOS Name

If the file you want to transfer is named my tartan.bmp in Windows 95, but appears as my~1.doc when you use the Dir command at the MS-DOS prompt, you can use the MS-DOS file name to transfer the file. To do this (using the first example in this chapter), enter (at the MS-DOS prompt or in a batch file):

wsftppro -s local:c:\armstrong\my~1.bmp -d robert!border:/pub/my~1.bmp

Using a Batch File

Instead of typing the command at the MS-DOS prompt, you may find it more expedient to enter the command line into a batch file (a text file with the file extension .bat). This makes it easier to correct mistakes and to run the same command again.

You run the command by invoking the .bat file at the MS-DOS prompt, double-clicking the icon for the .bat file from within Windows, or running the .bat file from another application (such as WS_FTP Pro Scheduler).

Here is a batch file (for the example at the beginning of this chapter) as viewed from a Windows text editor:

When you run the batch file named tartan.bat, WS_FTP Pro uploads the tartan.bmp file to the border FTP site.

Note that using a batch file involves placing the command name wsftppro at the beginning of each line in the file. Since each instance of the command name starts the WS_FTP Pro application (and connects to the FTP site), you would only use a batch file to work with one command at a time. If, on the other hand, you want to issue a group of commands, follow the procedure in “Multiple Folders or Commands” on page 68.

Remember that if a file name has a space in it, you must enclose that entire argument in quotes.

You cannot run 2 batch files at the same time.


68

Multiple Folders or Commands

To transfer files to or from multiple source or destination folders, or to issue multiple commands, use the -m argument followed by the name of a text file that contains the commands. To transfer files from several locations on the hard disk described in the first example in this chapter, enter (at the MS-DOS prompt or in a batch file) something like:

wsftppro -m xferall.txt

where the content of xferall.txt (as viewed in Windows Notepad) is:

Note that:

• The command name wsftppro must not appear in the text file

• Each line of text must contain only one command line.

• Each command line can contain any of the arguments described in this chapter.

• If a file name has a space in it, you must enclose that entire argument in quotes.

Pre-scheduled Transfers (“Automated Transfers”)

You can use the command line to schedule transfers that you want to run automatically. To do this, you create a batch file as described above, and then run the batch file using WS_FTP Scheduler. For more information, see “Chapter 11: Scheduler” on page 55.

When you use the command line to perform a pre-scheduled transfer, you may the -quiet parameter to prevent WS_FTP Pro from displaying a message box if and when an error occurs. This is particularly useful for avoiding a situation in which WS_FTP Pro might otherwise prompt for user input, such as clicking the OK button in an error message. This way, you can pre-schedule transfers to run automatically when you’re not at your computer. (When you return to the computer, you can always check the log file to see if there were any problems.)

User’s Guide

WS_FTP Pro

To use the examples shown above, you could do a pre-scheduled transfer by creating the following batch file:

as well as the following text file:

Then, you could have the Scheduler run the auto10.bat file at 10:00 PM each night.

Remember that if a file name has a space in it, you must enclose that entire argument in quotes.

Transferring a Folder Containing Subfolders

Since you are not able create folders using the command line, you will not be able to transfer a folder by simply specifying the folder name in the command line, or by using wildcards.

To transfer a folder using the command line, you need to use some other method to create the folder and its sub folders in the destination location. Then, you can use the same procedure as described in “Multiple Folders or Commands” on page 68. In the text file, you will have one command line for each sub folder.

For example, if you want to transfer the entire folder named armstrong to the border FTP site. The armstrong folder contains a number of files as well as three sub folders named family, arms, and photos.

Once you have created the border folder and its sub folders in the destination location, create the following text file:

The command you enter (at the MS-DOS prompt or in a batch file) is:

wsftppro -m DirStruct.txt


70

Using a Site Profile with a Host Name

You can use the -p argument to use site profile options with any FTP server, not just the one identified in the profile. For example:

wsftppro -p highland!armstrong -s local:c:\armstrong\my~1.bmp -d ftp.anysite.com:/pub/my~1.bmp

In this example, WS_FTP Pro will connect to ftp.anysite.com using the options set up in the armstrong site profile.

Extras

Here are a few more arguments and uses of the command line that some users have found helpful. These are listed below.

To have WS_FTP Pro display a dialog box that prompts you for the command line, type: wsftppro -ask

To launch the WS_FTP Pro Classic interface and default to the site configuration for the border site: wsftppro -p robert!border

To prevent WS_FTP Pro from displaying error messages, use the -quiet argument. This is useful if you want to do automated transfers when no one is around to respond to a message. An example:

wsftppro -s local:c:\armstrong\tartan.bmp -d robert!border:/pub/tartan.bmp -quiet

Summary

Here is a list of all arguments you can use in the command line.

Arguments (alphabetical)

When to use Important restrictions

-ascii Use -ascii when transferring text files.

-binary Use -binary when transferring non-text files such as executable programs, word processing documents, and so on.

-c account Use -c to work with sites that require an account for the user to log in, or to access partitions. account is the name of your account on the FTP site.

-d path_and_filename

Use -d to indicate the destination path and desired file name of the file you want to upload or download.

User’s Guide

WS_FTP Pro

-lower Use -lower to have WS_FTP Pro con-vert file names to lower case letters when you transfer from your PC to an FTP site.

If you use the -lower argument, it must be at the very end of the command.

-m text_file Use -m to do transfers that involve multi-ple source locations, multiple destina-tions, or multiple commands. text_file is the name of the file that contains the com-mands.

-p site_name Use -p to connect to a configured site, where site_name is the name of the site configuration. The site configuration must be in the default .ini file or in the .ini file specified with the -i argument.

The -p argument must precede all arguments except -i.

-quiet Use -quiet to prevent WS_FTP Pro from displaying message boxes.

-s path_and_filename

Use -s to indicate the source path and file name of the file you want to upload or download.

-u userID Use -u to use sign on using the userID.

-w password Use -w to identify password as the pass-word to use to connect to the ftp site.


72
User’s Guide
WS_FTP Pro

Appendix A: FireScript Editor

This appendix describes the purpose and syntax of the FireScript language and how it used to make an FTP connection through a firewall.

What is a FireScript?

A FireScript allows you to customize the sequence of commands and responses used to log in to an FTP server. This customization may be necessary if your FTP server requires any non-standard commands to be issued before or after logging in, or if certain types of firewalls are between the client and the server.

FireScripts are written in a custom FireScript language, developed specifically for use by WS_FTP Pro. FireScripts can perform the same functions that WS_FTP Pro uses internally to connect to a host or firewall type. FireScripts, however, let you determine if and when these functions are used. In particular, the FireScript determines when to autodetect the host type, and when to go secure with an SSL connection. The script can choose whether or not to try the XAUTH command, and also whether it is necessary to log in to a user account after sending the user ID and password.

FireScript Components

A FireScript is broken into three sections: fwsc, comment and script. As in a Windows ini file, the name of the section appears alone on a line, in square brackets, followed by the rest of the section.

The fwsc section is internally structured with name=value pairs in the same manner as a Windows ini section. It contains identifying information about the script, and indicates what variables will be required by the script.

The comment section is free-form text intended for human readers. It is ignored by the script executive.

The script section contains the scripts executable portion and conforms to the FireScript syntax.

73FireScript EditorWS_FTP Pro

74

Below is an example FireScript demonstrating this layout.

[fwsc]

author=Ipswitchconnectto=firewall

… other values not shown would typically include 'required=' and 'version='

[comment]

This is an example script that connects to an FTP proxy. It is incomplete because many of the commands required to connect have been deleted for clarity. The main purpose is to demonstrate the organization of the FireScript

into three sections.

[script]send ("OPEN %HostAddress") {}tryssl;send ("USER %HostUserId"){

case (300..399) :

continue ;case any :

return (false) ;}

… most of script not shown due to the size.

label success;gossl;return (true);

The fwsc Section

The fwsc section lets you specify information about the script in a manner similar to a Windows ini file. Most of the parameters are present for informational purposes. This includes the author and version fields. A few of the parameters are used by the script executive in determining whether or not to show the login dialog, and which IP address to use.

User’s Guide

WS_FTP Pro

The parser recognizes and stores values for the following parameters:

Unrecognized parameters are ignored.

The Comment Section

Use the comment section to describe the actions of the FireScript. The FireScript code should be well described, so it will be easier to understand and update later. The FireScript executive ignores the comment section.

You can also insert comments in the script section by using the ’//’ comment delimiter as in C++ and Java. Any text on a line following the ’//’ sequence is ignored by the parser.

The Script Section

The script section consists of a sequence of statements that send commands to the firewall or to the FTP server. Some of these statements have results, or trigger responses from the firewall or FTP server. There is a simple control structure that allows the script to take different paths of execution, based on these results or responses.

fwsc Parameters

Parameter Meaning and Values

author Informational only. Author of the FireScript.

version Informational only. Version number of the script file.

verdate Informational only. Date on which this version was updated.

required A comma delimited list of fields that must be present for the FireScript to execute. The login dialog is displayed if all required fields are not present, and the ’Connect’ button is disabled until all required fields have been filled in.

preask A comma delimited list of fields that are not required but which, if not present, will cause the login dialog to be displayed.

connectto ’firewall’ or ’host’. This parameter tells WS_FTP Pro which IP address to use when establishing the connection.


76

The Connection Sequence

A request for connection to an FTP site comes from user actions in either the Classic or Explorer interface, or by one of the WS_FTP Pro utilities such as Find or Synchronize. Sometimes, additional connections are requested by the Transfer Manager to resume or to speed up transfers. All connections are created by the CreateConnection function in the WS_FTP Pro API.

The connection sequence consists of two stages.

• Stage 1: Establish the connection with either the firewall or the FTP server.

• Stage 2: Send commands to log in and authorize the connected user. It is during this stage that the commands in a FireScript are executed.

The first stage works the same whether WS_FTP Pro is using a FireScript or using one of its internal firewall types. Before executing the script, WS_FTP Pro checks the fwsc section for the list of fields marked as required and preask. If any are missing, it displays the login dialog. If the user fills in all required information and presses Connect, WS_FTP Pro then checks the connectto field. Depending on this field, it will either establish a connection to the firewall's IP address and port, or to the FTP server's IP address and port. If this field is not present, WS_FTP Pro defaults to the IP address of the firewall, if present.

After the connection is established successfully, and a valid socket is opened, WS_FTP Pro calls the FireScript executive to execute the FireScript. If the FireScript logs in okay and returns success, the CreateConnection function returns the authorized connection to the caller.

The FireScript Language

The FireScript language contains a limited version of elements you may be familiar with if you have written scripts or programs in other languages. It uses variables, declarations, and statements to perform actions and direct program flow. Each of these elements is described in the following sections.

User’s Guide

WS_FTP Pro

Syntactically, FireScript statements are terminated by semicolons. They may therefore extend across multiple lines, and you can have multiple statements on a line. A string however, may not span lines. The final closing quote must appear on the same line of source code as the opening quote. For example, the code below is valid:

contains(lastreply,"Welcome to my cool FTP site");

but the following is not:

contains ( lastreply, "Welcome to my cool FTP site" );

FireScript Variables

Firecripts work with the login information provided by WS_FTP Pro. This includes at least the user IDs and passwords, the IP address and port of the FTP server, and sometimes the IP address and port of the firewall. These fields are often read from a site profile, an FTP URL, or from the command line. As described before, if some of the required information is missing, the connect sequence presents the login dialog so that the user can enter it interactively. The script executive stores this information in a set of intrinsic variables before beginning execution. In addition there are intrinsic variables that contain the results of the last command issued. These are set by the script executive after such statements are executed.

The syntax for using a variable depends on the statement or expression in which it is used. Below is a list of all the intrinsic variables:

FireScript Intrinsic Variables

Variable Meaning and Usage

FwUserId The user’s user ID on the firewall. Some firewalls require users to log in to the firewall before allowing other connections to be made through the firewall.


78

FireScripts neither need nor use user-defined variables, so there are no variable declarations. Also, since the FireScript cannot directly set the value of one of the intrinsic variables, there is no need for any assignment statements.

FwPassword The user’s password on the firewall. Required if the user must log in to the firewall.

FwAccount Account on the firewall. Required if the user must specify an account on the firewall. Practically unheard of but included in case required.

FwAddress The IP address of the firewall. Required if the user must connect to the firewall, and have the firewall in turn connect to the FTP server and act as proxy.

HostUserId The user’s ID on the FTP server. Almost always required. Specify ’anonymous’ if the user does not have a user ID on the server.

HostPassword The user’s password on the FTP server. Almost always required in conjunction with a user ID. Use your email address as the password when using ’anonymous’ for the user ID.

HostAccount The user’s account on the FTP server. To access certain information in some operating systems, FTP servers on those systems require an account to be sent after successful login with user ID and password.

HostAddress The IP address of the host. The script executive may connect directly to this address, or will send the address to a firewall that will act as a proxy.

LastFtpCode The 3-digit, numeric code of the last response received from the FTP server or firewall. For example, after a successful login, the LastFtpCode would be 230.

LastReply The text of the last response from the server. e.g. "230 user logged in"

User’s Guide

WS_FTP Pro

String Expansion

Some of the commands and functions in the FireScript language take strings as arguments. To these you may either pass a string variable or a string literal surrounded by double quotes, e.g. "This is a string." To put a double quote inside a string, preface it with the percent sign ’%’. The percent sign ’%’ is used as an escape character to embed variables and quote characters in strings.

The sequence %% is replaced by a single %. The sequence %" is replaced by ".% followed by the name of a variable is replaced by the value of the variable.

For example, the script statement below:

send ("OPEN %HostAddress")

If HostAddress is equal to "ftp.ipswitch.com" when this script is invoked, the command will be expanded to:

send ("OPEN ftp.ipswitch.com")

the expression,

contains (lastreply, "%% full")

will be expanded at runtime to:

contains(lastreply "% full")

and the statement

send ("SITE SETLOG %"f:\log files\access.log%" -clear")

the expanded string sent will be:

SITE SETLOG "f:\log files\access.log" -clear

Passing a string variable is equivalent to, but faster than passing a string literal that expands the variable.

Example:

isempty(FwPassword)

is equivalent to but faster than

isempty("%FwPassword")


80

Function Expressions

Currently the FireScript language does not allow full-blown expressions. It does include two function expressions with some boolean operators for evaluating the state of variables. They are contains and isempty. The boolean operators supported are not and and.

The contains function takes two strings and returns true if the second string is found in the first. The search is case sensitive. Both strings are expanded first.

The isempty function takes a string and returns true if there are any characters in the string. You can use it to test if a value was specified for one of the intrinsic variables.

The not boolean operator reverses the value returned by the function expression.

Example:

If the HostAccount variable contains the value ’usr987i’isempty (HostAccount) will return false butnot isempty(HostAccount) will evaluate to true.

The and boolean operator requires all specified conditions to be true.

Example, If the HostAccount variable contains a value such as ’usr987I’The last reply from the server is "230 User logged in, please send account"

then the following expression will evaluate to true:

case (200..299) and not isempty(HostAccount) and contains(lastreply, "ACCOUNT") :

FireScript Statements

The FireScript language includes several types of statements. Statements cause actions to be taken, or direct the flow of execution of the script. The following sections describe the types of statements.

User’s Guide

WS_FTP Pro

Switch Statements

The send statement and the xauth statement are called switching statements, because they imply an immediate switch statement based on the server response. The switch statement contains case statements very similar to Java and C++ case statements, except the conditions are not constants checked against a single expression.

A switching statement such as send and xauth is always immediately followed by a set of case statements between curly braces { <case statements> }. The set of case statements may be empty, in which case there is nothing between the curly braces, but the braces must be present.

Example of Switch Statement:

send ("USER %FwUserId") {}

The send statement takes a single argument, the string to be sent to the server. The string is expanded before it is sent. The maximum legal length for the expanded string is about 512 bytes, the maximum length of an FTP line. The send command then waits on a response from the server and evaluates the response against the conditions in each of the enclosed case statements.

The xauth statement takes no arguments. It examines the welcome banner for an xauth invitation supplied by WS_FTP server. If it is not connected to WS_FTP server or cannot find the invitation, xauth does nothing, andthe case statements are not evaluated. If it does find the invitation, it encodes the user ID‘ and password and sends the xauth command to the server. It then waits on the response and evaluates it against the case statements just as the send command does.

Case Statements

Case statements are enclosed in switching statements. A case statement lists a set of conditions that the server response must satisfy for the case to be activated.

The list of conditions is followed by a colon ':'.

Case stataments are processed in the order in which they are listed until the first match is found.


82

Once a match is found for the conditions in a case statement, then the nested statements are executed.

A case condition may be a list of FTP codes and code ranges, a function expression, or one of the special cases, any and timeout.

If a case includes a list of ftp codes/ranges, the list must appear first, followed by any function expressions. The list is comma separated and enclosed in parentheses. Each item in the list must either be a single 3-digit code, or a range specified by two 3-digit codes separated by a double period ’..’. The range is inclusive and it is recommended that the lower bound be specified first.

The special cases any and timeout must appear by themselves.

Examples of Case Statements

The following case condition will match if the returned ftp code is either 226 or 231.

case (226, 231) :

The following case conditions will match if the returned ftp code is either 226 or 231, or between 250 and 299 inclusive. So 250 itself will match, as well as 251, 252 etc. up to 299

case (226, 231, 250..299) :

The following case conditions will match if the returned ftp code is in the 300s and the returned string contains the text "email address".

case (300..399) and contains(lastreply, "email address") :

The following case conditions will match if the returned ftp code is 500 or greater and the returned string contains the specified error message

case (500..999) and contains(lastreply, "user %HostUserId cannot login.") :

If a case contains more than one condition they must be separated by and. The and operator specifies that all the listed conditions must be satisifed. So in the previous example, the ftpcode must be between 500 and 599 AND the lastreply most also contain the specified string. Both must be true. If either is false, the case will not match.

The not operator reverses the result of a function. We may for example want to make sure that the last response does not contain a

User’s Guide

WS_FTP Pro

certain string. For example:

case (500..599) and not contains(lastreply, "server is busy") :

There is no or operator. The same logic may be applied by using multiple case statements.

The following case condition will match if the send command timed out.

case timeout :

Case any is the catch all case, and if present should be the last case in the enclosing list. If it is followed by other case statements they will never be evaluated.

For example, the following case condition will always match.

case any:

If case statements overlap and two case statements would match the response, then the first one encountered will be executed.

Example:

case (200..299) and contains(lastreply, "please send user account") :...case (200..299) :...

If the case with the contains function appeared after the one without it, it would never get evaluated.

Continue

Unlike C and C++, execution inside a case statement does not fall through to the next case statement. Only the statements listed under the activated case are executed. Then execution continues at the next statement after the enclosing switching statement. The continue statement jumps to the statement following the enclosing switching statement. It does the same thing as a break, inside of a C/C++ switch statement, except it is not absolutely necessary.

Switching statements may not be nested. That is, neither a send statement nor an xauth statement may appear inside a case statement.


84

Jumps and Labels

A jump statement transfers execution to another part of the script. The jump destination must be defined by a label that also appears in the script. The Ipswitch example FireScripts use jumps to different code sequences from inside case statements, so the code that gets executed depends on which case was activated.

A label declaration consists of the word label, followed by the name of the label and a semicolon.

A jump statement consists of the word jump, followed by the name of the jump destination, and a semicolon.

A label may not appear inside a case statement. You can’t jump into a case statement.

Return

The return statement acts like a function in that it takes a single parameter, either true or false to indicate success or failure. It terminates script execution and returns to the caller. If it returns true, the connection is assumed to be logged in and authorized. If it returns false, the caller may either try again or abandon the connection.

Autodetect

The autodetect statement examines the last reply from the server to help determine the host type of the FTP server to which it is connected. Autodetect expects to examine the welcome banner so the statement should be placed immediately after the welcome banner is returned. Here are two example banners returned from two popular FTP servers. Autodetect would detect the first as being a Microsoft NT server, and the second as being an Ipswitch WS_FTP server.

220 tstsrvnt Microsoft FTP Service (Version 3.0).220 tstsrvws X2 WS_FTP Server 1.0.5 (1737223651)

If connection was made directly to the host FTP server and the welcome banner was already returned before the script begins execution, then autodetect should be the first statement in the script. If the connection was made to the firewall and the welcome banner from the host ftp server becomes available later in the script, the

User’s Guide

WS_FTP Pro

autodetect statement should be placed at that point. If the firewall swallows or replaces the welcome banner from the ftp host, or for some other reason, the ftp client never sees the welcome banner, then leave out the autodetect statement. WS_FTP Pro will try to determine the host type after the script executes.

Autodetect does nothing if the host type in the site profile is set to anything other than ‘Auto Detect.’ The autodetect statement has no return value and does not change the flow of the script.

SSL Statements

The tryssl and gossl commands attempt to open a secure channel with the server via SSL. The difference between them is that if gossl fails, the script will terminate and return false, while if tryssl fails, the script will continue. The commands can appear more than once in the program. If a secure connection was not requested, or has already been established, the commands will do nothing. If the commands fail to go secure, they will display a message box to the user, asking the user if she wishes to continue in the clear, try again for SSL later in the sequence, or abandon the connection. If the user chooses to continue in the clear, future calls to tryssl or gossl will do nothing.

When the script completes, the script executive checks the SSL status of the connection to make sure that a request for a secure connection was honored. In the site profile, if the user selected Use SSL, then the script executive will issue a warning to the user if the connection is not secure. At this point the user may abandon the connection. This warning is issued if a secure connection was attempted and the user chose to continue in the clear.

The placement of the attempts to open an SSL channel can be very important, depending on the type of firewall through which the script is connecting.


86

FireScript Key Words

Below is a complete list of all the keywords used and understood by the language. You may not use these words as label names.

FireScript reserved words

The following words are reserved for future versions of the language and the parser. You should not use these words to name your labels

gossl tryssl autodetect

send xauth case

continue and not

any timeout return

jump label true

false

switch if for

next while loop

break function int

bool string var

password or

User’s Guide

WS_FTP Pro

FireScript statements

FireScript intrinsic functions

FireScript intrinsic variables

gossl tryssl autodetect

send xauth jump

return continue

contains isempty

FwUserId FwPassword FwAccount

FwAddress HostUserId HostPassword

HostAccount HostAddress LastFtpCode

LastReply


88
User’s Guide
WS_FTP Pro

Appendix B: Textual Error Messages

This Appendix lists common textual error messages. Each error message is followed by an explanation of the error, and some possible workarounds or solutions, if any exist.

Some of these error messages are returned by the FTP protocol and will appear in the WS_FTP log, preceded by a three-digit reply code.

Others of these textual error messages may appear in dialog boxes generated by WS_FTP Pro or your operating system.

For more information, see the KnowledgeBase on the Ipswitch web site, www.ipswitch.com.

“Blocking call canceled”

There are several possible causes for this problem. Try these tests in the order shown:

1 Disconnect from the FTP site if you are currently connected to it. Then turn on passive mode. After you have done this, try reconnecting to the site.

2 If you still receive this error message, set the network timeout for the site to 120 in the Classic interface:

• If you are connected to a site, select Disconnect from the File menu.

• Select Connect from the File menu to view the “Connection” dialog box.

• In the Configured Sites list, select the site.

• Click the Advanced Properties button.

• Click the Advanced tab.

• Enter 120 for the Network Timeout.

3 If you still receive this error after making the above changes, try the command line FTP (not the WS_FTP Command Line) and see if you can connect and how long it takes. Once you know how long it takes to connect, enter this time into the Network Timeout setting on the Advanced tab of the site properties as described above.

4 If you still cannot connect please contact the FTP server administrator for assistance.

Textual Error Messages 89WS_FTP Pro

90

“Cannot create file”

This error usually means one of two things:

• The file already exists and is in use; therefore, you cannot overwrite the file.

• You do not have sufficient permission to create the file in the current directory.

“Can’t get ‘xxx’ host entry”

This error means that the host name you have entered for the FTP site cannot be resolved to an IP address. (Host names are resolved to IP addresses by a Domain Name Server.)

Check the Host Name box on the Host Info tab of site properties. It must contain a valid host name or a valid IP address. Enter the host name in this format:

ftp.ipswitch.com

Do not use:

http://ftp.ipswitch.com/Ipswitch/Product_Downloads

ftp://ftp.ipswitch.com

“Can’t set guest privileges”

If you have a personal account on this FTP site, use the corresponding user ID and password assigned to you by the FTP site administrator (instead of an “Anonymous” login). Make sure the Anonymous box is turned off on the Host Info tab, and enter the appropriate user ID and password.

“Connection refused”

Either the host is not running an FTP server program, or else the FTP site is accepting connections only from certain clients.

“Directory identifier unavailable”

You get this error message if the connection to the current FTP site has timed out and you try to refresh the display.

User’s Guide

WS_FTP Pro

“Disk quota exceeded”

The disk quota is not determined by WS_FTP Pro; it exists on the FTP site. You can either delete some files on the site to make room for your upload (if you have permission) or get more space from the site administrator.

“Failed data channel”

Disconnect from the FTP site if you are currently connected to it. Then turn on passive mode.

“File too large to download”

This message is coming from the FTP site that you are connected to. This site has a limit on how large a file you can download.

“Illegal port command”


“Invalid page fault”

This error is usually caused by an incorrect system date or system time, either on your PC or on the FTP site you are connecting to.

“Logon failure; Quitting.”

The FTP site is not recognizing or accepting your user ID and/or password. Contact the FTP site administrator to verify that you are using the correct User ID and password.

“MDTM”

The current FTP site does not support Month-Day-Time-Marking; this means that after the file was uploaded, WS_FTP attempted to preserve the date and time, but the FTP site does not support this feature. However, files transferred correctly. Note that this is not a fatal error, even though it displays in red.

Textual Error Messages 91WS_FTP Pro

92

“Port command failed”


“User access denied”

The error “530 user access denied” indicates that you are not properly logged on to the server. Make sure the information on the Host Info tab of site properties is correct. Common problems are spaces, case sensitive entries, or incorrect user name or password. If you are unsure whether or not you are using the correct user name and password, contact the FTP site administrator.

Most FTP sites support anonymous logins where you do not have to have an actual account on the FTP site in order to download files; the user ID is the word Anonymous and the password is your e-mail address. To test this, try connecting to the Ipswitch FTP site (ftp.ipswitch.com) using the user ID “Anonymous.”

If you do have to have an actual account on the FTP server, for example, a server where you place your web pages, then you will need to obtain a user ID and password from the server administrator and enter them in the host information tab.

User’s Guide

WS_FTP Pro

Index

Numerics“530 user access denied” 92

Aaccounts on FTP sites 4anonymous FTP 4ASCII files 19attributes for UNIX files 24autoexec.bat 63automating file transfers 68

Bbatch files 67bitmaps 19“Blocking call canceled” error

89

C“Can’t get ‘xxx’ host entry”

error 90“Can’t set guest privileges”

error 90“Cannot create file” error 90cgi files 19chmod (command) 24Classic interface (defined) 5client-server 1command line 63command prompt 52, 63“Connection refused” error 90

Ddata connection 60dates and times

criteria for finding files and folders 48

“Directory identifier

unavailable” error 90“Disk quota exceeded” error 91download (defined) 1

EEditor/Debugger window 52e-mail address 4error messages 70, 89exe files 19executable files 19Explorer Interface 27Explorer interface (defined) 5

F“failed data channel” error 91file name as criteria for finding

files 47file names with spaces 66file size as criteria for finding

files 49“File too large to download”

error 91files

ASCII 19compressed, transferring

19executables, transferring

19htm 19html 19postscript 19

Find Utility 45finding files and folders 45FireScript 73firewall types 60firewalls 59

router-based 60folders

with subfolders 69FTP (File Transfer Protocol)

client (defined) 1server (defined) 1

FTP (File Transfer Protocol) (defined) 1

FTP sitesaccounts on 4viewing contents of 5

FTP URL (defined) 6

Ggateways 59group permissions 25

Hhierarchical folders. See

foldershost name of firewall 60htm files 19html files 19HTTP 1

I“Illegal port command” error

91installing WS_FTP Pro 3interfaces of WS_FTP Pro 4“Invalid page fault” 91IP address of firewall 60Ipswitch, Inc.

getting software updates 8giving feedback 8web site 8

Jjpg files 19

Llocal area network 1Local System (defined) 5logging on 3, 4“Logon failure. Quitting.” 91

Index 93WS_FTP Pro

94

MMDTM error 91messages

suppressing with the command line 70

messages, error 89Microsoft Internet Explorer 7mirroring files and folders 41modem 1modes for UNIX files 24Month-Day-Time-Marking 91MS-DOS prompt 63

Nname of file as criteria for

finding files 47names (file) with spaces 66Netscape Navigator 7New Features in version 7.0 2

Oowner permissions 25

Ppassive transfers 60patches 8permissions for UNIX files 24“Port command failed” 92port of firewall 61postscript files 19pre-scheduled transfers 68prompts 41Proxy OPEN (firewall) 60public folder 4

Qqueuing transfer tasks 55, 68Queuing Utility 55

RRemote System (defined) 5router-based firewalls 60

Sscheduling transfers 57, 68scripting 51

example 53Scripting Utility 51scripts, writing and debugging

52server

See also FTP siteserver (defined) 1SITE hostname (firewall) 60site. See FTP sitessize of file as criteria for

finding file 49software patches 8spaces in file names

transferring with command line 66

SSLgenerating a certificate 36selecting a certificate 37trusted authorities 38

adding a certificate 39exporting a certificate 39removing a certificate 39

SSL (definition) 33certificate 34certificate signing request

34client 34private key 34public key 34session key 34

startuptransfer mode 21

“sticky bit” 25suppressing error messages

using the command line 70

Synchronize Utility 41synchronizing files and folders

41system requirements 2

Ttext files 19time. See dates and timesTransfer Manager 29transfer modes

defined 21startup 21

transferring files See also downloading,

uploadingASCII 19binary 19compressed 19HTML 19images 19jpg 19photographs 19pictures 19postscript 19scheduling 68text 19with spaces, using

command line 66zipped 19

Transparent (firewall) 60

Uuninstalling WS_FTP Pro 9UNIX 24UNIX FTP sites 24upgrades 8upload (defined) 1URL (defined) 6“User access denied” 92USER fireID@remoteHost

(firewall) 60user interfaces of WS_FTP Pro

WS_FTP ProIndex

4USER remoteID @remoteHost

fireID (firewall) 60USER remoteID@fireID

@remoteHost (firewall) 60USER with no logon (firewall)

60Utility

Find 45Queuing 55Scripting 51Synchronize 41

Vviewing

files and folders 5

WWeb browser integration 6wildcard characters for finding

files and folders 47wildcards

in command line 69World Wide Web 1WS_FTP Find Utility 45WS_FTP Pro Development Kit

8WS_FTP Queuing Utility 55WS_FTP Scripting Utility 51WS_FTP Server 7WS_FTP Synchronize Utility

41

Zzip files

transferring 19

Index 95WS_FTP Pro

96
WS_FTP Pro
Index

WS FTP Proftp.ipswitch.com/ipswitch/manuals/wsftp70.pdf · Introduction 1 WS_FTP Pro Chapter 1:...

Documents

Transcript of WS FTP Proftp.ipswitch.com/ipswitch/manuals/wsftp70.pdf · Introduction 1 WS_FTP Pro Chapter 1:...