WS_FTP Pro. User s Guide. Software Version 7.0. Ipswitch, Inc.

Transcription

1 User s Guide Software Version 7.0 Ipswitch, Inc.

2 Ipswitch, Inc. Phone: Hartwell Ave Fax: Lexington, MA Web: 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 information 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 companies. 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 December 1996 July 1997 February 1998 October 1998 May 2000 June 2001 First Edition Second Edition Third Edition Fourth Edition Fifth Edition Sixth Edition Seventh Edition

3 Table of Contents Chapter 1: Introduction Why FTP? How FTP Works New in WS_FTP Version System Requirements Installing Logging Onto an FTP Site Interfaces for Windows 95, 98, 2000, ME and NT The Classic Interface of The Explorer Interface of Browser Integration Other Ipswitch ducts WS_FTP Server Development Kit Getting Updates and Giving Feedback Uninstalling Accessibility Chapter 2: Getting Started Making your First Connection Connection Dialog Toolbar and Buttons Connection Dialog Boxes and Options Transferring a file Toolbar Anonymous Connections Using the Help System Chapter 3: Transferring Files Ways to Transfer Files Using the Transfer Arrows Drag and Drop Copy and Paste Batch Mode Using the Transfer Manager Transfer Modes Passive Transfers Chapter 4: Managing Files and Folders Viewing and Navigating Working with Files and Folders Click and Drag for Organization Contents iii

4 Changing the Permissions for UNIX Files Background Information Chapter 5: Explorer Interface Overview Using the Explorer Interface Configuring a Site Making a Connection Transferring Files Chapter 6: WS_FTP Transfer Manager What is the Transfer Manager? Transfer Manager Dialogs Transfers Manager Dialog Request Properties Log Window Chapter 7: SSL Utility What is SSL? How to make an SSL connection Client Certificate Verification Generating a Certificate Selecting a Certificate Trusted Authorities Adding a Certificate Exporting a Certificate Removing a Certificate Non-Trusted Certificate Chapter 8: Synchronizing Files and Folders A Word of Caution Using the Synchronize Utility Example Exclusions Using the Synchronize Utility from the Command Line Chapter 9: The Find Utility Using the Find Utility Using the Search Results Examples Finding a File When You Are Not Sure of Its Name Finding a File Modified During a Specific Time Period Finding a File in a Particular Folder Finding a File Smaller Than a Certain Size iv Contents

5 Chapter 10: Scripting Using Scripting Writing and Debugging Scripts Executing Scripts Executing a Script from the Command Prompt Running a Script from the Scripting Utility Example Chapter 11: Scheduler Using the Scheduler Examples Adding a Script to the Scheduler Updating a Web Site on a Nightly Basis Chapter 12: Using Firewalls Multiple Firewalls Firewall Types Configuring a Firewall Using a Configured Firewall Chapter 13: Using the Command Line Basic Command Line Syntax Site Information Transfer Source Transfer Destination File Transfer Options Uploading Files Downloading Files Transferring multiple files from the same location Converting File Names to Lower Case File Transfer Modes Transferring Files with Spaces in the File Names Enclosing the Command Line in Quotes Using the MS-DOS Name Using a Batch File Multiple Folders or Commands Pre-scheduled Transfers ( Automated Transfers ) Transferring a Folder Containing Subfolders Using a Site Profile with a Host Name Extras Summary Appendix A: FireScript Editor What is a FireScript? Contents v

6 FireScript Components The fwsc Section The Comment Section The Script Section The Connection Sequence The FireScript Language FireScript Variables String Expansion Function Expressions FireScript Statements Switch Statements Case Statements Examples of Case Statements Continue Jumps and Labels Return Autodetect SSL Statements FireScript Key Words FireScript reserved words FireScript statements FireScript intrinsic functions FireScript intrinsic variables Appendix B: Textual Error Messages Blocking call canceled Cannot create file Can t get xxx host entry Can t set guest privileges Connection refused Directory identifier unavailable Disk quota exceeded Failed data channel File too large to download Illegal port command Invalid page fault Logon failure; Quitting MDTM Port command failed User access denied Index vi Contents

