About FTP Use

Gen FTP commands are utility / convenience commands that are built on top of the tcllib ftp package.

Getting Set Up

To configure Gen for using certain FTP-related commands, you need to (A) add the following configuration code to your software, before you start using FTP commands, or (B) open src/gen-config.tcl and configure by hand the following (though beware of overwriting when you update your version of Gen):

set GenNS::Ftp::Server [Required. ip address of your server]
set GenNS::Ftp::Username [Required. username to log on that machine]
set GenNS::Ftp::Password [Required. password to log on that machine]
set GenNS::Ftp::OptionsList [Optional. list of options to use, see here for a list of options you can use.]
set GenNS::Ftp::FileTransferType [Optional. ascii | binary | tenex -- How to transfer the files.]

The OptionsList should look something like this :

"-port 21 -mode active"

Note that you do not have to set OptionsList; you can leave it blank.

Note that for any FTP command which takes in an FTP handle as its first argument, you do not have to configure the above. You can manage the FTP connection yourself and use only a few utility commands to assist you with the rest of your code.

Main Use Cases

The main use cases for this software are for when:

You are writing your own (Tcl) code and want simple file-transfer within it.
The machine you will want to interact with has an FTP server, but (a) you do not know what type of machine it will be (Windows / UNIX) -and/or- (b) you cannot install your own software on it -and/or- (c) it does not have any other file sync software (e.g. rsync) installed on it for you to use.
What you want to do is really pretty simple (e.g. just do a simple mirror or the equivalent of copy/paste).
You do not want to work through the details of the ftp package yourself.

Otherwise you may want to look into a full-featured file sync program. Or, use something simple like this to get going and figure out what you want, and then adopt something else for more advanced usage.

Issues

The following are issues you may encounter, which this software cannot really do anything about. For other issues, see the following section.

Cannot create directory on remote machine and switch into it: May or may not be an issue for you. This may happen because the directory is not made with sufficient permissions. You will have arrange to give it permissions (e.g. use chmod). You will want to try it first and see if it is an issue for you.

Missing Features, For Possible Future Release

FtpDownloadDirectory: This command is internal-only for the current release, due to lack of testing time. It allows downloading a directory with the current connection and takes various options. It will go in the next release.
FtpCleanRemoteDirectory: This command is used for emptying the contents of a directory. Did not have time to test it for this release, but it will most likely go in the next.
Uploading commands: An assortment of uploading commands did not make it into this release, but probably will make it into the next.
Inclusion / Exclusion File Filters: The commands will currently go through all files in the directories. Filters would allow skipping over certain files (e.g. ones with a .bak extension).
Option to offset for difference in clock times: For a situation where the clocks are different, and that is causing transfers that should not happen. Preferrably make them right.
Option to offset for file size difference: Preferrably use binary transfer mode, but this would be for when that is not possible and you are getting a difference in file size.

To Safely See What Would Happen: Dry Run Option

If you do the following :

set GenNS::Ftp::DryRun 1

Then when you run a command, it will print to each change that it would have made. The exception is when it would have had to make a directory and then switch into it to continue on a copy over the contents. At that point, Gen will not create the directory, but rather will skip on to the next item. For that scenario, if you want a complete dry run, you will have to set up the directories yourself, Gen will then recurse into it and continue the dry run as normal. (Possibly a future release could get past this limitation.)

When you are done with the dry run, and want to do things for real, do the following :

set GenNS::Ftp::DryRun 0

Debugging

You can turn on debug info like this :

set GenNS::DebugOn 1

This is an internal feature, is not supported, and will likely change in the future. But it is currently available to help you with any issues you may have.

If You Need More Advanced Features

The FTP within Gen is intended to be simple and serve simple use cases. If you find you need something more, there are quite a few file synchronization programs out there. Personally, I have used unison with good success.

Testing

You may want to run the tests yourself. In that case, you will want to take a look at test/README-test-ftp.txt or test/README-test-ftp.html for details on how to get set up to do that. Running tests may be a good way to confirm that your set up is fine and there are no issues there.

Error Handling

We try to check every FTP command used for a return code and then throw an error if the call was unsuccessful. Have not, to this point, done extensive testing on failure scenarios where some commands succeed and then others fail in the middle.

Note that you may see something like "Error getting file size!" This is because the code tries to detect remote directories by getting the file size. For directories this fails for the systems tested so far. A more complex solution would seem to be to take the detailed file listing (using ftp::List) and determine what kind of system it is, use a parser for that type, and detect if it is a directory.