How to use FTP scripting

When using FTP, it can sometimes be extremely useful to be able to script FTP commands. Scripts can be easily written and tested, and can even be dynamically generated and executed.

edtFTPj/PROis a powerful Java FTP library that supports FTP, FTPS (FTP over SSL) and SFTP (FTP over SSH). It is aimed at developers who wish to embed FTP capabilities (particularly secure FTP) into their applications. A fully functional trial edition can be downloaded from here.

edtFTPj/PRO includes an extensive FTP scripting engine that allows users to list FTP commands in a text file, and then execute all the commands sequentially. The script can be be run via a batch file (or Unix shell script), or the ScriptEngine class can be used within an application to run a script.

The script engine supports the FTP, FTPS (both implicit and explicit) and SFTP protocols. A sample script is shown below, that starts off using FTP, and then uses the auth command to change to FTPS.

Example script

# Sample FTP script using FTP initially
# then changing to FTPS
#
set remotehost=edtmobile
set port=21
set user=javaftp
set password=javaftp
set connectmode=passive
set timeout=30
set protocol=ftp
set localdir=D:\work\tmp

# logging off = 0, highest level = 5
set loglevel=5
set logfile=D:\work\ftp-ssl\tmp\script.log

# connect to the server
# optional remotehost and port supplied
# override the params set earlier
open edtmobile 21
cd remote/test

# change to secure mode
auth tls

# force binary mode transfers
binary

# put the local file test.jar to the server as mytest.jar
put test.jar mytest.jar

# rename it
rename mytest.jar test2.jar

# and get it back as test3.jar in the local working directory
get test2.jar test3.jar

# delete all *.jar files in the current directory on
# the server
mdelete *.jar

# disconnect
close


Running a script

To run the above script, assuming it is saved in a file called script.txt, simply supply it as the first argument to the ScriptEngine class:

java -classpath %CP% com.enterprisedt.net.ftp.script.ScriptEngine script.txt

(where %CP% contains edtftpjpro.jar and license.jar).

Note that the ScriptEngine class, when executed as above, can also take an additional two parameters, the username and password. This means these values do not need to be specified in the script itself.

Command overview

Most commands are fairly self explanatory.

The set command is used to set various parameters that are used during the session, such as username, password, timeout and so on. Many of these parameters are optional (e.g. port, timeout). The most important parameter is the protocol.

The local working directory is by default the standard Java working directory for the application, but the set localdir command can be used to set a different local working directory. All uploads and downloads that do not specify a full path will use the set local working directory.

Command reference

The scripting commands are described in the table below. Abbreviations for commands are noted in the command description.

Where the command has optional arguments, they are shown in square brackets, e.g. open [host] [port] means that for the open command, the host and port are optional parameters.
Command
Description


set
Sets various parameters used during the session, many of which are optional. Syntax is set name=value


set protocol
Set the protocol to be used. Supported protocols are shown below:
Protocol
Description
ftp "Plain" FTP protocol
ftps FTPS, i.e. FTP over SSL (explicit mode)
ftpse FTPS, i.e. FTP over SSL (explicit mode)
ftpsi FTPS, i.e. FTP over SSL (implicit mode). 
sftp SFTP, i.e. FTP over SSH

Note that server validation is not yet supported for any secure protocol, and the only form of client validation supported is username/password. Future versions will support client and server validation.

set connectmode
Sets the connection mode for data transfers and listings. Not applicable for SFTP protocol. Possible values are active or passive., e.g. set connectmode=active.

set remotehost
Sets the remote host to be connected to, e.g. set remotehost=ftp.gnu.org

set user
Sets the username, e.g. set user=javaftp

set password
Sets the user's password, e.g. set password=javaftp

set timeout
Optional. Sets the timeout in seconds for read or write operations (and for the initial connection attempt for JRE 1.4 and greater). The default is 0 (which is an infinite timeout). e.g. set timeout=10

set port
Optional. Defaults are determined by the protocol. Sets the port number to connect to, e.g. set port=21

set loglevel
Optional. Sets the logging level. 0 means no logging, while 5 is the maximum log level (the default). e.g. set loglevel=4