7 Chapter 1: Introduction This chapter offers an introduction to, 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? 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. 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, will speed up the time it takes to copy such files to your PC. For more information, see Browser Integration on page 6. 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. 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), 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. Introduction 1

8 Your PC FTP site A FTP site B 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 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) 2 User s Guide

9 Installing If you are upgrading from a previous version of, 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. The installation of is the same for new users, those who are upgrading from a previous version of, and those who are replacing an evaluation version with a purchased version. To install from a downloaded file: 1 Double-click the file you downloaded. (ftpproec.exe) 2 Follow the directions on your screen. To install from a CD-ROM: 1 If you already have a previous version of on your system, make sure you are not running the application (either Classic or Explorer). 2 Insert the 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. Introduction 3

10 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 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. 4 User s Guide

11 The Classic Interface of 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 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 current folder on your PC is shown under the words Local System. The current folder on the FTP site is shown under the words Remote System. This list box shows the files and folders in the current local folder. This list box shows the files and folders in the current folder on the FTP site. The buttons to the right of each list box provide file and folder operations for that list box. The Explorer Interface of The second interface of 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. Introduction 5

12 The Explorer interface looks similar to one of the following: The appearance of the Explorer window is determined by your View menu options. Explorer interface Files and folders in the current folder Browser Integration Browser Integration is NOT compatible with Netscape 6. You can set up Classic so that it automatically handles FTP URLs when you click them in your browser or in an 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 the FTP URL for the FTP site of Patches is ftp://ftp.ipswitch.com.) handles FTP URLs as follows: If the URL is the name of an FTP server, such as ftp.ipswitch.com, handles the URL by starting the Classic interface of and connecting to the site. 6 User s Guide

13 If the URL includes the path and name of a file, such as ftp.ipswitch.com/french/ftp605f.txt, 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, 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 to handle FTP URLs, select the first check box. 3 If you use Microsoft Internet Explorer and want 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, select Ask before using WS_FTP. Other Ipswitch ducts WS_FTP Server and the Development Kit can be purchased separately at 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. Introduction 7

14 Development Kit You can develop custom applications using the 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 To access upgrades on the Ipswitch FTP site: 1 In the window, click the Connect button. 2 In the Connection dialog box, open the Ipswitch folder and select the site named Patches. 3 Click Connect. connects to the 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 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 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: 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. 8 User s Guide

15 4 Save the patch file in a folder other than your folder or your Windows Temp folder. 5 Run the patch file to update the software. We welcome your feedback on. 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 Explorer icon from your desktop. To uninstall : 1 Click the Start button and select Programs -> Uninstall. 2 When prompted, choose Uninstall. 3 Follow the on screen instructions to uninstall. Accessibility 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 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. Introduction 9

16 10 User s Guide

17 Chapter 2: Getting Started This chapter describes how to get started using. The two main windows are mapped out for you, and in the sidebar are step-bystep instructions on the basic functions of. How to... 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 Classic Interface attempts to make the connection. Making your First Connection The first time is run, the Classic Interface opens with the Connection dialog box displayed. Some sites are set up for you when you install. 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. Getting Started 11

18 Connection Dialog Toolbar and Buttons 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 online help system. 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. 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. 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 12 User s Guide

19 and an IP address of In, 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. Getting Started 13

20 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:\) Comment. Enter any comment you would like to make about the site. 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. Transferring a file After making your connection, WS_FTP closes the Connection dialog, leaving the window. The image below shows how the window looks once you have connected to a site. 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. 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. 14 User s Guide

21 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: Upload Arrow Download Arrow Toolbar 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 gram 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 online help system. Getting Started 15

22 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 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. It should be the first place you look if you have any question using the product. Use the Index tab to look up keywords, and use the Search tab to search for words in the body of the topics. Individual topics are organized into books that relate to a specific function. Some books have other books listed inside. 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. 16 User s Guide

23 Chapter 3: Transferring Files Transferring 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 allows you several ways to transfer a file. Using the Transfer Arrows Look for more information in the Transferring Files section of the Online help. 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. Upload Arrow Download Arrow 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. 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. 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. Transferring Files 17

