Upload a file to an FTP site
FTPupload [-ftps] [-p] [-v] [-rel] [-h] localpath ftpspec [.ext]
FTPupload -sftp [-h] [-v[=key]] localpath ftpspec [.ext]
The FTPUPLOAD program can be used to upload a file to an FTP site. It is intended for use in post-processing where it may be necessary to upload files for further processing or for a remote viewing application. The localfile parameter must be a full pathname, optionally with wildcards (* or ?) in the filename part. If the path name contains white space, it must be enclosed in double-quotes.
Command-line Switches
The sequence of the three command-line options on the command line is not significant.
| -ftps | uses implicit SSL mode, normally on port 990. |
| -sftp | uses SFTP protocol with optional verification of a server fingerprint key if provided. |
| -p | this parameter forces passive mode FTP. Before using this mode, you must ensure it is supported by the FTP server. If you use active mode, you may need to configure your own firewall to allow the FTP server to select the data port. Setting an environment variable FTPUPLOAD_METHOD to either PASSIVE or ACTIVE is an alternative to the command-line option and overrides it if different. |
| -rel | this parameter causes the folder name immediately following the first single / to be taken as a relative folder name - relative to the folder set automatically by the server on login. Without this option the folder is taken as a root folder of the FTP site. Setting an environment variable FTPUPLOAD_FOLDER to either RELATIVE or ROOT is an alternative to the command-line option and overrides it if different. |
| -h | hides the status window. |
| -v | indicates that an FTPS server certificate is to be accepted without verification, or that an SFTP fingerprint is to be accepted without verification. For SFTP, the received fingerprint will be reported in FFTRACE output for FTPUPLOAD, if enabled, and this can then be entered on a -v=key command-line switch to verify the server, if required. |
-v=key The SMTP verification key in this parameter specifies the fingerprint string (typically xx:12:yy:....) which will be used to verify the server. This value should be provided if you required verification, in the server configuration parameters.
FTP Server specification
The ftpspec parameter (enclosed in double-quotes if it contains white space) takes the form:
ftp://[user:pwd]@ftpsite[:port]/[folder/][filename]
It comprises a number of required and optional components in the following sequence:
| filetype | the prefix ftp:// is required (for all protocol choices). |
| login | A login name and password, separated by a colon (:) and followed by an at sign (@) is required. The password may also contain an @, which is sometimes the case with anonymous login. |
| ftpsite | The host name or IP address of the FTP server is required. |
| port | An optional command port number may be given, preceded by a colon (:). The default port number is 21 for FTP, 990 for FTPS, and 22 for SFTP. |
| path | A path is required. To save in the root of the FTP site, use a single forward slash (/). The path must use forward slash characters, not backslash, and should always end in a forward slash. Note that the path name may be case-sensitive at some FTP servers. |
| filename | An optional filename may be added, following the forward slash at the end of the folder. If omitted, the filename of the source file is used. The filename must be omitted if the localfile contains wildcard characters. |
The optional .ext parameter contains a file extension (with leading .) which will be used to rename the local file if the transfer is successful. This can be used to prevent a second transfer if the upload is re-run with the same local file specification.
The program does not terminate until the transfer is complete. A status window is displayed during operation unless the -h command-line switch is used. If the transfer fails, a non-zero errorlevel is returned, which may be tested in a batch file. The error can be viewed (briefly) in the status window, or can be recorded by capturing FTPUPLOAD output using FFTRACE.
Login through a proxy is not currently supported. All uploads are done in binary mode.
Examples:
Upload file myfile.zip to ftp.copia.com, creating a file of the same name in folder UPLOAD (note the final forward slash character), and using anonymous login with a password of an e-mail address:
FTPupload myfile.zip ftp://anonymous:tim@copia.com@ftp.copia.com/UPLOAD/
Upload file myfile.zip to ftp.copia.com in passive mode, creating a file named myupload.zip in folder UPLOAD, and using a specific login (tim) and password (xyzzy):
FTPupload -p myfile.zip ftp://tim:xyzzy@ftp.copia.com/UPLOAD/myupload.zip
See also this example of using $run to initiate an FTPUPLOAD of a received file from an infobox script.
