Mercurial > gftp.yaz
diff docs/USERS-GUIDE @ 1:8b1883341c6f
Initial revision
| author | masneyb |
|---|---|
| date | Mon, 05 Aug 2002 19:46:57 +0000 |
| parents | |
| children |
line wrap: on
line diff
--- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/docs/USERS-GUIDE Mon Aug 05 19:46:57 2002 +0000 @@ -0,0 +1,1354 @@ + + + gFTP Users Guide + + +version 2.0.13 (06/10/2002) +Copyright (C) 1998-2002 Brian Masney <masneyb@gftp.org> + + + gFTP is a multiprotocol file transfer program for both X Window and the +console. Some of the gFTP features are: + + * Downloading files + * Uploading files + * Transfering files between 2 remote servers + * Downloading multiple files in one run + * Downloading entire directories and subdirectories + * Simultaneous downloads using multithreading + * Supports resuming interrupted file transfers + * Bookmarks menu to allow you to quickly connect to remote sites + * FTP and HTTP proxy host support + * Supports the FTP, FXP, HTTP and SSH protocols + * Supports both passive and non-passive file transfers + * Supports UNIX, EPLF, Novell, MacOS, and NT (DOS) style directory listings + * Fully Internationalized. gFTP is currently available in Bulgarian (bg), + Chinese (zh_TW.Big5, zh_CN.GB2312), Czech (cs), Danish (da), Dutch (nl), + Finnish (fi), French (fr), German (de), Italian (it), Korean (ko), + Japanese (ja), Norwegian (no), Polish (pl), Portuguese (pt_BR, br), + Russian (ru), Spanish (es), Swedish (sv) and Turkish (tr) + + + gFTP is distributed under the terms of the GNU General Public License. You +can read the GPL by clicking on Help->About->License Agreement. + + This document is a tutorial on how to use gFTP and describes some of its +functionality. I welcome any changes or additions to this document to make it +better, and easier to read. + + CONTENTS + +1. Connecting to a remote site + 1.1. Connecting using the Open URL button + 1.2. Connecting using bookmarks + 1.3. Connecting using the toolbar + 1.4. Connecting using command line parameters +2. Downloading files + 2.1. Traversing remote directory trees + 2.2. Downloading a single file + 2.3. Downloading multiple files + 2.4. Downloading from multiple sites + 2.5. Simultaneous downloads from multiple sites + 2.6. Differences between downloading in ASCII and BINARY mode +3. Uploading files + 3.1. Selecting the remote directory + 3.2. Working with the remote file tree + 3.3. Uploading a single file + 3.4. Uploading multiple files + 3.5. Passive and non passive file transfers +4. Transfering files between remote sites (FXP) + 4.1. Connecting to the receiving site + 4.2. Selecting the receiving directory + 4.3. Working with the receiving file tree + 4.4. Connecting to the sending site + 4.5. Traversing the sending site directory tree + 4.6. Selecting files from the sending site +5. Resuming transfers + 5.1. Manual resumes + 5.2. Automatic resumes +6. FTP password and user id + 6.1. Anonymous FTP + 6.2. Secure FTP password and user id + 6.3. FTP security concerns +7. Local directory + 7.1. Specifying the local directory + 7.2. Working in the local directory + 7.3. Formating the local directory window +8. Remote directory + 8.1. Specifying the remote directory + 8.2. Formating the remote directory window +9. Transfer window + 9.1. Queue + 9.2. Progress + 9.3. Formating the transfer window +10. Log and log window + 10.1. Log commands + 10.2. Formating the log window +11. Bookmarks + 11.1. Using a bookmark entry + 11.2. Adding a bookmark + 11.3. Editing bookmarks + 11.4. Bookmark passwords + 11.5. Bookmark security concerns +12. FTP protocol + 12.1 Invoking FTP +13. HTTP protocol + 13.1. Invoking HTTP +14. SSH protocol + 14.1. Configuring SSH + 14.2. Invoking SSH + 14.3. SSH and SSH2 + 14.4 Invoking SSH +15. Miscellaneous commands + 15.1. Window + 15.2. SITE commands + 15.3. Bidirectional transfers + 15.4. Clear cache + 15.5. Compare Windows + 15.6. Disconnect +16. Using gftp-text (the command line version of gFTP) + 16.1. Downloading entire directories and subdirectories + 16.2. Documentation for gftp-text +17. Using gftp-gtk (the GUI version of gFTP) +18. Configuring gFTP + 18.1. Proxy host setup + 18.2. Proxy security concerns + 18.3. Configuring file extensions + 18.4. Desktop icon +19. Staying in touch + 19.1. gFTP bugs + 19.2. gFTP mailing list + 19.3. gFTP home page and FAQ +20. Legal section + 20.1. Copying gFTP + 20.2. Warrenty + 20.3. Source code + + +1. Connecting to a remote site + +This section describes the various ways that you can connect to a remote +site using gFTP. + +1.1. Connecting using the Open URL button + + On the top line of gFTP you will see the word "Remote". Click on Remote +and you will get a pop down menu. Click on "Open URL" and you will get a +command line which has several uses. You can enter a URL name in this +command line in a manner very similar to the way it works in most web +browsers. You can type in the URL, paste the URL from the clipboard, or Drag +and Drop a URL from another application (say Mozilla). gFTP will automatically +disconnect from the site that you are connected to, if any, and connect to the +site you specified in the Open URL window. + +When you click on the Open URL button, several things are checked +(in the following order): + + - If you are already connected to a site and you click the Open URL + button, you will be disconnected from the site that you are + connected to. + + - If you have a hostname entered on the toolbar, it will connect to + that host. + + - If the above 2 conditions are false, then it will bring up the + Open URL dialog window where you can enter a FTP URL to connect to. + FTP URL's can look like some of the following: + + ftp://ftp.myhostname.com/pub (this will log in as anonymous) + ftp://user@ftp.myhostname.com/pub (log in as user. You will be + prompted for a password) + ftp://user:password@ftp.myhostname.com/pub (log in as user/password) + +1.2. Connecting using bookmarks + + Bookmarks are the easiest way to connect to a remote site. Click on +Bookmarks and select which site you want to connect to from the pop down menu. +If gFTP doesn't have a password for the site you are trying to connect to, it +will prompt you for one. Due to security reasons, gFTP will not save a password +in your bookmark file when gFTP obtains the password from a prompt. + +1.3. Connecting using the toolbar + + You can use the toolbar at the top of the window to connect to a remote +site. The only mandatory field to fill in is the hostname. You can type in +the hostname or you can copy it from the clipboard. When entering a hostname in +the toolbar do not include a directory name and file name. If you do +enter a complete URL gFTP will eventually give you an error message: "Cannot +look up hostname (hostname): Name or service not known". If you have a complete +URL to enter or paste, a better method would be to go to section 1.1 and +use the Open URL button. The way to handle a complete URL name on the toolbar +is to split up the URL with the hostname in the Host field and the directory +and/or file name in the directory name field on the right side of the screen +just above the message that says "Not connected*". + +All of the other fields in the toolbar are optional: + + If you don't fill in the port, it will default to the ftp port in your +/etc/services file (usually port 21). + + If you don't fill in a username, it will default to logging you in as +anonymous. + + Once you have all your information filled in, you can either +hit enter in any of the host, port, user or password fields and gFTP will +connect you to the remote site. + +1.4. Connecting using command line parameters + + You can start the GUI version of gFTP by using a KDE desktop application link +or a Gnome desktop application link. If you want to go to a specific site +immediately on startup you can tell gFTP to connect to that site by typing in +that site's URL after the gftp command. For example: +gftp ftp://ftp.myhostname.com/pub + + gftp-gtk is a the name of the GUI version of gFTP. The command gftp is +actually a script which decides whether, under the circumstances, to launch +gftp-text or gftp-gtk. If gftp does not launch the version that you want you +can use gftp-text or gftp-gtk. + + +2. Downloading files + + Once you have successfully connected to a remote site you can then +select the files that you want and download them. This section describes +several ways that you can select and download files in gFTP. + +2.1. Traversing remote directory trees + + In the center of the right half of the gFTP screen you will find two windows. +The upper window shows what remote directory you are currently connected to. +The lower window is a listing of that directory's contents. To open a +directory, double click on the directory name. To go back up to a parent +directory double click on the .. at the top of the direcory listing. +Be careful that you are not double clicking on a file name unless you intend to +download that file. You can also change directories by clicking on +Remote->Change Directory. + + You can control which files are shown in the remote directory window by +clicking on Remote->Change Filespec. Then enter the filespec that you would +like to see. For example you could enter *.rpm to eliminate everything but rpm +files in the directory listing. + + You can also control which files are shown in the remote directory window by +clicking on Remote->Show Selected. Then the remote directory will only show +the file names of files that are also on the transfer queue. + + Almost every FTP site limits the portion of their directory tree that you +can access. When you double click on the .. at the top of the directory +listing and nothing happens that means that you are as low in the directory +tree as you are allowed to go. + +2.2. Downloading a Single File + + To download a file double click on the file name. +Or + Drag and Drop a file name from the remote directory window to the local + directory window. +Or + Drag and Drop a file name from a web browser (such as Opera) to the + gFTP local directory window. +Or + Click on the file name and click on the left arrow near the center of the + screen. + +2.3. Downloading multiple files + + If you want to specify several files to download one after the other then you +must first throw the "Start file transfer" toggle off. What this means is that +when the toggle is on, gFTP starts downloading immediately when you select a +file. When the toggle is off you can stack up as many selections as you want +on the transfer queue without gFTP starting to download. You can use any of the +selection methods described in the previous section on downloading single files. +You can also select several files at once by using some of the commands on the +Remote menu. Click on Remote. Click on the appropriate command(s) and then +click on left arrow. The commands are: + + Select All Files - select every file in the current directory + + Select All - select every file in the current directory and every file in + every subdirectory of the current directory + + Deselect All - erase your selections and start over + + Then when you have finished selecting files you turn on the "Start file +transfer" toggle on and gFTP will begin working its way through all of the +downloads, one by one. To turn the toggle on click on +FTP->Options->Start file transfers->Apply->OK. + +2.4. Downloading from multiple sites + + One of the features of gFTP is that you can queue download files from +different remote sites. Once you have a file(s) download started, you can +safely disconnect from the remote site by clicking on Remote->Disconnect, and +it will not harm the download in progress. You can then connect to another +remote site, and select another file(s) to download. gFTP will add the new +selections to the transfer queue and download all of the files in the queue +sequentially. + +2.5. Simultaneous downloads from multiple sites + + In the previous section I described how to queue up downloads from multiple +remote sites. gFTP also has the ability to download from multiple sites +simultaneously. Whether gFTP does the downloads sequentially or in parallel +is controlled by the "Do one transfer at a time" button. To find this button: +click on FTP->Options. When the "Do one transfer at a time" button +is on then gFTP will download files sequentially. When the "Do one transfer at +a time" button is off then gFTP will open up a connection to each remote site +listed in the transfer queue and do as many downloads simultaneously as there +are remote sites in the transfer queue. + + Whether simultaneous downloading is an advantage to you or simply a confusion +factor depends on how you are connected to the Internet. If you are connected +to an ISP with a dial-up modem then simultaneous downloading buys you nothing, +you should leave the "Do one transfer at a time" button on. If you are on a +high speed local network connected to a proxy host which is attached to +multiple trunk lines then simultaneous downloads could save you a lot of +download time. If you are not on a dial-up modem and haven't a clue about your +network line configuration I suggest that you turn off the "Do one transfer at a +time" button and give gFTP a real workout as a speed test. If you get any +interesting results let me know. + +2.6. Differences between downloading in ASCII and BINARY mode + + If you download a file in binary mode, gFTP will transfer the file as is, +making no modifications to it. But, if you are downloading text files, you +should consider downloading them as ascii (unless you're downloading them from +another unix machine, in which case either ascii or binary works fine). The +problem is that DOS and Unix use different methods to show end of line. + +In DOS, the lines in text files will have a carriage return and line feed +after them: + +This is a line in a DOS text file\r\n + +But, in unix the file will just be stored with a line feed at the end: + +This is a line in a UNIX text file\n + +If you download a text file from a DOS machine as binary, and open it up in +an Unix program like vi, you will see some weird Ms at the end of each +line. These are the carriage returns. To get around this, download the file in +ascii mode, and gFTP will do the proper conversion for you. You can change +between ascii and binary in the ftp menu. + + +3. Uploading files + + Uploading is a lot simpler if you collect all of the files that you want to +upload in the local directory before you connect to a remote site. The local +directory is the directory you specified in FTP->Options->Startup Directory. + + Once you have successfully connected to a remote site you can then +select the files that you want and upload them to a specific place on the +remote site. This section describes several ways that you can select and upload +files in gFTP. + +3.1. Selecting the remote directory + + In the center of the right half of the gFTP screen you will find two windows. +The upper window shows what remote directory you are currently connected to. +The lower window is a listing of that directory's contents. To open a +directory, double click on the directory name. To go back up to a parent +directory double click on the .. at the top of the direcory listing. +Be careful that you are not double clicking on a file name unless you intend to +download that file. + + You can control which files are shown in the remote directory window by +clicking on Remote->Change Filespec. Then enter the filespec that you would +like to see. For example you could enter *.rpm to eliminate everything but rpm +files in the directory listing. + + You can also control which files are shown in the remote directory window by +clicking on Remote->Show Selected. Then the remote directory will only show +the file names of files that are also on the transfer queue. + + Almost every FTP site limits the portion of their directory tree that you +can access. When you double click on the .. at the top of the directory +listing and nothing happens that means that you are as low in the directory +tree as you are allowed to go. + +3.2. Working with the remote file tree + + Uploading often consists of more than simply copying a file to a remote site. +You may have to create or rearrange portions of the file tree on the remote +site. Right click on a blank spot in the directory window for the remote site +and you will get a pop up menu which contains some commands for manipulating the +remote site file tree. These commands include: + + Delete - delete a remote file or directory + + Make Directory - create a directory on the remote site + + Rename - rename a remote file or directory + + Edit - edit a remote file using the editor specified in FTP->Options->Edit + program + + View - view a remote file using the editor specified in FTP->Options->View + program + + Chmod - change the attributes of a remote file or directory + +3.3. Uploading a single file + + To upload a file double click on the file name in the local directory window. +Or + Drag and Drop a file name from the local directory window to the remote + directory window. +Or + Click on the file name in the local directory and click on the right arrow + near the center of the screen. +Or + Drag and Drop a file name from a file manager such as Midnight Commander to + the gFTP remote directory window. + +3.4. Uploading multiple files + + If you want to specify several files to upload one after the other then you +must first throw the "Start file transfer" toggle off. What this means is that +when the toggle is on, gFTP starts uploading immediately when you select a +file. When the toggle is off you can stack up as many selections as you want +on the transfer queue without gFTP starting to upload. You can use any of the +methods described in the previous section to select files to upload. You can +also select several files at once by using some of the commands on the Local +menu. Click on Local. Click on the appropriate command and then click on right +arrow. The commands are: + + Select All Files - select every file in the current directory + + Select All - select every file in the current directory and every file in + every subdirectory of the current directory + + Deselect All - erase your selections and start over + + Then when you have finished selecting files you turn the "Start file +transfer" toggle on and gFTP will begin working its way through all of the +uploads, one by one. To turn the toggle on click on FTP->Options->Start file +transfers->Apply->OK. + +3.5. Passive and non passive file transfers + + When uploading files to a server you will find that some servers support +passive file transfers and others do not. Those sites which do not support +passive file transfers usually block them because they consider passive file +transfers too insecure. When you run into a site that does not support +passive file transfers you can try toggling passive file transfers off. You can +find the passive file transfers toggle by clicking on File->Options. Click on +the Passive file transfers button to toggle passive file transfers on and off. + + The most common error message given out by a site that does not support +passive transfers is: Cannot create a data connection: Connection refused + + +4. Transfering files between remote sites (FXP) + + The File Transfer Protocol has a subsection called File eXchange Protocol. +gFTP can use FXP to transfer files between two remote sites. gFTP will set up a +direct connection between the two remote sites so that the transfer proceeds +from one remote site to the other without your machine acting as an +intermediary. In order for gFTP to do a FXP transfer both remote sites must +support FXP transfers. Also the receiving site must support passive transfers +and the sending site must allow gFTP to open a port to the receiving site. If +you cannot get the two remote sites to do a FXP transfer then the fall back +method is to download the file(s) from the source remote site to your machine +and then upload the file(s) to the receiving remote site. The fall back method +will take at least twice as long as a FXP transfer and perhaps as much as an +order of magnitude longer. + + The next several sections describe the sequence of actions that you must +do in order to start a FXP transfer. This explanation of FXP will assume that +you know how to use gFTP to download and upload files. Check the sections on +downloads and uploads to fill in the details missing in the FXP explanation. + +4.1. Connecting to the receiving site + + You connect to the receiving remote site the same as if you are doing an +upload to that site. + +4.2. Selecting the receiving directory + + You select the receiving remote directory the same as if you are doing an +upload to that directory. + +4.3. Working with the receiving file tree + + You manipulate the receiving remote file tree the same as if you are doing +an upload to that site. + +4.4. Connecting to the sending site + + On the top line of gFTP you will see the word "Local". Click on Local +and you will get a pop down menu. Click on "Open URL" and you will get a +command line window. You can enter an URL name in this command line in a manner +very similar to the way it works in most web browsers. You can type in the +URL, paste the URL from the clipboard, or Drag and Drop an URL from another +application (say Konqueror). gFTP will connect to the site you specify in the +Open URL window. + +4.5. Traversing the sending site directory tree + + In the center of the left half of the gFTP screen you will find two windows. +The upper window shows what remote sending site directory you are currently +connected to. The lower window is a listing of that directory's contents. To +open a directory, double click on the directory name. To go back up to a parent +directory double click on the .. at the top of the direcory listing. Be +careful that you are not double clicking on a file name unless you intend to +transfer that file to the receiving remote site. You can also change +directories by clicking on Local->Change Directory. + + You can control which files are shown in the left directory window by +clicking on Local->Change Filespec. Then enter the filespec that you would +like to see. For example you could enter *.deb to eliminate everything but +Debian files in the directory listing. + + You can also control which files are shown in the remote directory window by +clicking on Local->Show Selected. Then the local directory will only show +the file names of files that are also on the transfer queue. + + Almost every FTP site limits the portion of their directory tree that you +can access. When you double click on the .. at the top of the directory +listing and nothing happens that means that you are as low in the directory +tree as you are allowed to go. + +4.6. Selecting files from the sending site + + If you want to specify several files to transfer one after the other then you +must first throw the "Start file transfer" toggle off by clicking on +FTP->Options->Start file transfers->Apply->OK. If you are only transfering a +single file then you can ignore the "Start file transfer" toggle. + + To transfer a file double click on the file name in the left directory + window. +Or + Drag and Drop a file name from the left directory window to the right + directory window. +Or + Click on the file name in the left directory window and click on the right + arrow near the center of the screen. + + Select as many files as you want from the left directory window and gFTP will +place them on the queue. You can traverse the left directory window while you +are selecting files. You can also select several files at once by using some +of the commands in the Local menu. Click on Local. Click on the appropriate +command and then click on right arrow. The commands are: + + Select All Files - select every file in the current directory + + Select All - select every file in the current directory and every file in + every subdirectory of the current directory + + Deselect All - erase your selections and start over + + When you are finished selecting files then toggle "Start file transfer" on +and gFTP will start transferring the files in the queue. + + +5. Resuming transfers + + The File Transfer Protocol has the ability to restart an interrupted transfer +at the point where it left off. gFTP supports the resume function. If the +remote site you are dealing with also supports resume (most FTP sites do, HTTP +sites do not) then you can resume an interrupted transfer. + +5.1. Manual resumes + + You can interrupt a transfer in the middle by exiting from gFTP and later +resume the transfer at the point where it left off. To resume a download start +up the download just like any other download. gFTP will find the partially +downloaded file in the local download directory and then ask you whether to +resume the download or to start all over. Choose resume. Then gFTP will +connect to the remote site and negotiate with the remote site to resume the +download at the point where it was interrupted. + + Uploads and FXP transfers can be resumed in a manner analogous to resuming a +download. + + The only sticking point with exiting gFTP and then starting it up again is +that you will lose the queue. gFTP erases the queue when you exit and when you +start up again you will have to rebuild the queue. If you are doing a single +file transfer then erasing the queue is unimportant. + + Resume is a well defined Internet protocol which requires the cooperation of +both gFTP and the server software. Occasionally you will run into a server +which does not support the Resume protocol. In the case of downloads all is +not necessarily lost. gFTP will try to resume any download when it finds the +file name in the local download directory. You might be able to salvage the +download by finding another remote site to download that same filename from, a +site that supports the FTP Resume protocol. + +5.2. Automatic resumes + + If gFTP is in the process of transferring some files and the connection closes +for some reason, gFTP will try to reconnect again and continue with the file +transfer where it left off. You can set how many times to reconnect and how +long to wait in the options dialog. In order to specify reasonable reconnect +options you need to understand some of the things that can go wrong with a +transfer. + + The most common cause of transfer problems is an overloaded FTP server. When +a server becomes overloaded there will be times when the server just can't get +around to passing gFTP the next block of data (or receiving the data in the +case of an upload). In the gFTP progress window you will get a message that the +transfer is stalled. If the transfer is stalled for over 30 seconds gFTP will +time out the transfer and disconnect. (Don't mess with the Read timeout Option +unless you know what you are doing. You can get timeouts for a lot of other +reasons that an overloaded server.) gFTP then waits the time interval specified +in FTP-Option and then reconnects. + + Some servers recognize when they are overloaded and begin deliberately +disconnecting clients until they get back down to the maximum number of +transfers that they can reasonably serve. If gFTP gets disconnected it waits +the time interval specified in FTP->Options and then reconnects. These servers +sometimes remember who they have just bounced off and if you try to reconnect +immediately they may tell gFTP to stop trying to automatically reconnect. So in +the Options (Ftp->Options->Network->Retry sleep time) you want to wait just long +enough that the busy server will have forgotten you and then reconnect. The +gFTP default is 15 seconds. + + The other reconnect Option that you are interested in is Connect retries +(Ftp->Options->Network->Connect retries). Connect retries is the number of +times that gFTP will reconnect before giving up altogather. There two ways to +approach this option: + + If gFTP has to keep reconnecting to a remote server then the transfer can be +very slow. You might want to switch another remote server which is faster. +If the file name on the new server is exactly the same as the file name on the +previous server then you can resume a download at whatever point you got to on +the first server. In this case set FTP->Options->Connect retries to 3, which is +the gFTP default. + + If you want to keep chugging away at the transfer until it finishes, no +matter what, then set FTP->Options->Connect retries to 0. + + +6. FTP password and user id + + The standard File Transfer Protocol requires the use of a user id and a +password. gFTP will always use a user id and a password for each FTP +connection. + +6.1. Anonymous FTP + + Many FTP server sites are public sites which make their files freely +available to anyone who wants to download them. To get around the nuisance of +user ids and passwords public sites use the standard anonymous FTP protocol. +gFTP uses an user id of anonymous and a password that looks like a valid email +address (internet@linux.local). You can change the anonymous email +address/password by clicking on FTP->Options->General and changing the Email +address field. + +6.2. Secure FTP password and user id + + Some FTP server sites are private sites which are very selective about who +can download files from that site. Almost all upload sites are selective. +Private sites insist that you obtain a user id and a password, perhaps even +pay money for them. Then you have to use that particular user id and password +to access the private FTP site. + + If you want to save your password for a bookmarked site in the bookmark file, +you should read the section on security concerns first. Then if you still +want gFTP to remember your bookmark entry passwords there are two ways to do it. +The easier way is to add the password manually to the bookmark file +(/home/user/.gftp/bookmarks) using a text editor. Or you can have gFTP add +the bookmark password by: click on Edit bookmarks, right click on the +appropriate bookmark entry, click on Properties, and turn off "Log in as +ANONYMOUS". Then gFTP will make the Username and Password fields available +for editing. + + You can tell gFTP not to use anonymous FTP by entering the user name in the +URL. For example: + + ftp://user@ftp.myhostname.com/pub (log in as user. gFTP will prompt you + for a password) + + You can give gFTP both the user name and password in the URL. For example: + + ftp://user:password@ftp.myhostname.com/pub (log in as user/password) + + +6.3. FTP security concerns + + Some private FTP sites require you to use a valid email address as either the +user id or the password. An organization with a reputable name to protect will +not spam your email address. With other people or organizations you are +vunerable to spamming. You might consider opening a free email account +somewhere and use it for spam bait only. + + +7. Local directory + + The local directory is the directory on your computer from which you will +upload files or which you will use to receive downloaded files. A window +showing the local directory is located in the middle left of the gFTP screen. + +7.1. Specifying the local directory + + You can set the default local directory by clicking on FTP->Options and then + typing in the local directory path into Startup Directory. +Or + You can change the local directory by entering the new name into the small + window just above the local directory window. Your new name will be entered + into the local directory history but the new name will not replace the + default name in Options. +Or + You can select a name from the local directory history list. Click on the + down arrow to the right of the local directory name and then click on the + history entry you want to use. Your new name will be entered into the local + directory history but the new name will not replace the + default name in Options. +Or + You can traverse the local directory tree by clicking on the directory names + in the local directory window. To open a directory, double click on the + directory name. To go back up to a parent directory double click on the .. + at the top of the file listing. Be careful that you are not double clicking + on a file name unless you intend to upload that file. + +7.2. Working in the local directory + + There are several operations that gFTP can perform in the local directory. +You can perform the following operations regardless of whether you are connected +to a remote site or not: + + Make a directory - Right click on a blank area in the local directory window. + Then left click on Make Directory. Enter the new directory name in the + pop up window and click on Create. + + Delete a directory or filename - Right click on the directory or filename. + Then left click on Delete. + + Rename a directory or filename - Right click on the directory or filename. + Then left click on Rename. Enter the new name in the pop up window and + click on Rename. + + Change the attributes of a directory or filename - Right click on the + directory or filename. Then left click on Chmod. Set the attributes in + the pop up menu and click on Change. + + Edit a file - Right click on the filename. Then left click on Edit. The + file will be opened in the editor that you specified FTP->Options->Edit + program. + + View a file - Right click on the filename. Then left click on View. The + file will be opened in the program that you specified FTP->Options->View + program. + + Refresh the listing - Right click on a blank area in the local directory + window. Then left click on Refresh. gFTP will refresh the local + directory listing. + + Change the filespec - Click on Local->Change Filespec. Then enter the + filespec that you would like to see. For example you could enter *.html to + eliminate everything but html files in the directory listing. + + +7.3. Formating the local directory window + + You can arrange the format of the local directory window by sliding the +Filename, Size, User, Group, Date, and Attribs labels to wherever you want them. + + You can change the overall size of the local directory window by using a text +editor to change the config file (/home/user/.gftp/gftrc). The parameters which +control the local directory window size are listbox_local_width and +listbox_file_height. + + +8. Remote directory + + The remote directory is the directory on a remote site from which you will +download files or which you will use to receive uploaded files. A window +showing the remote directory is located in the middle right of the gFTP screen. + +8.1. Specifying the remote directory + + When you enter a URL in the Remote->Open URL window, gFTP shows that portion +of the URL which designates a remote site directory name in the small window +just above the remote directory window. + +8.2. Formating the remote directory window + + You can arrange the format of the remote directory window by sliding the +Filename, Size, User, Group, Date, and Attribs labels to wherever you want them. + + You can change the overall size of the remote directory window by using a +text editor to change the config file (/home/user/.gftp/gftrc). The parameters +which control the remote directory window size are listbox_remote_width and +listbox_file_height. + + +9. Transfer window + + The transfer window is the second window from the bottom. It shows the queue +and the progress of the current file transfer(s). + +9.1. Queue + + The left hand side of the transfer window shows the queue of transfers to be +done. You can stack several transfers in the queue and gFTP will work its way +through the queue transferring the files in the order that they were entered in +the queue. Whether gFTP does the transfers sequentially or in parallel is +controlled by the "Do one transfer at a time" button. To find this button: +click on FTP->Options. When the "Do one transfer at a time" button is on then +gFTP will transfer files sequentially. When the "Do one transfer at a time" +button is off then gFTP will open up a connection to each remote site listed +in the transfer queue and do as many transfers in parallel as there are remote +sites in the transfer queue. + + You can manipulate the entries on the transfers queue by first clicking on +the entry to highlight it and then clicking on Transfers. The Transfers pop up +menu makes these commands available: + + Stop Transfer - highlight the queue entry for the file currently being + transferred and then click on Transfers->Stop Transfer + + Start Transfer - highlight the queue entry for the file you want to + transfer next and then click on Transfers->Start + Transfer + + Move File Up - move the file up one position in the queue + + Move File Down - move the file down one position in the queue + + Remove File - delete the file from the queue + + Skip Current File - leave the file name on the queue but do not transfer the + file + + gFTP does not save the transfer queue when gFTP exits. If you exit gFTP and +then start it again you will have an empty queue. + +9.2. Progress + + The right hand side of the transfer window shows the status of the +transfer(s) in progress. gFTP shows the % completion of the entire queue, the +size of the file currently being transfered, how many bytes of the current file +have already been transferred, which files are finished transfering, and which +files are waiting to begin transfering. The progress report also shows the +current transfer rate and gives an estimated length of time until the entire +queue is transferred. Your milage may vary. + +9.3. Formating the transfer window + + You can arrange the format of the transfer window by sliding the Filename and +Progress labels to wherever you want them. + + You can change the height of the remote directory window by using a text +editor to change the config file (/home/user/.gftp/gftrc). The parameter +which controls the transfer window height is transfer_height. + + +10. Log and log window + + gFTP keeps a log (/home/user/.gftp/gftp.log) which records what gFTP has +done. The log is erased and begun anew at each startup of gFTP. The log +entries are displayed in the window at the bottom of the gFTP screen. You can +specify a different location for your log file by clicking on FTP->Options and +entering the now location in Log file. + +10.1. Log commands + + If you right click anywhere on the log window then a pop up menu will appear +with three commands: + + Clear - double clicking on Clear erases all of the log entries. + + View log - double clicking on View log launches the program you specified in + FTP->Options->View program to display the log. + + Save log - double clicking on Save log opens a file tree display window which + you can use to save the gFTP log anywhere that you want to put it. + + The Clear, View log, and Save log commands can also be accessed by clicking +on the Logging button at the top of the gFTP screen. + +10.2. Formating the log window + + You can change the overall size of the log window by using a text editor to +change the config file (/home/user/.gftp/gftrc). The parameters which control +the remote directory window size are log_height= and max_log_window_size=. + + You can change the colors of the various message types in the log window by +using a text editor to change the config file (/home/user/.gftp/gftrc). The +parameters which control the log window message colors are +send_color=rrii:ggii:bbii, recv_color=rrii:ggii:bbii, +error_color=rrii:ggii:bbii, and misc_color=rrii:ggii:bbii. + + rrii:ggii:bbii is the color code where each letter stands for a hexidecimal +digit from o through f. + + rr - amount of red in the color + gg - amount of green in the color + bb - amount of blue in the color + ii - intensity of the color + + examples: bright red rrii:ggii:bbii = ffff:0000:0000 + dull brown rrii:ggii:bbii = a000:8d80:4600 + + +11. Bookmarks + + gFTP has a bookmarks file which looks and acts very similar to the bookmarks +file in a web browser. gFTP comes with several popular download sites listed in +the bookmarks file. + +11.1. Using a bookmark entry + + To connect to a remote site, click on Bookmarks and a drop down menu appears. +Navigate the tree until you find the site you want to connect to. Click on that +entry and gFTP will connect to that site. If gFTP doesn't have a password for +the site you are trying to connect to, it will prompt you for one. For +security reasons, gFTP will not save this password in your bookmark file when it +prompts you for it. + +11.2. Adding a bookmark + + There are two ways to add a bookmark entry to the gFTP bookmark file: + + When you are connected to a site you can click on Bookmarks->Add bookmark. +gFTP will open a window in which you enter the entire path name for the new +entry. For example: If you find a Czech mirror site for SuSE downloads you +could file the bookmark as SuSE Sites/Czech mirror and gFTP will add Czech +mirror to the existing SuSE Sites folder. + + At any time, connected or not, you can add a bookmark entry by clicking on +Bookmarks->Edit bookmarks. Then right click on a blank area of the bookmarks +window. A menu will pop up. Click on New item. Then enter the entire path +name of the new entry in the pop up window. (For example: To create the first +site in a new Mandrake folder enter Mandrake Sites/USA mirror.) Click on +create. At this point you have created a bookmark entry that does not point +anywhere. Now right click on the new entry, click on Properties, and fill out +the information requested in the pop up form. Click on Apply and click on OK. +You are now finished adding the new bookmark entry. + +11.3. Editing bookmarks + + You can change the details in a bookmark entry by clicking on Bookmarks->Edit +bookmarks, right click on the bookmark entry, and click on Properties. A form +will pop up which you can use to edit the entry. Then click on Apply and OK. + + You can delete a bookmark or an entire folder of bookmarks by clicking on +Bookmarks->Edit bookmarks, right click on the bookmark entry, and click on +Delete. + + You can rearrange bookmarks with drag and drop. Rearrangement of the +bookmark entries in gFTP works very similar to the way that it works in most web +browsers. You drag the entry to the appropriate spot in the directory tree and +drop it. With a little practice you can get the entries to go where you want +them to go. + +11.4. Bookmark passwords + + If gFTP doesn't have a password for the bookmarked site you are trying to +connect to, gFPT will prompt you for one. Due to security concerns, gFTP will +not save this password in your bookmark file. If you want to save your +password for a bookmarked site in the bookmark file, you should read the section +on security concerns first. Then if you still want gFTP to remember your +bookmark entry passwords there are two ways to do it. + + The easier way is to add the password manually to the bookmark file + (/home/user/.gftp/bookmarks) using a text editor. An example of a bookmark + entry containing a password is: ftp://user:password@ftp.myhostname.com/pub +Or + You can have gFTP add the bookmark password by: click on Edit bookmarks, + right click on the appropriate bookmark entry, click on Properties, and turn + off "Log in as ANONYMOUS". Then gFTP will make the Username and Password + fields available for editing. Enter the Username and Password fields. Click + on Apply and click on OK. + +11.5. Bookmark security concerns + + When you save a password in the gFTP bookmark file you are creating a +potential security vulnerabilty because gFTP does not encrypt stored passwords. +Any cracker could write a program to extract passwords from the gFTP bookmarks +file. You should weigh the chances of a malicious attack on your machine and +the value of the password protected data versus the convenience of storing the +passwords before deciding whether or not to store passwords in the bookmark +file. + + +12. FTP protocol + + File Transfer Protocol is a hardware and software independent Internet +protocol which is used to transfer information between servers and clients. +Servers are computers which give out information and clients are computers that +receive information. It is possible for a computer to be both an FTP client and +server. gFTP allows your computer to act as a FTP client. + + When gFTP contacts a FTP server it establishes two connections, a control +connection and a transfer connection. gFTP first establishes a control +connection by sending an user id and a password to the server. Then gFTP +requests that a particular file(s) be transferred. Once gFTP has started a FTP +transfer gFTP can drop the control connection without interrupting the transfer. + +12.1 Invoking FTP + + gFTP knows to use FTP by the first three letters of the URL. An URL for a + FTP transfer begins with ftp://. +Or + Click on the button immediately to the left of the red light and click on FTP + + +13. HTTP protocol + + HyperText Transfer Protocol is a hardware and software independent Internet +protocol which is used to transfer information between servers and clients. It +is probably the most used protocol on the Internet. gFTP can act as a HTTP +client. + + From the client standpoint the HTTP protocol is far simpler than the FTP +protocol. Among other things, HTTP has no user ids and passwords. This +simplicity makes file transfers using HTTP somewhat more simple minded. + +13.1. Invoking HTTP + + gFTP knows to use HTTP by the first four letters of the URL. An URL for a + HTTP transfer begins with HTTP://. +Or + Click on the button immediately to the left of the red light and click on + HTTP. + + +14. SSH protocol + + SSH (Secure SHell) is a protocol which provides a high level of security +for transfering files from one computer to another across the Internet. gFTP +implements the SSH protocol by calling upon an SSH program to wrap a layer of +security around what would otherwise be an ordinary FTP tansfer. In effect +FTP "tunnels" through a secure SSH connection. + +14.1. Configuring SSH + + In order to configure your SSH transfers click on FTP->Options->SSH and fill +out the form. The required entries are: + + SSH Prog Name - This is the name of the program which provides the SSH + wrapper. + + SSH Extra Params - These are the parameters that the SSH wrapper program + needs to build an encryption key. + +14.2. Invoking SSH + + gFTP knows to use SSH by the first three or four letters of the URL. An URL + for a SSH transfer begins with ssh:// or ssh2://. +Or + Click on the button immediately to the left of the red light and click on + either SSH or SSH2 + +14.3. SSH and SSH2 + + SSH recently went through a major revision to plug known security holes. The +latest version of SSH is called SSH2. SSH and SSH2 are not compatible with each +other. gFTP supports both SSH and SSH2. + + +15. Miscellaneous commands + +15.1. Window + + You can reverse the roles of the local window and the remote window. Click +on FTP. The Window 1 and Window 2 buttons can be used to switch the roles of +the local and remote windows. Window 2 is the default and this user's guide +describes everything as set up by Window 2. Clicking on Window 1 switches the +roles of the two windows to the mirror image of that described in this document. + +15.2. SITE commands + + One of the features of the File Transfer Protocol is the ability to create +SITE commands. A FTP server administrator can create customized commands for a +FTP client program, such as gFTP, to use. These customized commands are called +SITE commands. + + If you want to use a SITE command while you are connected to a FTP server +then click on either Remote or Local, whichever is connected to the remote site +in question. Then click on Send SITE Command and a pop up window will open. +You can enter the SITE command in the window. Then click on OK and gFTP will +send the SITE command to the FTP server. + +15.3. Bidirectional transfers + + It is possible that you may want to open a connection to a remote site and +transfer files in both directions. Click on Transfers and you will find some +commands to help you change the direction of the transfers without having to +drop the connection and restart it in the other direction. These commands are: + + Put Files - send the files on the transfer queue to the remote site + + Retrieve Files - copy the files on the transfer queue from the remote site + to the local site + +15.4. Clear cache + + gFTP keeps a cache of data from remote sites. It is possible that while you +are working with a remote site other people are making changes to that site. To +get rid of stale copies of the remote directory tree in the cache click on +Tools->Clear Cache. + +15.5. Compare Windows + + An easy way to check which files have been transferred and which files have +not is to click on Tools->Compare Windows. gFTP will highlight any file names +which appear in either the local directory or the remote directory but not both. + +15.6. Disconnect + + You can disconnect from a remote site at any time. Disconnecting does not +stop any transfers already in prograss. You can disconnect by: + + clicking on the red button when it is lit up +Or + clicking on Remote->Disconnect +Or + clicking on Local->Disconnect + + +16. Using gftp-text (the command line version of gftp) + + The gFTP package includes a completely functional command line version of +gFTP. You can launch the command line version by typing in the command, +gftp-text, at your console prompt. The command gftp is actually a script which +decides whether, under the circumstances, to launch gftp-text or gftp-gtk. If +gftp does not start the version that you want you can finesse that problem by +using gftp-text or gftp-gtk instead of gftp. + +16.1. Downloading entire directories and subdirectories + + If you want to download entire directories including subdirectories you +should look at using gftp-text. Some downloads are simpler to invoke using +gftp-text. For example: + + gftp-text -d ftp://ftp.somesite.com/someplace + + If someplace is a directory, it'll automatically download all its +subdirectories as well. If you want to transfer a file through SSH instead of +FTP then change the ftp:// to ssh:// + +16.2. Documentation for gftp-text + + gftp-text will give you a prompt: ftp> +You can learn more about gftp-text by typing in help at the ftp> prompt. You +can also get instructions in how to use gftp-text by typing in "man gftp" or +"info gftp" at the console prompt. + + +17. Using gftp-gtk + + gftp-gtk is the name of the GUI version of gFTP. The gftp command is +actually a script which decides whether, under the circumstances, to launch +gftp-text or gftp-gtk. + + +18. Configuring gFTP + + All of the gFTP configuration options are specified in the file +/home/user/.gftp/gftprc. + +18.1. Proxy host setup + + If your computer is on a local network then you are probably connected to the +internet through a proxy host. A proxy host can connect several users to the +internet. A proxy host often also acts as a firewall, possibly filtering +messages in both directions. If you are connected to the internet through a +proxy host then gFTP needs passwords and other configuration information to +make a connection through the proxy host to the internet. + + To set up your proxy host and/or firewall configuration, click on +FTP->Options. You can click on HTTP Proxy and FTP Proxy to set up your +proxy hosts, user names, and passwords. In the FTP Proxy form, you can set up +how you want gFTP to log into the proxy host. I have many of the common types +of proxy hosts that you will encounter already descried in gFTP. If you are +using a very complex proxy host configuration then you may have to use a text +editor to edit the config file (/home/user/.gftp/gftprc). The fields in the +config file that pertain to proxy host and/or firewall configuration are: + + # Firewall hostname + firewall_host= + + # Port to connect to on the firewall + firewall_port=21 + + # Your firewall username + firewall_username= + + # Your firewall password + firewall_password= + + # Your firewall account (optional) + firewall_account= + + # This specifies how your proxy server expects us to log in + proxy_config= + + # Firewall hostname + http_proxy_host= + + # Port to connect to on the firewall + http_proxy_port=80 + + # Your firewall username + http_proxy_username= + + # Your firewall password + http_proxy_password= + +18.2. Proxy security concerns + + When you have gFTP save a proxy password you are creating a potential +security vulnerabilty. gFTP does not encrypt stored passwords. They are kept +in plain text in the file, /home/user/.gftp/gftprc. Any cracker could write +a program to extract passwords from the gftprc file. You should weigh the +chances of a malicious attack on your machine and the value of the proxy +passwords versus the convenience of storing the passwords before deciding +whether or not have gFTP store proxy passwords. Also if you are on a local +network then you are probably a member of a beaurocracy, lucky you. In that +case you should give a passing thought to your organization's security rules. + +18.3. Configuring file extensions + + gFTP has the ability to use mime types. Some mime types come pre-configured +with gFTP and you have complete control to configure the gFTP mime types any way +that you want. + + Towards the bottom of the config file (/home/user/.gftp/gftprc), there is a +section that has some ext= lines. Here you can control via a file extension, +the icon in the listbox for it, the default transfer method (ascii or binary), +and a default view/edit program. For example, let's take the line: + +ext=.xcf:gimp.xpm:B:gimp + +The first token, .xcf, is the file extension. The next token, gimp.xpm, is +the default icon to use in the listboxes. You don't have to specify one if +you don't want to. By default, gFTP will search ~/.gftp, $(PREFIX)/share/gftp +(where prefix is your installation prefix), and then /usr/share/icons in that +order. The files must be valid xpm files. The next token, B, specifies +whether or not to transfer a file as Binary or Ascii. If you want to have +something transfer as Ascii, put an A there. If you omit this field, then gFTP +will transfer the file according to whether ascii or binary is selected in +the FTP menu. The final token, gimp, specifies the name of the program to run +to view or edit a file with that extension. You can omit this as well if you +like. + +18.4. Desktop icon + + You can set up gFTP to be started from your Gnome or KDE desktop. The +program name can be either gftp or gftp-gtk. Some suitable gFTP icons are +available in /usr/share/gftp: gftp.xpm down.xpm world.xpm + + +19. Staying in touch + +19.1. gFTP bugs + + gFTP is released under the GNU General Public License. As such there is +ABSOLUTELY NO WARRENTY with gFTP. That said, if you run into ANY bugs in gFTP +please let me know. I take pride in making gFTP as bug free as possible. Since +gFTP is used on a wide variety of hardware and software configurations bugs will +sometimes crop up that I never could have anticipated on the configuration I use +to develop gFTP. Please include as much information as possible in your bug +description. It is better to report too much detail than to report too little +detail in your bug report. Basically, I need enough information to be able to +recreate the bug on my machine. The information that might be useful to me +could include: + +The gFTP version number you are using and what installation method (tarball +or rpm). For example: + + I am using gFTP-2.0.13.tar.gz. + +Please tell me your hardware and software configuration. For example: + +Configuration: + AMD 1.2G CPU with 256M ram + Mandrake 8.1 distribution + KDE 2.2 desktop + KWvDial 0.10 -> dial up modem + kernel 2.2.10 + + Please tell me enough about the problem so that I can try to recreate it. +For example: + + I was connected to jungle.metalab.unc.edu, which is a Mandrake mirror, to do +some downloads. I connected OK using the Remote->Open URL window. I went to +a directory called /pub/Linux/distributions/mandrake/Mandrake/8.1/SRPMS/ and +double clicked on the file alien-7.27-1mdk.src.rpm. gFTP entered this file +name in the queue twice and downloaded it twice. I think gFTP should have +only downloaded it once. This happens intermittently. Sometimes gFTP downloads +files once and sometimes it downloads files twice. gFTP always downloads +alien-7.27-1mdk.src.rpm twice. + +Please attach the gFTP log file (/home/user/.gftp/gftp.log) to your report. + +If you are having trouble with gFTP bookmarks please attach the gFTP bookmark +file (/home/user/.gftp/bookmarks) to your report. + +If you are having trouble with the gFTP configuration please attach the gFTP +configuration file (/home/user/.gftp/gftprc) to your report. + +If you keep passwords in your bookmark file or your configuration file you might +want to x out the passwords before you send the file to me. + +Please send your bug report to: + +Brian Masney masneyb@gftp.org +Elkview, WV USA + +If you find a bug in an older version of gFTP, that bug might already be fixed +in the latest version of gFTP. You can find the latest version at the gFTP +download site by clicking on Bookmarks->General Sites->gFTP. + +19.2. gFTP mailing list + + There is a mailing list available where you can receive announcements about +new versions of gFTP. It is an extremely quiet mailing list and I promise not +to spam you. To subscribe to the gFTP mailing list, send a message to +majordomo@seul.org with the words subscribe gftp-announce in the body. + +19.3. gFTP home page and FAQ + + You can find the latest information about gFTP at the gFTP home page or on +the gFTP Frequently Asked Questions. + +gFTP home page: http://www.gftp.org/ + +gFTP FAQ: http://www.gftp.org/faq.html + + +20. Legal section + + Click on Help->About->License Agreement to find a copy of the GNU General + Public License + +20.1. Copying gFTP + + This program is free software; you can redistribute it and/or modify + it under the terms of the GNU General Public License as published by + the Free Software Foundation; either version 2 of the License, or + (at your option) any later version. + + You should have received a copy of the GNU General Public License + along with this program; if not, write to: + + Free Software Foundation, Inc. + 59 Temple Place - Suite 330 + Boston, MA 02111 + USA + +20.2. Warrenty + + This program is distributed in the hope that it will be useful, + but WITHOUT ANY WARRANTY; without even the implied warranty of + MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the + GNU General Public License for more details. + +20.3. Source code + + gFTP is open source software under the terms of the GNU General Public +License. You can find the gFTP source code by clicking on +Bookmarks->General Sites->gFTP. The tarballs on the gFTP web site contain both +source and binary. The rpm packages are split into binary rpms and source +rpms. The Debian packages contain both binary and source. You may use the +gFTP source code in any way that you wish as long as you conform to the terms +of the GNU General Public License. If you fix any bugs or add any useful +features to gFTP you might consider sending your changes to me to be +incorporated into a future release of gFTP. I welcome any help you might give +me in improving gFTP.