24 Confirming Overwrites Most sites allow you to overwrite or replace a file without giving you any kind of visual warning. Through, 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. When you release the mouse button, 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. then attempts to make the transfer. Batch Mode If you want to transfer multiple files from different sites, you can put in Batch Mode. While in batch mode, 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 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 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. Transfer Mode 18 User s Guide

25 These modes are called ASCII, Binary, or Auto. The following chart shows the icon that should be chosen for the described type of file. Ascii Mode Binary Mode Auto 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. 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. If you turn on Auto mode, 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. 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 ; 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 Transferring Files 19

26 20 User s Guide

27 Chapter 4: Managing Files and Folders This chapter deals with using 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 Look for more information in the Viewing and Navigating section of the Online help. WS_FTP provides many tools and techniques for viewing and navigating files and folders. This section points out various structures on the window that allow you to view files and folders, and to navigate both local and remote systems. Display Icons Address Bar Local System Remote System Up one Level Local Directory Mapped Drives Remote Directory Change Directory Button Refresh Buttons 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. Managing Files and Folders 21

28 The left side of the 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 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 Look for more information in the Working with files and folders section of the Online help. gives you a variety of features that make it quick and easy to organize, manipulate, and delete files and folders. 22 User s Guide

29 The graphic below points out key features used during these tasks. Connection buttons (Connection Bars) Folder Files 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, 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 Managing Files and Folders 23

30 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 The selected options do not necessarily indicate the current permissions for the selected file or folder. 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). If you attempt to change permissions, check the message area or the log to see if you were successful. 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: The first digit is interpreted as follows: 24 User s Guide

31 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 log, in the message area, and by some system administrators and ISPs. The table below shows how 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 tenposition value in the first column of a directory list for a UNIX site. Selected options in 2nd, 3rd, or 4th digit of 4-digit number Permissions in directory list none Execute 1 --x Write 2 -w- Write, Execute 3 -wx Read 4 r-- Read, Execute 5 r-x Read, Write 6 rw- Read, Write, Execute 7 rwx 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 Managing Files and Folders 25

32 directory list. This expression is comprised of four parts: d rwx r-x --x First position indicates whether item is a file (-,s,s, or t) or directory (d) Positions 2-4 indicate Owner permissions: read, write, execute. Positions 5-7 indicate Group permissions: read and execute. Positions 8-10 indicate Other permissions: execute only. 26 User s Guide

33 Chapter 5: Explorer Interface Unlike previous versions of, 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 Look for more detailed information in the Online Help. Most sections are applicable to the Explorer Interface. 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. Site folders. The + means that there are configured sites in the folder. The site icon changes when connected. This pane displays the remote directory when connected to an FTP site. Site Icon The status bar displays the current state of the interface. Explorer Interface 27

34 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 dragand-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. 28 User s Guide

35 Chapter 6: WS_FTP Transfer Manager This chapter includes the following topics: What is the Transfer Manager Transfer Manager Dialogs What is the Transfer Manager? The Transfer Manager is used to view the progress of transfers, to schedule the transfer of multiple files, and to view logs for individual transfers. How to... 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 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. You can remove completed items individually, or you can select Remove Completed Requests from Transfer Manager on the General tab of the Options dialog. 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. WS_FTP Transfer Manager 29

36 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. Request Properties You can double click any item on the Transfer Manager dialog to view the Request Properties dialog for that item. How to... Remove an item To remove an item from the Transfer Manager: 1 Select the file you want removed. 2 From the Transfers menu, select Delete. How to... Schedule a transfer To 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. 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. 30 User s Guide

37 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. WS_FTP Transfer Manager 31

38 32 User s Guide

39 Chapter 7: SSL Utility This chapter describes what SSL is and how you can configure 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. SSL Utility 33

40 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 client. If the connection is accepted, or if the server is not set up to receive certificates, it decodes the session key from the client 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. 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. 34 User s Guide

41 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, 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 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. SSL Utility 35