set logfile
Sets the name or full path of the logfile to direct logging to, e.g. set logfile=C:\temp\ftp.log

set tlsdebug
Sets the level of SSL/TLS debugging. Different levels display different portions of TLS debugging information. The possible levels are 0,1,2,4,8,16,32,64,256,65535. Use 65535 to get all possible debugging output for SSL/TLS processing (warning - there is a lot).

set cryptodebug
Sets debugging of cryptographic code on or off, e.g. set cryptodebug=true


open [host] [port]
Opens the connection to the remote server. The user and password must already be set via the set command. If the remote host is not already set, it must be supplied here (and will override any previous setting for this connection). The port number can also be optionally supplied. e.g. open edtmobile 21


binary
Change the current transfer mode to binary mode. Binary is the default.

Can use bin as an abbreviation.



ascii
Change the current transfer mode to ASCII mode. Binary is the default.

Can use asc as an abbreviation. 

cd remotedir
Change the current remote working directory to remotedir.

mkdir remotedir
Create the remotedir directory.

rmdir remotedir
Delete the remotedir directory. It must be empty.



get remotefile [localfile]
Download a remotefile to the local host.  The localfile parameter can be a filename or the full path of a local file. If it is a filename, the current local working directory is prepended.

Note that the localfile parameter is optional - if not supplied, the downloaded file is saved in the current local working directory with the name of remotefile.

The remotefile parameter can be a filename or a path. Not all servers support the use of a path - in this case navigate to the correct remote directory using cd.


put localfile [remotefile]
Upload a local file to the remote host. The localfile parameter can be a filename or the full path of a local file. If it is a filename, the current local working directory is prepended.

The remotefile parameter should be a filename or a path. Not all servers support the use of a path - in this case navigate to the correct remote directory using cd.

If the remotefile parameter is not supplied, the local file name will be used.



append localfile [remotefile]
Append the contents of a local file to a remote file (if it exists) on the remote host. The localfile parameter can be a filename or the full path of a local file. If it is a filename, the current local working directory is prepended.

The remotefile parameter should be a filename or a path. Not all servers support the use of a path - in this case navigate to the correct remote directory using cd.

If the remotefile parameter is not supplied, the local file name will be used.


rename remotefile1 remotefile2
Rename a remote file from remotefile1 to remotefile2.  Note that both parameters should be filenames, not full paths.

Can use ren as an abbreviation. 

delete remotefile
Delete a remote file in the current remote working directory.

Can use del as an abbreviation.


mdelete wildcard
Delete multiple remote files that match the wildcard in the current remote working directory.

Wildcards supported are '?' for a single matching character, and '*' for multiple matching characters. e.g. to delete all text files in the current remote directory, use mdel *.txt

Can use mdel as an abbreviation.


mput wildcard
Upload multiple local files that match the wildcard in the current local working directory to the current remote working directory.

Wildcards supported are '?' for a single matching character, and '*' for multiple matching characters. e.g. to upload all text files from the current local working directory, use mput *.txt

mget wildcard
Download multiple local files that match the wildcard in the current remote working directory to the current local working directory.

Wildcards supported are '?' for a single matching character, and '*' for multiple matching characters. e.g. to download all text files from the current remote working directory use mget *.txt

close
Closes the connection to the remote server.

Can also use bye, quit or disconnect.



auth
Change from unencrypted 'plain' FTP into secure FTP.

Supported options are ssl, tls, or tls-c. e.g. auth tls


protect
Change the protection level of the data channel.

Supported options are clear (setting data channels to unencrypted) and private (setting data channels to encrypted). e.g. protect clear

Alternatively private has the same effect as protect private, and clear has the same effect as protect clear.


private
Change the protection level of the data channel to private. Identical to protect private.


clear
Change the protection level of the data channel to clear. Identical to protect clear.


ccc
Clears the control channel, setting it back to plain unencrypted text. This can be useful when using firewalls, which need to be able to inspect the control channel to open data channel ports.

Once ccc has been called, no more protect commands can be used. This is a security measure inherent in the protocol.