42 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. 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. 36 User s Guide

43 Country. The country you are in. This must be a valid two letter country code. (Ex. US) . 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, you should send the certificate signing request (by ) 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. SSL Utility 37

44 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. 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. 38 User s Guide

45 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. SSL Utility 39

46 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 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. 40 User s Guide

47 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 /00:00 ( /00:00) # receiving filec.ext /00:00 ( /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 -> -> Synchronize Utility. The Synchronize Utility 41

48 Example The following is an example of how you might use the WS_FTP Synchronize 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. 42 User s Guide

49 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\ The Synchronize Utility 43

50 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 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 User s Guide

51 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 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. The Find Utility 45

52 For example, if you search the Ipswitch FTP site for a file named filelist.txt, the following results are displayed. The search found this file. 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. 46 User s Guide

53 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. Search text The results of the search are shown below. The Find Utility 47

54 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, 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. 48 User s Guide

55 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. The Find Utility 49

56 50 User s Guide

57 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. The Scripting Utility 51

58 Click the Windows Start button and select Programs -> -> 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 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. 52 User s Guide

59 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. The Scripting Utility 53

60 54 User s Guide

61 Chapter 11: Scheduler The 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 Classic interface. Click the Windows Start button and select Programs -> -> 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 Classic or Explorer Interface to the Scheduler window to create an upload task. Create a task from within, Find Utility by right-clicking the file and selecting Send to Scheduler. Create a task from the Synchronize Utility or the Transfer Manager. Scheduler 55

62 The 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. 56 User s Guide

63 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 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.. 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 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.) 5 If you are on an NT workstation, you must enter your NT user login and password in the boxes provided. Scheduler 57

64 6 Select the frequency of the recurring transfer in the Schedule Frequency area. 7 Click OK to add this task to the scheduler. Scheduling a single item (this can be a folder with multiple items inside) 1 Select the file in and select Send to Scheduler from the right-mouse menu. The 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 If you are on an NT workstation, you must enter your NT user login and password in the boxes provided. 5 Select the frequency of the recurring transfer in the Schedule Frequency area. 6 Click OK to add this task to the scheduler. 58 User s Guide

65 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. 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). Using Firewalls 59

66 Firewall Types The following table lists all conventional firewall types and the information about each that you will need to procure and enter into. Type of Firewall Proxy OPEN SITE hostname Transparent USER after logon USER Information you need to enter in Host Name (or Address) Host Name (or Address), User Name (ID) User Name (ID), Password Host Name (or Address), User Name (ID), Password Host Name (or Address), User Name (ID), Password Host Name (or Address), User Name (ID), Password USER fireid USER with no logon Host Name (or Address), User Name (ID), Password Host Name (or Address) Configuring a Firewall For some router-based firewalls, you will want to use passive mode, in which the data connections are established by the FTP client () rather than by the FTP site. 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. 60 User s Guide

67 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. 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. Using Firewalls 61

68 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. 62 User s Guide

69 Chapter 13: Using the Command Line So you can use the command line from any location on your hard disk, we recommend that you place the 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 folder to the path variable in the System Environment. Otherwise, change to your folder when you use the commands. You can use the command line from the MS-DOS prompt to run the 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 wsftppro -s local:c:\tartan.bmp -d robert!border:/pub/tartan.bmp If you use a configured site from the command line, 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 Using the Command Line 63

70 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 wsftppro -s local:c:\tartan.bmp -d robert!border:/pub/tartan.bmp 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 :/pub/tartan.bmp -d local:c:\ Transfer Destination wsftppro -s local:c:\tartan.bmp -d robert!border:/pub/tartan.bmp 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: 64 User s Guide

71 wsftppro -s local:c:\tartan.bmp -d pub/tartan.bmp or wsftppro -s local:c:\tartan.bmp -u username -w password -d :/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 Using the Command Line 65

72 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 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 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.) 66 User s Guide

73 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 You cannot run 2 batch files at the same time. 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 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, 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 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. Using the Command Line 67

74 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 from displaying a message box if and when an error occurs. This is particularly useful for avoiding a situation in which 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.) 68 User s Guide

75 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 Using the Command Line 69

76 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, 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 display a dialog box that prompts you for the command line, type: wsftppro -ask To launch the Classic interface and default to the site configuration for the border site: wsftppro -p robert!border To prevent 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) -ascii -binary When to use Use -ascii when transferring text files. Use -binary when transferring nontext 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. Important restrictions 70 User s Guide

77 -lower Use -lower to have convert file names to lower case letters when you transfer from your PC to an FTP site. -m text_file Use -m to do transfers that involve multiple source locations, multiple destinations, or multiple commands. text_file is the name of the file that contains the commands. -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. -quiet Use -quiet to prevent 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 password to use to connect to the ftp site. If you use the -lower argument, it must be at the very end of the command. The -p argument must precede all arguments except -i. Using the Command Line 71

78 72 User s Guide

79 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. FireScripts can perform the same functions that 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. FireScript Editor 73

80 Below is an example FireScript demonstrating this layout. [fwsc] author=ipswitch connectto=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 ( ) : 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. 74 User s Guide

81 The parser recognizes and stores values for the following parameters: fwsc Parameters Parameter author version verdate required preask connectto Meaning and Values Informational only. Author of the FireScript. Informational only. Version number of the script file. Informational only. Date on which this version was updated. 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. A comma delimited list of fields that are not required but which, if not present, will cause the login dialog to be displayed. firewall or host. This parameter tells which IP address to use when establishing the connection. 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. FireScript Editor 75

82 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 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 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 is using a FireScript or using one of its internal firewall types. Before executing the script, 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, 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, defaults to the IP address of the firewall, if present. After the connection is established successfully, and a valid socket is opened, 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. 76 User s Guide

83 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. 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 FwUserId Meaning and Usage 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. FireScript Editor 77

84 FwPassword FwAccount FwAddress HostUserId HostPassword HostAccount HostAddress LastFtpCode LastReply The user s password on the firewall. Required if the user must log in to the firewall. Account on the firewall. Required if the user must specify an account on the firewall. Practically unheard of but included in case required. 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. 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. The user s password on the FTP server. Almost always required in conjunction with a user ID. Use your address as the password when using anonymous for the user ID. 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. 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. 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. The text of the last response from the server. e.g. "230 user logged in" 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. 78 User s Guide

85 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") FireScript Editor 79

86 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 but not 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 ( ) 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. 80 User s Guide

87 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. FireScript Editor 81

88 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, ) : The following case conditions will match if the returned ftp code is in the 300s and the returned string contains the text " address". case ( ) and contains(lastreply, " 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 ( ) 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 82 User s Guide

89 certain string. For example: case ( ) 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 ( ) and contains(lastreply, "please send user account") :... case ( ) :... 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. FireScript Editor 83

90 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 ( ) 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 84 User s Guide

91 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. 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. FireScript Editor 85

92 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. gossl tryssl autodetect send xauth case continue and not any timeout return jump label true false 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 switch if for next while loop break function int bool string var password or 86 User s Guide

93 FireScript statements gossl tryssl autodetect send xauth jump return continue FireScript intrinsic functions contains isempty FireScript intrinsic variables FwUserId FwPassword FwAccount FwAddress HostUserId HostPassword HostAccount HostAddress LastFtpCode LastReply FireScript Editor 87

94 88 User s Guide

95 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 or your operating system. For more information, see the KnowledgeBase on the Ipswitch web site, 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 89

96 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: 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. 90 User s Guide

97 Disk quota exceeded The disk quota is not determined by ; 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 Disconnect from the FTP site if you are currently connected to it. Then turn on passive mode. 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 91

98 Port command failed Disconnect from the FTP site if you are currently connected to it. Then turn on passive mode. 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 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. 92 User s Guide

99 Index Numerics 530 user access denied 92 A accounts on FTP sites 4 anonymous FTP 4 ASCII files 19 attributes for UNIX files 24 autoexec.bat 63 automating file transfers 68 B batch files 67 bitmaps 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 90 cgi files 19 chmod (command) 24 Classic interface (defined) 5 client-server 1 command line 63 command prompt 52, 63 Connection refused error 90 D data connection 60 dates and times criteria for finding files and folders 48 Directory identifier unavailable error 90 Disk quota exceeded error 91 download (defined) 1 E Editor/Debugger window 52 address 4 error messages 70, 89 exe files 19 executable files 19 Explorer Interface 27 Explorer interface (defined) 5 F failed data channel error 91 file name as criteria for finding files 47 file names with spaces 66 file size as criteria for finding files 49 File too large to download error 91 files ASCII 19 compressed, transferring 19 executables, transferring 19 htm 19 html 19 postscript 19 Find Utility 45 finding files and folders 45 FireScript 73 firewall types 60 firewalls 59 router-based 60 folders with subfolders 69 FTP (File Transfer Protocol) client (defined) 1 server (defined) 1 FTP (File Transfer Protocol) (defined) 1 FTP sites accounts on 4 viewing contents of 5 FTP URL (defined) 6 G gateways 59 group permissions 25 H hierarchical folders. See folders host name of firewall 60 htm files 19 html files 19 HTTP 1 I Illegal port command error 91 installing 3 interfaces of 4 Invalid page fault 91 IP address of firewall 60 Ipswitch, Inc. getting software updates 8 giving feedback 8 web site 8 J jpg files 19 L local area network 1 Local System (defined) 5 logging on 3, 4 Logon failure. Quitting. 91 Index 93

100 M MDTM error 91 messages suppressing with the command line 70 messages, error 89 Microsoft Internet Explorer 7 mirroring files and folders 41 modem 1 modes for UNIX files 24 Month-Day-Time-Marking 91 MS-DOS prompt 63 N name of file as criteria for finding files 47 names (file) with spaces 66 Netscape Navigator 7 New Features in version O owner permissions 25 P passive transfers 60 patches 8 permissions for UNIX files 24 Port command failed 92 port of firewall 61 postscript files 19 pre-scheduled transfers 68 prompts 41 Proxy OPEN (firewall) 60 public folder 4 Q queuing transfer tasks 55, 68 Queuing Utility 55 R Remote System (defined) 5 router-based firewalls 60 S scheduling transfers 57, 68 scripting 51 example 53 Scripting Utility 51 scripts, writing and debugging 52 server See also FTP site server (defined) 1 SITE hostname (firewall) 60 site. See FTP sites size of file as criteria for finding file 49 software patches 8 spaces in file names transferring with command line 66 SSL generating a certificate 36 selecting a certificate 37 trusted authorities 38 adding a certificate 39 exporting a certificate 39 removing a certificate 39 SSL (definition) 33 certificate 34 certificate signing request 34 client 34 private key 34 public key 34 session key 34 startup transfer mode 21 sticky bit 25 suppressing error messages using the command line 70 Synchronize Utility 41 synchronizing files and folders 41 system requirements 2 T text files 19 time. See dates and times Transfer Manager 29 transfer modes defined 21 startup 21 transferring files See also downloading, uploading ASCII 19 binary 19 compressed 19 HTML 19 images 19 jpg 19 photographs 19 pictures 19 postscript 19 scheduling 68 text 19 with spaces, using command line 66 zipped 19 Transparent (firewall) 60 U uninstalling 9 UNIX 24 UNIX FTP sites 24 upgrades 8 upload (defined) 1 URL (defined) 6 User access denied 92 USER fireid@remotehost (firewall) 60 user interfaces of 94 Index

101 4 USER fireid (firewall) 60 (firewall) 60 USER with no logon (firewall) 60 Utility Find 45 Queuing 55 Scripting 51 Synchronize 41 V viewing files and folders 5 W Web browser integration 6 wildcard characters for finding files and folders 47 wildcards in command line 69 World Wide Web 1 WS_FTP Find Utility 45 Development Kit 8 WS_FTP Queuing Utility 55 WS_FTP Scripting Utility 51 WS_FTP Server 7 WS_FTP Synchronize Utility 41 Z zip files transferring 19 Index 95

102 96 Index