- Parameters
- Session
- Logging
- Console/scripting mode
- Operations
- Configuration
- Mass-modification of sites
- Private key conversion and modification
- Auxiliary
- Syntax
- Executables
- Hint
- Running from Bash
Advertisement
Parameters
Parameters for winscp.exe
executable:
winscp.exe site|workspace|folder winscp.exe <session_url>[/path/[file]] winscp.exe [mysession] [/sessionname=<name>] winscp.exe [mysession] [/newinstance] winscp.exe [mysession] /edit <path> winscp.exe [mysession] /browse[=<file>] winscp.exe [mysession] /synchronize [local_directory] [remote_directory] [/defaults[=secs]] winscp.exe [mysession] /keepuptodate [local_directory] [remote_directory] [/defaults[=secs]] winscp.exe [mysession] /refresh [path] winscp.exe [mysession] /upload file1 file2 file3 ... [/defaults[=secs]] winscp.exe [mysession] [/privatekey=<file> [/passphrase=<passphrase>]] winscp.exe [mysession] [/hostkey=<fingerprint>] winscp.exe [mysession] [/username=<user>] [/password=<pass>] winscp.exe [mysession] [/clientcert=<file> [/passphrase=<passphrase>]] winscp.exe [mysession] [/certificate=<fingerprint>] winscp.exe [mysession] [/passive[=on|off]] [/implicit|explicit] winscp.exe [mysession] [/timeout=<sec>] winscp.exe [mysession] [/rawsettings setting1=value1 setting2=value2 ...] winscp.exe [/console] [/script=<script_file>] [/command command1 command2 ...] [/parameter // param1 ...] winscp.exe [/log=<logfile> [/loglevel=<level>] [/logsize=[<count>*]<size>]] [/xmllog=<logfile> [/xmlgroups]] winscp.exe [/ini=<inifile>] winscp.exe [/rawconfig config1=value1 config2=value2 ...] winscp.exe [/rawtransfersettings setting1=value1 setting2=value2 ...] winscp.exe /batchsettings <site_mask> setting1=value1 setting2=value2 ... winscp.exe /keygen keyfile [/output=<file>] [/changepassphrase] [/comment=<text>] winscp.exe /update winscp.exe /info winscp.exe /help
Advertisement
Parameters for winscp.com
executable:
winscp.com [/script=script_file] [/command command1 command2 ...] [/parameter // param1 ...] winscp.com [/stdout[=binary|chunked]] [/stdin] winscp.com [/log=<logfile> [/loglevel=<level>] [/logsize=[<count>*]<size>]] [/xmllog=<logfile> [/xmlgroups]] [/nointeractiveinput] winscp.com [/ini=<inifile>] winscp.com [/rawconfig config1=value1 config2=value2 ...] winscp.com /batchsettings <site_mask> setting1=value1 setting2=value2 ... winscp.com /keygen keyfile [/output=<file>] [/changepassphrase] [/comment=<text>] winscp.com /info winscp.com /help
Session
The first syntax opens the site. To open site, stored in folder, use path syntax “folder/site”. You can also open workspace or all sites in site folder.
The second creates the session specified by session URL and optionally by initial remote path. If the remote path is not ended by slash (/
), it is treated as path to file (or even directory) that should be downloaded.
The parameter /sessionname
specifies a custom name of the session to be used instead of the automatically generated name in a format username@hostname
or to override the name of the saved site.
If there’s already idle WinSCP instance running, the session(s) opens in the existing instance. To force session open in new instance of WinSCP, use /newinstance
parameter.
The parameter /privatekey
specifies a local path to an SSH private key file. If the key file is encrypted, use the /passphrase
to specify its passphrase.
The parameter /hostkey
specifies the fingerprint of the expected SSH host key (or several alternative fingerprints separated by a semicolon). It makes WinSCP automatically accept the host key with the fingerprint.
You can use the parameters /username
and /password
as an alternative way to specify the credentials. The credentials are normally part of the session URL. Using these switches has the advantage of not needing to URL-encode special characters.
The parameter /clientcert
specifies a local path to FTPS or WebDAVS TLS/SSL client certificate. If the certificate is encrypted, use the /passphrase
to specify its passphrase.
When a FTPS or WebDAVS server TLS/SSL certificate is not trusted (typically a self-signed certificate), use the parameter /certificate
to specify the fingerprint of the untrusted certificate. It makes WinSCP trust the certificate. Several alternative fingerprints can be separated by a semicolon.
The parameter /passive
enables a passive (=on
) or an active (=off
) transfer mode (FTP protocol only).
The parameters /implicit
, and /explicit
enable respective method of invoking FTPS.
The parameter /timeout
specifies server response timeout.
The parameter /rawsettings
allows configuring any site settings using raw format as in an INI file. E.g. to enable an SSH compression and an agent forwarding, use /rawsettings Compression=1 AgentFwd=1
. The parameter must come after the session URL (if any).
Advertisement
When using scripting, use the open
command (and its switches) instead.
Examples:
winscp.exe "My site" winscp.exe sftp://martin:password@example.com/ /hostkey="ssh-rsa 2048 xxxxxxxxxxx..." winscp.exe scp://test@example.com:2222/ /privatekey=mykey.ppk winscp.exe ftps://martin:password@example.com/
Logging
With /log
parameter you may turn on session logging to file specified by local path. In the path you can use the same patterns as in the logging preferences.
Use parameter /loglevel
to change logging level. The value can be in range -1
…2
(for Reduced, Normal, Debug 1 and Debug 2 logging levels respectively). Append additional *
to enable password logging (e.g. /loglevel=2*
).1
Use parameter /logsize
to configure log file size limit and log file rotation. Specify maximum size in bytes, optionally with K
, M
or G
units. Optionally you can limit number of archived log files using count*
prefix. For example /logsize=5*10M
will limit log file size to 10 MB and will allow up to 5 archived logs.
winscp.exe sftp://martin@example.com/ /log="C:winscp.log" /loglevel=0
With /xmllog
parameter you may turn on XML logging to file specified by local path.2 In the path you can use the same patterns as in the logging preferences.
Use parameter /xmlgroups
along with /xmllog
, to group all XML log elements belonging to the same command under parent group
element.
Console/scripting mode
Parameter /console
executes WinSCP in console (scripting) mode. Note that when using winscp.com
, the console mode is implicit, so using /console
parameter is redundant.
To run batch script either pass script file using /script
parameter or specify the commands directly on command line using /command
. In the latter case each following parameter is treated as single command. See syntax section and examples below for details how to deal with spaces and double-quotes.
If both /script
and /command
parameters are used, commands from script file are executed first. When the last command is not exit
, regular non-batch mode follows.
Use parameter /parameter
to specify list of arguments to be passed to script. It is recommended to escape the arguments with //
switch.
With winscp.exe
, if /console
parameter is not used along with /script
or /command
, the script/command is executed without visual feedback (window).
Use the parameter /stdout
to enable streaming files to the standard output of winscp.com
. When the parameter is used, the get
command will stream the downloaded file(s) to the standard output, when -
is used as a download target. By default (or with the binary
flag), the files are streamed unmodified. With the chunked
flag, the files are individually encoded using Chunked transfer encoding, what allows separating contents of multiple streamed files. When the parameter is used, all console output that would normally be printed to the standard output is redirected to the error output. Streaming is supported with the SFTP and FTP protocols only.
Advertisement
Use the parameter /stdin
to enable streaming files from the standard input of winscp.com
. When the parameter is used, the put
command will stream the standard input to the remote server, when -
is used as an upload source. Implies /nointeractiveinput
. Streaming is supported with the SFTP and FTP protocols only.
Use parameter /nointeractiveinput
, when feeding commands to winscp.com
using standard input, to make sure prompts for anything other than commands (such as password prompts) are cancelled. Also prevents error message popping up when fatal error occurs while starting WinSCP. When combined with /xmllog
the fatal error is recorded in the XML log.
Examples:
winscp.com /script="C:UsersmartinDocumentsmyscript.txt" winscp.com /command "open sftp://martin@example.com/ -hostkey=""ssh-rsa 2048 xxxx...""" "exit" winscp.exe /console /script="myscript.txt" /log="myscript.log"
You can have WinSCP generate a scripting command-line for you.
Operations
The following parameters can be used to create a shortcut that initiates operation in GUI mode. They are not intended for automation, for that see scripting.
Use /edit
to open a remote file in WinSCP internal editor.
Use /browse
to select the specified file in (both) file panel(s). The switch can also be used together with a file URL for the same effect, overriding the default download action.
With /synchronize
or /keepuptodate
parameter WinSCP performs Synchronize or Keep remote directory up to date commands respectively on the specified session and directories. A dialog to set options is displayed first.
With /upload
parameter WinSCP uploads specified files to initial remote directory of session.3 A dialog to set options is displayed first.
Use /defaults
parameter along with /upload
, /synchronize
or /keepuptodate
to skip the settings dialog and start the operation straight away with default settings. Alternatively you can specify a number of seconds, to actually show the settings dialogs, but have them automatically submit after the specified time elapses.
Use the /refresh
parameter to reload remote panel of all running instances of WinSCP. If a session is specified on command-line, only instances that have that session as active are refreshed. If a path is specified after the /refresh
, only that directory is refreshed.
It is recommended to escape the arguments with // switch.
Example:
winscp.exe /defaults /synchronize // "C:UsersmartinDocumentsMySite" /home/martin/public_html
Configuration
With /ini
parameter you may specify local path to configuration INI file. It effectively disables using registry as configuration storage. If the file does not exist, default configuration will be used and the file will be created.
winscp.exe /ini="C:UsersmartinDocumentsmyconfig.ini"
Advertisement
Use nul
instead of path to force WinSCP start with its default configuration and not save the configuration on exit.
With /rawconfig
parameter you can set any configuration settings using raw format as in an INI file. E.g. to configure an external IP address use /rawconfig InterfaceExternalIpAddress=198.51.100.10
. The parameter must come after a session URL (if any). The configuration set this way is preserved.
With /rawtransfersettings
you can set any transfer settings using raw format as in an INI file. E.g. to enable preserving of directory timestamps, use /rawtransfersettings PreserveTimeDirs=1
. The configuration set this way is preserved. In scripting, it is better to use -rawtransfersettings
switch of individual scripting commands, like get
, put
, etc.
Mass-modification of sites
Use /batchsettings
to mass-modify stored sites. The first argument is a mask to select sites to modify. Use a syntax of basic file masks. You can also use path mask to select sites based on their folders. The other arguments define new values for site settings. Use the same syntax as for /rawsettings
.
For example to configure a proxy for all sites in a “clients” folder, use:
winscp.exe /batchsettings clients/* ProxyMethod=3 ProxyHost=proxy
Private key conversion and modification
Use the /keygen
switch to convert private keys from other formats to a PuTTY .ppk
format or to change their passphrase or comment.
A parameter after the /keygen
switch specifies a path to an input private key file. The input key can be in OpenSSH or ssh.com format (when converting the key to the PuTTY format) or in the PuTTY format (when changing a key passphrase or comment).
When converting the key from other format, you need to specify an output key path using the /output
switch. When modifying a PuTTY key, the existing file is overwritten, if /output
is not specified.
Use /changepassphrase
switch to change the key passphrase.
Use /comment
switch to change the key comment.
For example, to convert key mykey.pem
from OpenSSH format to mykey.ppk
in PuTTY format and set its comment:
winscp.com /keygen mykey.pem /output=mykey.ppk /comment="Converted from OpenSSH format"
To change the passphrase of existing mykey.ppk
:
winscp.com /keygen mykey.ppk /changepassphrase
For a compatibility with *nix puttygen
, the -o
, -P
and -C
switches are understood as aliases to /output
, /changepassphrase
and /comment
respectively. So, for features supported by WinSCP, you can use the same arguments as for puttygen
, just prefixed with /keygen
:
winscp.com /keygen mykey.pem -o mykey.ppk -C "Converted from OpenSSH format"
Advertisement
Auxiliary
When run with /update
parameter, WinSCP only checks for its updates.
The parameter /info
lists the supported SSH and TLS/SSL algorithms.
Parameter /help
shows usage (overview similar to this).
Syntax
Command-line parameters that include space(s) must be surrounded by double-quotes:
winscp.exe /ini="C:UsersmartinDocumentsmyconfig.ini"
To use the double-quote as a literal, use two double-quotes sequentially. For example, the /command
expects that each script command is surrounded by double quotes, so that it is passed as a single command-line argument. In addition, any script command argument that includes spaces is expected to be surrounded by double-quotes within the command (see doubling double-quotes):
winscp.com /command "open sftp://... -hostkey=""ssh-rsa ...""" "put ""C:my file.dat""" <- Script command 1 -> <- Script command 2 ->
When executing such command from PowerShell, you additionally have to escape the doubled inner double-quotes with `
(backtick) to prevent PowerShell from interpreting them on its own:4
winscp.com /command "open sftp://... -hostkey=`"`"ssh-rsa ...`"`"" "put `"`"C:my file.dat`"`"" <- Script command 1 -> <- Script command 2 ->
To debug the quoting, enable session logging on level Debug 1 (/loglevel=1
). The log will show how WinSCP understands your command-line.
An argument that begins with a slash is considered a switch. To pass a parameter that itself starts with the slash in its syntax (i.e. a remote path like /root
), use the special switch //
(two slashes) before the argument. The switch //
denotes that all following arguments are not switches. Example:
winscp.exe /synchronize // "C:UsersmartinDocumentsMySite" /root
Executables
Learn about two WinSCP executables, winscp.exe
and winscp.com
.
Hint
If you are going to run WinSCP from command-line often, you may wish to add WinSCP installation directory to search path.
Running from Bash
When running WinSCP from a shell, where /switch
is interpreted as a path, such as Git Bash, use a dash (-
) instead of the slash (/
) for switches. For example:
./WinSCP.com -script="myscript.txt" -log="myscript.log"
Advertisement
Overview
MOVEit Freely (a.k.a. «ftps.exe») is a secure command-line
FTP client for Windows.
It accepts syntax similar to Microsoft’s built-in «ftp.exe» FTP client to make migrations to secure FTP easy.
Designed with professional system administrators in mind, MOVEit Freely duplicates
Microsoft client syntax from commands to error messages. In addition to embracing
Microsoft FTP, MOVEit Freely extends the functionality of
command-line FTP with the addition of secure channel communication, passive mode
transfers and resumption of transfers.
MOVEit Freely runs on Microsoft Windows 10 (32-bit and 64-bit), Windows 8.1 (32-bit and 64-bit), Windows 8 (32-bit and 64-bit), or Windows 7 (32-bit and 64-bit) and can take the place
of the Microsoft command-line FTP client in all scripts. Simply replace
«ftp» in your existing scripts with «ftps».
MOVEit Freely also implements a «file integrity» mode. This is a transfer mode that
compresses files on-the-fly, and checks a file checksum to ensure that the file
was transferred successfully. This mode is selected automatically when
transferring to/from a MOVEit Transfer FTP server; it is not available with other types
of servers.
MOVEit Freely features:
- FTP and FTP/S (FTP over SSL) file transfers
- Explicit (RFC-conforming) and implicit FTP/S connection modes
- Active and passive file transfer modes
- Client certificate support
- Ability to halt script execution on first error
- Client-side NAT support for legacy FTP servers
- On-the-fly data transmission compression to conserve bandwidth and speed transfers (where available)
- Resuming of partial transfers (where available)
- Cryptographic-quality file integrity checks to guard against truncation or corruption during transit (MOVEit Transfer transfers only)
- USB-Friendly «Portable» deployment
Like other command-line utilities,
MOVEit Freely can be driven by an automated script
such as a Windows batch file.
In turn, these scripts can be scheduled by Windows Scheduled Tasks.
- Need MISSION-CRITICAL automation?
- Need your own secure file transfer server?
Table of Contents
- Overview
- Requirements
- Installation
- Command Line
- Commands
- Examples
- FTP Protocol 101
- Client NAT
- Basic Troubleshooting
- Distribution
- License
- Contacting the Vendor
- Other MOVEit Products
Requirements
MOVEit Freely is a standalone executable that does not require any other software,
assuming the operating system is Microsoft Windows 10 (32-bit and 64-bit), Windows 8.1 (32-bit and 64-bit), Windows 8 (32-bit and 64-bit), or Windows 7 (32-bit and 64-bit).
Installation
To install MOVEit Freely, run the MOVEit Freely installation package. This package will ask into which folder and which «Start menu» program group you would like to install the application. It will change your «PATH» variable to allow you to run MOVEit Freely from any command prompt. (You may be prompted to log off after the installation to allow this to occur.) The installation will also install a «Start Menu» link to this documentation.
If Windows Firewall is running—which is the default under Windows Vista and Windows Server 2008—then
«active mode» FTP transfers will be blocked until you create an «exception»
for MOVEit Freely in the firewall.
(This is the case with any FTP client.)
To create an exception, use Control Panel | Windows Firewall | Allow a program through Windows Firewall.
Command Line
MOVEit Freely must be executed from a shell («command prompt»).
MOVEit Freely is a 32-bit program, not a
«legacy» DOS program.
(If you plan on using MOVEit Freely with MOVEit Transfer servers only,
Ipswitch also provides, at no cost, a similar command-line client called «MOVEit Xfer»
that securely transfers files over firewall/proxy-friendly HTTPS instead of FTPS.)
Use the following command syntax to run MOVEit Freely:
FTPS [-e:sslmode] [args] [hostname [port]]
…where args is zero or more of:
- -a starts the program in passive
mode. By default, the program is in active mode. This
can be changed during a session with the passive command. -c:connect_timeout_secs
to set the connect
timeout in seconds. This is the amount of time that the program will
wait for a successful connection to the server. The default is 30
seconds.- -csn:store to set the name of an alternate Microsoft Certificate Store
from which an optional SSL client certificate (with private key) will be selected.
. This defaults to «MY» (a.k.a. «Personal»), which is the name
Windows stores certificates for the
currently-logged-in user. This option is very rarely used, because
when client certificates are used, they are usually in the default location. - -ccn:common_name to specify the Common Name (CN)
of an optional SSL client certificate; for example, «Thawte Freemail
Member». This must be specified in order to enable client
certificates, and the named certificate must already be present in the current user’s
Windows Certificate Store. (This is typically configured via Internet Explorer’s Tools
/ Internet Options / Content / Certificates.) The default is to
not support client certificates. Use this option only if
the remote FTP server requires client certificates.
Because Common Names usually contain spaces, you will usually need to use
double quotes: «-ccn:Thawte Freemail Member».
Some SSL hardware tokens, such as Aladdin’s eToken, may also be used with MOVEit Freely
to provide credentials, provided that the SSL hardware certificate store is accessible
through the Windows certificate store interface.
See also the -pfxfile:filename
option. - -d to display commands sent to the server. Passwords, however, are still masked when this mode is in use.
- -e:sslmode to select the SSL encryption
mode. sslmode must be one of:sslmode Meaning off
no SSL encryption (default) tls-p
oron
encrypts both control and data with the AUTH TLS and
PROT P commands. («explicit»)on-ccc
the same as «on», except that after signon,
the CCC command is sent to switch the control connection to
unencrypted mode. Data connections will be
encrypted. With this option, the username and password are
encrypted, but other FTP commands are in cleartext.This option is used when a firewall between the client and the
server is using Network Address Translation to change the client’s
view of the FTP server’s IP address. This option the
firewall to inspect and rewrite PORT commands and PASV responses, to
account for this IP address mapping. Without this feature, if
you are using encrypted sessions with certain firewalls, you might
have to use the -natpasv or -natact:ip command-line options
instead.The «on-ccc» option is not frequently used, because many
FTP servers do not support the CCC command.tls-c
encrypts only the control connection with the AUTH TLS command. Encryption of the data connection can be changed during
the session with the prot command.prot p sets data connections to be protected (encrypted);
prot c sets data connections to be cleartext (unencrypted).tls-c-ccc
like «tls-c», except that after signon,
the CCC command is sent to switch the control connection to
unencrypted mode. Data connections will not be
encrypted. See the above discussion of «on-ccc».implicit
encrypts both connections without the use of an AUTH
command; usually to port 990.implicit-ccc
the same as «implicit», except that after
signon,
the CCC command is sent to switch the control connection to
unencrypted mode. Data connections will be
encrypted. See the above discussion of «on-ccc». - -n to not prompt for username and password at startup.
- -natact:ip to use ip as our IP address in «Client NAT» mode
in active (as opposed to passive) FTP mode. See Client
NAT. - -natpasv to ignore the IP address in the PASV reply in «Client NAT» mode
when in passive FTP mode. Instead, use the address of the control
connection. See Client NAT. - -password:pw is the default password.
If this is not specified, the program will prompt for a password upon
initial connect. - -pfxfile:filename specifies a file from
which a client certificate is to be read. The first private
certificate in the file will be used. This is an alternative to the -ccn
parameter, for when the client certificate is not installed in a Windows
store. The filename must be in .PFX format (also known as .P12
format). If the file is protected by a password, use the -pfxpw
parameter. - -pfxpw:password specifies the password to be
used with -pfxfile. See also -pfxpwfile. - -pfxpwfile:filename specifies the name of a
file that contains the password to the file given by -pfxfile.
Do not use both -pfxpw and -pfxpwfile. - -ports:low-high specifies the port
range to use on the client side of TCP data connections. For example,
you might specify -ports:8000-8009. MOVEit Freely will restrict
the port numbers it uses to be greater than or equal to low, and less
than or equal to high. For active mode, this restricts the port
numbers sent by the PORT command. For passive mode, this controls the
port number of the originating end of the connection. This very rarely
used option exists to accommodate highly restrictive firewall rules.
Without this option, MOVEit Freely will allow the operating system to choose
port numbers. - -quiterror to quit on any error.
This will exit a script file without reading any more commands. - -resume to attempt to resume transfers if the destination
files exist. - -s:filename to read commands from a script file (do
not use redirection). The default is to read commands from the console. - -t:data_timeout_secs to set the data socket
timeout in
seconds. This applies to both the amount of time to wait for the
server to connect back (on a non-passive data port), and the amount of time to wait
without data before declaring a data socket dead. The default is 120 seconds. - -user:username is the default
username. If this is not specified, the program will prompt for a
username upon initial connect. - -z to not warn about problems with FTP server
certificates, instead accepting any certificate. By default, if there is a problem
with a certificate, MOVEit Freely will display a dialog, asking whether you want to accept
the certificate. The most common problem is that a certificate was issued by a
non-trusted certification authority, as happens with test certificates.
hostname is the domain name or numeric IP address of an FTP server.
port is the numeric TCP port number to use. The default is 21,
unless -e:implicit has been specified, in which case the default is 990.
If no hostname is given on the command line, MOVEit Freely starts without making a
connection. In this case, you must issue an open command to connect to an FTP
server.
Here are some examples of this syntax in use:
- FTPS ftp.ipswitch.com
(Open an INSECURE, INTERACTIVE connection to «ftp.ipswitch.com») - FTPS -e:on ftps.ipswitch.com
(Open a SECURE, INTERACTIVE connection to «ftps.ipswitch.com») - FTPS -e:on -s:mybatch.txt ftps.ipswitch.com
(Open a SECURE, BATCH connection to «ftps.ipswitch.com»)
Compatibility with MOVEit Xfer and Microsoft’s «ftp.exe» Client
MOVEit Xfer is a free, command-line application also written and distributed by Ipswitch
to communicate with MOVEit Transfer servers using the firewall-friendly HTTPS protocol.
(MOVEit Freely communicates with MOVEit Transfer server using the FTPS protocol.)
The command-line syntax for MOVEit Xfer was based on existing MOVEit Freely command-line syntax.
This uniformity allows people to convert most MOVEit Freely scripts to MOVEit Xfer scripts
simply by replacing «ftps» with «xfer».
MOVEit Freely command-line syntax was itself based on the command-line syntax of the Microsoft non-secure ftp.exe client.
This uniformity allows people to convert many scripts based on «ftp.exe» to MOVEit Freely scripts
simply by replacing «ftp» with «ftps».
Program Exit Values
MOVEit Freely will return an exit value of zero (0) if no errors occurred during the
processing of a file transfer session. See the example below for a batch file that checks
the return code for errors. Several different exit codes are returned by MOVEit Freely.
- 1 is returned for syntax errors in the command line parameters.
2 is returned if the -s: parameter points to a file or directory that does not exist.
3 is returned if any command during the session caused an error, either a
4xx or 5xx response from the server or a syntax or file error detected by MOVEit Freely itself.
13 is returned if the -s: parameter points to a file whose sharing mode does not
allow read access, or if the path is a directory, not a file.
If the -quiterror parameter is specified, MOVEit Freely will exit immediately with an
exit code of 3 as soon as an error occurs without reading any more commands from the script file
or console.
Resuming Transfers
The -resume parameter can be used to cause MOVEit Freely to attempt to resume a transfer
that may have been interrupted in a previous execution. Specifying -resume will change the
way that get and put (also mget/mput) work. Resuming transfers requires support on the
corresponding FTP server, but not all server implementations have that support. Here is
how the -resume parameter works:
When a get operation is performed,
MOVEit Freely will first check to see if there is already a local file present. If so, a
«REST xxxxx» command is sent to the server with «xxxxx» being the size in bytes of local copy
of the file. Then, when the file is transferred, the first «xxxxx» number of bytes are skipped
by the server and MOVEit Freely will write the data sent to the end of the local file.When a put operation is performs, MOVEit Freely will first send a «SIZE (filename)»
command to the server to ask for the number of bytes in the file. Next, MOVEit Freely will
send a «REST xxxxx» command is to the server with «xxxxx» being the number of bytes to skip
when the transfer takes place. The server is responsible for writing the data to the end
of the file.
It is important to note that use of the -resume parameter will cancel the ability of MOVEit
Freely to overwrite a file if it already exists. A destination file, if it exists, is assumed to be
a partially transferred version of the source file. If you often transfer different versions
of a file with the same name with overwrite, do not use -resume.
When MOVEit Freely «file integrity mode» is used with MOVEit Transfer, a partial transfer that is
completed by using the -resume parameter is verified, by checksum, that the entire destination file
matches the source file.
When using -resume for put operations with MOVEit Transfer, only files that have
been detected by MOVEit Transfer as previously incomplete transfers can be resumed. That is, a
file which was completely received by MOVEit Transfer cannot be extended using the -resume feature.
Commands
Once MOVEit Freely is started, it prompts for and reads single-line commands. The
commands are read from the console, or from the script filename if the -s
parameter has been specified on the command line. If the -quiterror parameter has been
used and an error is encountered, (either a 4xx or 5xx response from the server or a syntax
or file error detected by MOVEit Freely itself), MOVEit Freely will exit without reading
any more commands from the console or script file.
If a command that has required parameters is entered without the parameters, MOVEit
Freely will prompt for the parameters, using the same prompts as Windows 2000’s FTP.EXE.
For many commands, to enter a parameter containing spaces, you must enclose the parameter in
double quotes. For instance, to retrieve a file named My
Document.txt, you should say get «My Document.txt».
The only exceptions to this rule are the dir, lcd, ls, and quote commands, which
do not require double quotes.
Legal FTP commands are listed below. Optional parameters are enclosed in brackets
([]).
![cmd]
Executes a shell command on the local machine. If cmd is not specified, a copy of
the command interpreter is launched. You can type as many Windows commands as you
like. When you are finished, type exit to return control to MOVEit
Freely. If cmd is specified, that command is executed, then control is returned to
MOVEit Freely, with no need to type exit.
?
Displays a list of the available MOVEit Freely commands.
about
Displays a brief description of MOVEit Freely, the current version, and a link to the
vendor’s website.
append localfilename [remotefilename]
Appends a local file to an existing file on the server. If remotefilename is not specified,
the name of the file on the remote system will be the same as localfilename.
You may put » around the filenames in order to include spaces in the names.
If the remote file does not exist, many FTP servers will create a new one,
treating the command as if it were a put.
ascii
Tells the FTP server to switch to ASCII transfer mode.
bell
Toggles the flag that indicates whether to sound a bell after the completion of
certain commands. These commands are the commands that cause data to be
transferred: dir, ls, get, put, mget, mput.
binary
Tells the FTP server to switch to binary transfer mode.
cd directory
Changes the working directory on the server.
close
Closes the connection to the server without exiting the program.
debug
Toggles the flag that indicates whether commands sent to the FTP server are echoed to
the console.
delete filename
Deletes a filename on the FTP server.
dir [filemask] [outputfile]
Gets a directory listing from the FTP server. If outputfile is
specified, the output goes to that file instead of to the console.
get remotefilename [localfilename]
Retrieves a file. If localfilename is not specified, the file will be saved to
the local system as remotefilename. You may put » around the
filenames in order to include spaces in the names.
hash
Toggles the flag that says whether to print a ‘#’ for every 2048 bytes transferred.
help
Displays the list of commands accepted by MOVEit Freely.
lcd
Changes the local directory.
ls [filemask] [outputfile]
Displays a list of files on the remote system, with file names only. If
outputfile is specified, the output goes to that file instead of to the
console.
mdelete remotefilemask
Deletes multiple files from the remote system. MOVEit Freely implements this by
executing the equivalent of an «ls» command, then doing a delete for
each filename returned. If prompting is on, MOVEit Freely prompts for whether to actually
delete the
file. The responses are: «y» or just <Enter> to fetch that file,
q to quit,
or anything else to not delete the file.
mget remotefilemask
Retrieves multiple files from the remote system. MOVEit Freely implements this by
executing the equivalent of an «ls» command, then doing a get for each filename
returned. If prompting is on, MOVEit Freely prompts for whether to actually get the
file. The responses are: «y» or just <Enter> to fetch that file,
q to quit, or anything else to not transfer the file.
Examples of remotefilemask:
- *.* (Get all files — however, some remote systems omit files without
«extensions») - * (Get all files — however, some remote systems omit files with «extensions»)
- *.txt (Get all files with an extension of «txt»)
mkdir remotedirectory
Makes a directory on the remote system.
mput localfilemask
Sends multiple files to the remote system. MOVEit Freely implements this by
getting a list of local files matching the mask, then doing a put for each filename
returned. If prompting is on, MOVEit Freely prompts for whether to actually put the
file. The responses are: «y» or just <Enter> to send that file,
or anything else to not transfer the file.
open hostname [port]
Connects to an FTP server. If port is not specified, MOVEit Freely will
attempt to connect on port 21.
passive
Toggles the flag that says whether to use passive mode. In passive mode, the
remote FTP server accepts data connections from MOVEit Freely for each data
transfer. In the more traditional non-passive mode, MOVEit Freely accepts data
connections from the remote FTP server.
(Passive mode is often required by firewalls and proxy servers.)
prompt
Toggles the flag that says whether to prompt for transfers during an mget or mput.
put localfilename [remotefilename]
Sends a file to a remote FTP server. If remotefilename is not specified,
the name of the file on the remote system will be the same as localfilename.
You may put » around the filenames in order to include spaces in the names.
pwd
Displays the working directory on the FTP server.
quit
Closes the connection, if any, and exits the program.
quote remotecommand
Sends an arbitrary command to the remote system.
remotehelp
Displays a list of commands available on the remote FTP server.
rename oldfilename newfilename
Renames a file on the remote system.
rmdir directory
Removes a directory on the remote system.
status
Displays the status of various flags.
user
Prompts for username and password. Used when you are connected to an FTP server,
but not necessarily logged in.
type [ascii | binary]
Displays the current transfer type. If ascii or binary are
specified, first tells the FTP server to switch to that type.
verbose
Toggles the flag that indicates whether responses from the FTP server are displayed on
the console. There is rarely a reason to turn this mode off.
Examples
Simple Script Example
The following script and command line retrieve all files named *.rpt from the
Incoming directory of an FTP server. Passive mode is used.
The command line is:
ftps -s:GetRpt.in ftp.bigcorp.com
The contents of GetRpt.in are:
jsmith secret123 cd Incoming passive prompt mget *.rpt quit
Note that the lines in the script are simply the lines of text
that would be entered by the user if the transfer were done interactively
rather than via a script. The
«prompt» command is necessary to turn off prompting for use inside a
script.
Batch File to Upload a Single File
The following batch file lets a user upload a single file using a single command. If you save the following snippet as «uploadit.bat», usage would be: «uploadit (hostname) (username) (password) (file_to_transfer)»
echo put %4 > temp.txt echo quit >> temp.txt ftps -a -e:on -user:%2 -password:%3 -s:temp.txt %1 del temp.txt
Batch File that Checks for Errors
This batch file checks the exit code from MOVEit Freely to see if any errors occurred. The
-quiterror parameter will make the program exit as soon as there is an error without reading any more
commands from the script file.
ftps -user:dave -password:super -quiterror -s:script.txt myhost if %ERRORLEVEL%==0 goto great echo ftps returned error code: %ERRORLEVEL% if %ERRORLEVEL%==3 goto out if %ERRORLEVEL% GEQ 1 goto oops echo Unknown File Transfer Problem goto done :oops echo Error in File Transfer syntax goto done :out echo An error occurred in the File Transfer goto done :great echo The File Transfer completed successfully :done
Secure FTP Host to Insecure FTP Host
Included with this documentation is a longer script example («samplecopy.bat») which retrieves all the files from a folder on a secure FTP server and places them into a folder of an insecure FTP server.
This batch file invokes MOVEit Freely twice (once for each of the two hosts). Immediately before invoking the client, the batch file builds up a temporary command file. These command files (as well as a temporary work folder) are deleted before the batch file exits.
echo off rem * * * * * * * * * * * * * * * * * * * * * * * * * * * rem * Simple script to pick up files from MOVEit Transfer rem * (via its FTP over SSL interface) rem * and upload those file to another host via FTP rem * * * * * * * * * * * * * * * * * * * * * * * * * * * rem * rem Fill out ALL the values below rem * SET MOVEitIP=securehost1 SET MOVEitUser=username1 SET MOVEitPassword=password1 SET RemoteIP=insecurehost2 SET RemoteUser=username2 SET RemotePassword=password2 rem * rem * * * * * * * * * * * * * * * * * * * * * * * * * * * echo Copying files from %MOVEitIP% as %MOVEitUser% echo Copying files to %RemoteIP% as %RemoteUser% mkdir work echo prompt > frommoveit.txt echo lcd work >> frommoveit.txt echo mget *.* >> frommoveit.txt echo quit >> frommoveit.txt ftps -a -e:on -user:%MOVEitUser% -password:%MOVEitPassword% -s:frommoveit.txt %MOVEitIP% del frommoveit.txt echo prompt > toremote.txt echo lcd work >> toremote.txt echo mput *.* >> toremote.txt echo quit >> toremote.txt ftps -user:%RemoteUser% -password:%RemotePassword% -s:toremote.txt %RemoteIP% del toremote.txt del work*.* /Q rmdir work
Piping Directory Lists and Other Output to a File
People who write scripts around MOVEit Freely often find it useful to be able to write directory listings and other FTP output to a file.
The standard Windows executable-level pipe makes this easy.
Here is a one-line command which signs onto a secure FTP server, runs a script («myscript.txt») and pipes all output to a file («xxx.txt»).
C:>ftps -e:on -a moveit.ipswitch.com -user:myuser -password:mypass -s:myscript.txt > xxx.txt
The «myscript.txt» script file contains the following commands.
prompt cd home cd "My User Folder" pwd ls *.zip quit
The «xxx.txt» output file will contain output similar to the following.
The directory list begins after the «150» response.
Alternately, a «dir» command could be used in place of «ls» if the intent was to view a «column-view» directory listing.
220 Connected to MOVEit DMZ FTP server version 2.7.1.4 234 SSL enabled start the negotiation Connected to moveit.ipswitch.com. 331 Password required for myuser 230-This area exists to provide our clients and business partners with secure, immediate access to key resources. Anonymous access is NOT permitted - please contact Ipswitch for your complementary account 230-All time and date stamps displayed on this site are GMT -5 unless otherwise specified. 230-This server is configured to do passive mode transfers only. 230 User myuser logged in. 215 Windows_NT version 5.0 (MOVEit DMZ FTP 2.7.1.4) 200 Integrity Mode Selected ftp> Interactive mode Off . ftp> 250 CWD command successful ftp> 250 CWD command successful ftp> 257 "/home/My Home Folder" is current directory ftp> 227 Entering Passive Mode (66,170,5,143,46,224). 150 Opening ASCII mode data connection backup.zip DMZ_2751_Patch.zip DMZ_NTFS_Advice.zip DMZ_Training_26.zip flbk.zip gnugpg.zip jgl_backup.zip personalfirewall.zip upload.zip Using Local SMTP Relay.zip ftp: 190 bytes received in 0.70Seconds 0.26Kbytes/sec. 226 Transfer complete ftp> 221 Goodbye
FTP Protocol 101
Unlike most other Internet protocols FTP requires not one but TWO TCP/IP connections to
function properly. The first connection is called the «control channel»
and is initiated by an FTP client to an FTP server. (Nothing unusual so far.)
FTP commands such as «USER» and «PWD» and simple responses are sent and received across this
the control channel.
The second connection is called the «data channel». Actual file data
— including DIRECTORY LISTINGS — is sent across the data channel.
Unlike the control channel, the data channel does NOT remain connected throughout
an FTP sessions, but is only connected and available when needed.
Most FTP servers «listen» for control channel connections on TCP port 21.
(Or port 990 when FTP over SSL implicit mode is used.)
Data channels are not as predictable, however.
In «ACTIVE»
mode the CLIENT tells the SERVER which remote port to use and a data connection is
opened by the SERVER from port 20 back to the CLIENT on a random «high port».
(A «high port» is a TCP port numbered 1024-65535).
«Active Mode» FTP
In «PASSIVE»
mode the SERVER tells the CLIENT which remote port to use and a data connection is
opened by the CLIENT from a random high port back to the SERVER on a random «high port».
«Passive Mode» or «Firewall-Friendly» FTP
Over the years, firewalls became increasingly involved in site-to-site file transfers,
and most firewalls learned
enough about the FTP protocol that they could DYNAMICALLY open up high ports
for FTP data transfer without requiring addition configuration
by actually reading FTP control channels.
In other words, a firewall technician dealing with regular FTP
would typically only need
to define a single «FTP» rule on his firewall
and would not need to define
additional rules to cover the data ports.
FTP over SSL
With the introduction of FTP over SSL, however, FTP-aware firewalls lost the ability to
dynamically open data ports because the firewalls could not longer read the control
channels. This meant that firewall technicians needed to start defining ranges of ports
for FTP sessions to use. The rules required to get FTP over SSL to work properly were
often alarming to security people for good reason. For example, a basic FTP over SSL
«ACTIVE DATA PORT» rule might allow OUTBOUND connections from the FTP server to ANY high port
ANYWHERE on the Internet. A basic FTP over SSL «PASSIVE DATA PORT» rule might allow
INBOUND connections from ANYWHERE on the Internet to ANY high port on the FTP server.
Obviously, some improvements needed to be made.
At this point we can safely discard the idea of using
FTP over SSL in ACTIVE mode, however, because any FTP client which supports
FTP over SSL also supports PASSIVE mode. (FTP over SSL in ACTIVE mode also
requires a great deal of holes to be poked in CLIENT firewalls, so it is
good we do not need to deal with it.) This leaves only FTP over SSL in
PASSIVE mode to worry about.
The knock against the FTP over SSL PASSIVE data port rule defined above is that
it allows traffic from ANY Internet address to ANY high port on the FTP server. It’s easy
to begin defining rules which restrict the ANY Internet addresses to SPECIFIC Internet
addresses, but an address spoofer would still have access to ANY high port on the FTP server.
(This is also really only an option for organizations which a finite number of users and
do not have restrictions on immediately firewall changes.) However, if you have a
decent FTP server (e.g. MOVEit DMZ),
it is relatively
easy to tell the FTP server itself to confine its passive data ports to a finite range
(e.g. 15000-15020). Now, your passive data port rule can have a finite range of ports too,
and because the SERVER is in charge of port assignments during PASSIVE transfers, you
never need to do anything to your FTP CLIENTS but tell them to use PASSIVE mode. (Some CLIENT
firewalls will need this range of ports configured in them too, but it’s still less work than
dealing with ACTIVE mode over SSL.)
MOVEit Freely complies with RFC 959 (regarding the FTP protocol) and uses SSL to
encrypt both the control and data channels. (In particular, MOVEit Freely does not
implement the single channel, usually port 22 «secure FTP over SSH» mode.)
Client NAT
MOVEit Freely provides a client Network Address Translation («client
NAT») capability to help overcome problems with poorly-configured FTP
servers and firewalls. These problems can prevent you from performing
transfers over data ports, even if you can connect and login on the control
port. These problems occur in two similar circumstances:
- In active mode, the FTP server may be unable to connect to the client’s IP
address due to an intervening network firewall. - In passive mode, you may not be able to connect to the FTP server because
the address it has told the client to connect to is not reachable by the
client.
These problems are particularly likely to occur in secure mode. In
non-secure mode, many firewalls will automatically make adjustments to the PORT
and PASV transactions on-the-fly to compensate for the client and server being
on different networks. This is not possible with secure connections,
because the firewall is unable to decrypt and rewrite the transactions.
Although these problems are best addressed by reconfiguring the FTP server
and/or firewall, users of MOVEit Freely do not always have administrative access
to do so. MOVEit Freely thus provides two command-line parameters that
allow the user to work around these problems on the client end.
- The -natact:ipaddr parameter tells MOVEit Freely to tell
the FTP server, in active mode, to connect to MOVEit Freely on IP address «ipaddr»
rather than the client’s actual IP address. In order to use this
parameter, you must know an address by which the server can access your PC.
Note: You cannot use this feature with the MOVEit Transfer FTP server in
active mode, because of a security feature in MOVEit Transfer that prevents the
«hijacking» of a data port. Use passive mode instead. - The -natpasv parameter tells MOVEit Freely to ignore
the IP address specified by the FTP server when the FTP server tells Freely to
make a data connection in passive mode. Instead, when this parameter is
specified, MOVEit Freely will connect to the IP address that it used to make the
control connection.
Basic Troubleshooting
Ipswitch rarely deals with «control channel» problems
encountered through MOVEit Freely because these problems provide such
instant feedback to the user.
For example, a user who cannot connect or sign on to an FTP server will usually
contact the technician in charge of the particular FTP server rather than
the client software vendor.
The problems Ipswitch does hear about are typically «data channel» problems instead.
Specifically, these involve the inability to start a data transfer or perform a directory listing.
(Many people do not know that FTP directory listing are technically data transfers too.)
To troubleshoot these problems, be sure you are running MOVEit Freely in DEBUG mode
(so you can capture a log), try to replicate the problem and see if it is described by
one of the situations described below.
«Six Octet» PORT Syntax
Before proceeding, however, you need to know how to read «six octet» PORT syntax you will
see using many clients and servers.
227 Entering Passive Mode (192,168,3,15,15,180)
In this format, the first four octets are the IP address the remote machine is telling
the client to connect to. (i.e. «192.168.3.15») The two remaining octets describe the port
the remote machine is telling the client to connect to, but this calculation requires a
calculator. Take the fifth octet, multiply by 256 and add the sixth octet
to get the complete port number. (i.e. 15×256+180= «4020»)
Blocked ACTIVE Data Channel
In this situation, the FTP client asks the FTP server to connect to a specific
port on the FTP client, but access to that port is blocked by a client firewall
or a server firewall. Note the «PORT» command being issued by the client.
C:>ftps -z -d -t:5 -e:implicit 192.168.3.15 -user:myuser -password:mypass Connected to 192.168.3.15. ... ftp> dir ---> PORT 192,168,3,165,12,195 200 PORT command successful ---> LIST Timed out waiting for connection from server. ftp>
Solution:
- If you are using FTP over SSL, consider using PASSIVE mode transfers instead.
- If you are not using FTP over SSL, consider switching to an «FTP-aware» firewall
or use explicit firewall rules to un-block the data channel ports.
Blocked PASSIVE Data Channel
In this situation, the FTP server asks the FTP client to connect to a specific
port on the FTP server, but access to that port is blocked by a client firewall
or a server firewall. Note that there is no «PORT» command being issued by the client.
Instead, the server sends its IP address to the client.
C:>ftps -a -z -d -e:implicit 192.168.3.15 -user:myuser -password:mypass Connected to 192.168.3.15. ... ftp> dir ---> PASV 227 Entering Passive Mode (192,168,3,15,15,178). ---> LIST Unable to connect to server: The connection timed-out. timeout=5 150 Opening ASCII mode data connection
Solution:
- If you are using FTP over SSL, use explicit rules to un-block the data channel ports.
- If you have control over the FTP server, consider limiting the PASSIVE data channel
ports to a specific range to avoid a confrontation with your security team. - If you are not using FTP over SSL, consider switching to an «FTP-aware» firewall
or use explicit firewall rules to un-block the data channel ports.
Incorrect Server Address using PASSIVE mode with FTP over SSL
In this situation, the FTP server returns an IP address (usually an internal IP address)
to be used for passive data transfer which is different than the IP address to
which you connected the client. (In the example below, «192.168.3.15» != «33.44.55.66»)
This is another situation which used to be taken care
of automatically by «FTP aware» firewalls before FTP over SSL existed.
C:>ftps -a -z -d -e:implicit 192.168.3.15 -user:myuser -password:mypass
Connected to 192.168.3.15.
...
ftp> dir
---> PASV
227 Entering Passive Mode (33,44,55,66,15,178).
---> LIST
Unable to connect to server: The connection timed-out. timeout=5
150 Opening ASCII mode data connection
ftp>
Solution:
- If you have control over the FTP server, configure the correct
external NAT address on the server itself to avoid the need to deploy this fix
to all your clients. (Major commercial FTP over SSL servers, including
MOVEit DMZ, have
the built-in ability to send the correct IP address to clients in a NAT environment. - Use MOVEit Freely’s Client NAT capability.
- See Ipswitch Secure FTP v. NAT White Paper for more information.
Distribution
The standard MOVEit Freely
installation packages will automatically
set the «PATH» variable to include the folder into which MOVEit Freely was
installed. This allows users to invoke the MOVEit Freely client
from any command line prompt. Use the standard MOVEit Freely
installation packages for distribution if your clients will write their
own scripts OR are replacing existing FTP client scripts.
USB-Friendly «Portable» Deployment
«A portable app is a computer program that you can carry around with you on a
portable device and use on any Windows computer. When your USB thumbdrive,
portable hard drive, iPod or other portable device is plugged in, you have
access to your software and personal data just as you would on your own PC.
And when you unplug, none of your personal data is left behind.»
(Rare Ideas, LLC, 2005)
MOVEit Freely can be deployed/installed as a USB-Friendly «Portable» application.
Simply copy the contents of a MOVEit Freely archive file (e.g., «MOVEitFreely.zip»)
into a folder on your USB drive or other portable device.
With command line
applications, MOVEit Freely included, your personal information is
generally confined to what you have written in batch files or piped out
into log files. Please remember to keep any such batch or log files on
the portable drive too.
You may wish to add the portable directory in which you installed MOVEit Freely
to your PATH if you want to be able to invoke MOVEit Freely from any folder
without specifying a full path to the executable. If you often find yourself
running command-line applications in a portable environment, you will also
probably want to create a portable «Launch Command Line» shortcut and/or batch
file on your portable device so your favorite utilities are always available
in command-line sessions.
Custom Distribution
If you elect to roll your own distribution of MOVEit Freely, you MUST include:
- THIS DOCUMENT, AND…
- MOVEitOverview.pdf, AND…
- ftps.exe
You will probably also wish to include the supporting images required by this document,
all of which are found in the «images_MoveITFreely» folder.
You will also probably want to include any custom batch files, script input files and/or documentation
in your own distribution. Usually all these files are placed into a single «archive»
file (e.g., a «zip» file), but they may be bundled in other distributions
as permitted by the license found in this document.
Other MOVEit Products
Need MISSION-CRITICAL automation?
If you run more than 10 automated MOVEit Freely transfers or need mission-critical automated file-transfer,
please consider using MOVEit Central instead of MOVEit Freely.
MOVEit Central is a fully-automated, schedule and event driven file transfer engine.
It can move files between FTP servers, SSH servers, Windows file shares, email servers and comes with enterprise features such as remote control, task configuration/execution delegation, and automatic retry/resume of failed transfers.
(More info…)
Need your own secure file transfer server?
The first Windows-based secure file transfer server to support all three modes of FTP over SSL, the first to add SSH support, and the first one to support both protocols plus browser-based (HTTPS) transfers was MOVEit DMZ. In addition to three secure IN TRANSIT protocols, MOVEit DMZ features integrated FIPS-140-validated AT REST encryption to protect files while they are stored on the server. Request an evalution and join the banks, governments, hospitals and others who have stepped up to MOVEit secure file transfer today!
(More info…)
MOVEit Freely LICENSE
MOVEit � Freely is protected by copyright laws and international copyright treaties, as well as other intellectual property laws and treaties. MOVEit Freely is licensed, not sold.
1. GRANT OF LICENSE. This license agreement grants you the following rights:
Installation and Use. You may install and use MOVEit Freely for your personal or company use. There is no charge for such use. You may also make copies of MOVEit Freely for backup and archival purposes.
Distribution. You may make unlimited copies of and may distribute to any party the original MOVEit Freely installation package as long as such distribution is performed without charge. You may reproduce or distribute components of the product (e.g., just «ftps.exe») as long as all MOVEit Freely documentation (including «MOVEitOverview.pdf») accompanies the software.
2. DESCRIPTION OF OTHER RIGHTS AND LIMITATIONS.
Limitations on Reverse Engineering, Decompilation, and Disassembly. You may not reverse engineer, decompile, or disassemble MOVEit Freely, except and only to the extent that such activity is expressly permitted by applicable law notwithstanding this limitation.
Software Transfer. You may not transfer your rights under this license agreement.
Termination. Without prejudice to any other rights, Ipswitch, Inc. may terminate this license agreement if you fail to comply with the terms and conditions of this license agreement. In such event, you must destroy all copies of MOVEit Freely and all of its component parts.
Rental. You may not sell, rent, or lease MOVEit Freely.
3. COPYRIGHT. All title and copyrights in and to MOVEit Freely, the accompanying printed materials, and any copies of MOVEit Freely are owned by Ipswitch, Inc. MOVEit Freely is protected by copyright laws and international treaty provisions. Therefore, you must treat MOVEit Freely like any other copyrighted material.
WARRANTY AND LIMITATION OF LIABILITY
WARRANTY. MOVEit Freely is distributed on an «as is» basis with no warranty, either expressed or implied.
OTHER WARRANTIES. TO THE MAXIMUM EXTENT PERMITTED BY APPLICABLE LAW, IPSWITCH, INC. AND ITS SUPPLIERS DISCLAIM ALL OTHER WARRANTIES AND CONDITIONS, EITHER EXPRESS OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, IMPLIED WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, TITLE, AND NON-INFRINGEMENT, WITH REGARD TO MOVEit Freely, AND THE PROVISION OF OR FAILURE TO PROVIDE SUPPORT SERVICES. THIS LIMITED WARRANTY GIVES YOU SPECIFIC LEGAL RIGHTS. YOU MAY HAVE OTHERS, WHICH VARY FROM STATE/JURISDICTION TO STATE/JURISDICTION.
LIMITATION OF LIABILITY. TO THE MAXIMUM EXTENT PERMITTED BY APPLICABLE LAW, IN NO EVENT SHALL IPSWITCH, INC. OR ITS SUPPLIERS BE LIABLE FOR ANY SPECIAL, INCIDENTAL, INDIRECT, OR CONSEQUENTIAL DAMAGES WHATSOEVER (INCLUDING, WITHOUT LIMITATION, DAMAGES FOR LOSS OF BUSINESS PROFITS, BUSINESS INTERRUPTION, LOSS OF BUSINESS INFORMATION, OR ANY OTHER PECUNIARY LOSS) ARISING OUT OF THE USE OF OR INABILITY TO USE MOVEit Freely OR THE PROVISION OF OR FAILURE TO PROVIDE SUPPORT SERVICES, EVEN IF IPSWITCH, INC. HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGES. IN ANY CASE, IPSWITCH, INC.’S ENTIRE LIABILITY UNDER ANY PROVISION OF THIS EULA SHALL BE LIMITED TO THE GREATER OF THE AMOUNT ACTUALLY PAID BY YOU FOR MOVEit Freely OR U.S.$5.00; PROVIDED, HOWEVER, IF YOU HAVE ENTERED INTO A IPSWITCH, INC. SUPPORT SERVICES AGREEMENT, IPSWITCH, INC.’S ENTIRE LIABILITY REGARDING SUPPORT SERVICES SHALL BE GOVERNED BY THE TERMS OF THAT AGREEMENT. BECAUSE SOME STATES AND JURISDICTIONS DO NOT ALLOW THE EXCLUSION OR LIMITATION OF LIABILITY, THE ABOVE LIMITATION MAY NOT APPLY TO YOU.
TRADEMARKS. MOVEit is a registered trademark of Ipswitch, Inc. All names of products and companies used in this document, the software, or the enclosed documentation may be trademarks of their corresponding owners. Their use in this document is intended to be in compliance with the respective guidelines and licenses.
Contacting the Vendor
MOVEit Freely is FREEWARE.
Support for MOVEit Freely is normally only available
to existing MOVEit Transfer customers and MOVEit Transfer evaluators.
To contact Ipswitch Support, go to:
1. Introduction
2. DriveHQ Command FTP Syntax and Parameters
3. Creating FTP Script Files
3.1 An Example of FTP Script File
3.2 FTP Script File with Parameters
4. Automate File Transfer with Windows Task Scheduler
5. Automatic Folder Synchronization using DriveHQ Command FTP
6. FTP Command References
6.1 Standard FTP Commands
6.2 DriveHQ Advanced FTP Commands
Command-line FTP/FTPS/SFTP client
1. Introduction
DriveHQ Command FTP is a powerful command-line FTP & SFTP client designed to replace the Windows FTP client.
It supports FTP scripting, and is compatible with any standard FTP/SFTP servers.
FTP/SFTP is extremely popular in transferring large files/folders over the Internet. Command-line FTP client is widely used
in automated file transferring with FTP scripting. Many people use the built-in command-line FTP client on Windows. However, the built-in FTP client
has a few major disadvantages:
- 1. It only supports active mode FTP, which is often blocked by routers, firewalls or security software.
- 2. It only supports plain FTP without data encryption.
- 3. It does not support automatic resuming/retrying.
DriveHQ Command FTP is designed to replace the default Windows FTP client.
It has the following advantages:
- 1. It supports both active and passive mode FTP.
- 2. It supports FTP over SSL (FTPS & FTPES) and SFTP.
- 3. It supports automatic resuming/retrying.
- 4. It supports data compression and encryption.
- 5. It supports downloading/uploading folders.
- 6. It supports mirroring/synchronizing folders.
- 7. It supports event logging for auditing and trouble shooting.
- 8. It can send email reports after an operation.
- 9. It supports more powerful FTP scripts.
In many cases, DriveHQ Command FTP can directly replace the Windows FTP client. They share similar syntax and command-line parameters.
However, DriveHQ Command FTP offers a lot more features. It can handle complicated
file transferring tasks with just one command. With its support for SFTP,
You can write an FTP script file, but run it with an SFTP server.
2. DriveHQ Command FTP Syntax and Parameters
Syntax
cmdftp FTP_SERVER [-u:USERNAME] [-p:PASSWORD] [-i] [-A] [-k:"PRIVATE_KEY_FILE"] [-s:"FTP_SCRIPT_FILE"] [-d:"LOG_FILE"] [-m:"SOURCE_FTP_SERVER", "DESTINATION_FTP_SERVER"] [CMDOPTIONS]
cmdftp [-s:"FTP_SCRIPT_FILE"] [-d:"logfile"]
Parameters
Parameter | Description |
---|---|
FTP_SERVER | The FTP/SFTP server name or IP address such as ftp.drivehq.com, or ftp://ftp.drivehq.com or ftps://ftp.drivehq.com. It is required unless the parameters include -s:FTP_SCRIPT_FILE |
-u:USERNAME | Specifies the FTP/SFTP account username. |
-p:PASSWORD | Specifies FTP/SFTP account password. |
-k:»PRIVATE_KEY_FILE» | Optional. Specifies the SFTP private key file path. |
-s:»FTP_SCRIPT_FILE» | Optional. Specifies the FTP script file path. If this parameter is provided, then other parameters are ignored, except the «-d:LOG_FILE» option. |
Command Options
/xo[:time] | Exclude old files |
/xn[:time] | Exclude newer files |
/xf:filenames | Exclude files, files are split by comma |
/xd:foldernames | Exclude folders, folders are split by comma |
Logging options
-d:»LogFileName» | Specifies the log file path. If using «-d» without a LogFileName, then it will display the log in the console window. |
3. Creating FTP Script Files
FTP scripts are very popular among IT administrators and system integrators. They are widely used in automated data backup and file transferring.
FTP scripts enable you to create a text file that contains a list of FTP commands and inputs. You can then run these commands sequentially in one execution.
Because a script file can contain many FTP commands, it can accomplish a very sophisticated file transfer task.
FTP scripting with the default Windows FTP client is very limited: It only supports plain FTP, which is not secure;
it only supports Active Model FTP, which is often blocked by routers/firewalls.
DriveHQ Command FTP supports most features of Windows FTP client; in addition, it supports many features that are not available in Windows FTP client.
DriveHQ Command FTP is compatible with all standard FTP servers.
To write an FTP script file, you can run the FTP commands in interactive mode first. Open a command window,
type in the following commands as shown in the screenshot below:
These commands usually include:
Connect to an FTP server, login to the server, list files/folders in a directory, change current directory, upload/download/delete files, and so on.
If you only occasionally use FTP, then the above method works just fine. However, if you need to repeatedly transfer/backup/delete files,
e.g. as part of a scheduled backup task, or EDI (Electronic Data Interchange) with another company,
you can easily write a script file that can be re-used again and again. Coupled with the Task Scheduler supported by the operating system,
you can automate the business process.
An Example of FTP Script File
An FTP script file has the same commands/inputs as used in an interactive FTP session.
Basically, you just need to create a text file in a text editor (e.g. NotePad),
and type in the commands and inputs as you would do in the interactive mode. DriveHQ’s
Command FTP has very similar interface as the Windows FTP client. The following commands
can be run in both the Windows FTP client and DriveHQ’s Command FTP clients. To use Command FTP, please type in cmdftp instead of ftp.
e.g.:
C:>ftp ftp> open ftp.drivehq.com Connected to ftp.drivehq.com. 220 Welcome to the most popular FTP hosting service! Save on hardware, software, hosting and admin. Share files/folders with read-write permission. Visit http:/ /www.drivehq.com/ftp/; User (ftp.drivehq.com:(none)): dhqdemo 331 User name ok, need password. Password: xxxxxxxxx 230 User dhqdemo logged on. ftp> cd test 250 CWD command successful. "/test" is current directory. ftp> delete orders.xml.bak 550 File not found. ftp> rename orders.xml orders.xml.bak 350 File exists, ready for destination name. 250 File "/test/orders.xml" renamed successfully. ftp> put c:testorders.xml 200 Port command successful. 150 Opening BINARY mode data connection for file transfer. 226 Transfer complete ftp: 41 bytes sent in 0.06Seconds 0.65Kbytes/sec. ftp> quit 221 Bye C:>
As you can see, these commands will:
— Log in to an FTP server: ftp.drivehq.com;
— Enter the username and password;
— Change to a local directory «c:test»;
— Change to an FTP directory «/test»;
— Delete the file «Orders.xml.bak» (if exists) on the FTP server;
— Rename the file «Orders.xml» (if exists) to «Orders.xml.bak» on the FTP server;
— Upload the local file «Orders.xml» to the FTP server;
— Exit
You can run them in a command window to debug the code before you save them into a script file. The content of the script will be as follows:
open ftp.drivehq.com USERNAME xxxxxxxxx cd test delete orders.xml.bak rename orders.xml orders.xml.bak put c:testorders.xml quit
The above FTP script can be executed daily to automatically transfer new orders info to the FTP server.
It will upload the latest «Orders.xml» to the FTP server; before it uploads the file, it will
rename (backup) the previous file.
To run the FTP script, you just execute the FTP command with the -s option. With Windows FTP client, you can use:
ftp -s:ftpscript.txt
With DriveHQ command FTP client, you can use
cmdftp -s:ftpscript.txt
FTP Scripts with Parameters
The above FTP script is static. It can be run repeatedly, but it is not very flexible.
For example, if you need to transfer data for multiple clients, you probably want to use different folders.
To re-use the same FTP script, it needs to support additional parameters. There are two solutions:
(1) Use a batch script file to dynamically create the FTP script file. Windows batch scripts can take command-line parameters. If you use Windows FTP client, this is the only solution.
(2) DriveHQ Command FTP supports additional parameters.
With the first method, you need to create a batch file, e.g. test.bat. Save the file in the folder C:test. You can run the batch file by type in:
c:testtest.bat PARAM1 PARAM2 ...
The test.bat file will be like:
@echo off echo open ftp.drivehq.com > ftpscript.txt echo USERNAME >> ftpscript.txt echo PASSWORD >> ftpscript.txt echo cd %1 >> ftpscript.txt echo delete %2.bak >> ftpscript.txt echo rename %2 %2.bak >> ftpscript.txt echo put c:%1%2 >> ftpscript.txt echo quit >> ftpscript.txt
This way, you can pass the arguments to the batch file to the FTP script file. The same batch script can be re-used
for different companies, e.g.:
c:testtest.bat c:OrdersOfCompanyA ordersOfCompanyA.xml c:testtest.bat c:OrdersOfCompanyB ordersOfCompanyB.xml
With DriveHQ Command FTP, you can run an FTP script with additional arguments.
This way, you don’t need to create a batch script file. You can simply run
the FTP script with the following command:
cmdftp -s:ftpscript.txt argument1 argument2 argument3 ...
The FTP script file needs to be modified slightly as follows:
# %1 is like "test", %2 is like "orders.xml" # This file is saved as c:tempftpscript2.txt # to run it, use: # cmdftp -s:c:tempftpscript2.txt -%1:test -%2:orders.xml open ftp.drivehq.com USERNAME PASSWORD cd /%1 delete /%1/%2.bak rename /%1/%2 /%1/%2.bak put c:%1%2 quit
In the above script file, the folder name is replaced with %1, and the file name is replaced with %2.
To run the FTP script, you must supply these parameters as command-line arguments.
cmdftp -s:c:tempftpscript2.txt -%1:test -%2:orders.xml
When DriveHQ Command FTP executes the script file, it will replace %1 with «test» and %2 with «orders.xml».
4. Automate file transfer with Windows Task Scheduler
Whether you use a batch file, or directly use DriveHQ Command FTP, you can schedule the file transfer in Windows Task Scheduler.
You can schedule the task to run daily, weekly or monthly. In the Advanced Settings, you can even set the task to run every few hours or minutes.
you can set the time of the day to start the task. To launch Task Scheduler, type «Task scheduler» in the search box, see the screenshot below:
Click Task Scheduler, it will launch Windows Task Scheduler.
To create a task, click «Create Basic Task».
Enter the task name and description, then click Next.
Select your task schedule. You can choose daily, weekly and monthly. If you want to run the task hourly, you can do so in the Advanced Settings later.
Click Next to set the Action.
In the Action page, select «Start a program», then click Next.
Browse to select DriveHQ Command FTP (cmdftp.exe) as the program. Add the command-line parameters in the «Add Arguments» text box. The «Start in» is optional. You can set it
to the same folder as the EXE file. Click Next to finish creating the task.
To access the Advanced Settings, click «Task Schedule Library», you can see a list of scheduled tasks. Double click on the task «Upload Orders», you can edit the
task settings.
Note by default, the task will run only when the user is logged on. You can change the setting here to run the task even when the user is not logged on.
5. Automatic Folder Synchronization using DriveHQ Command FTP
DriveHQ Command FTP supports folder mirroring. Synchronizing a local folder with an FTP folder is extremely easy. Just use the following command:
cmdftp FTP_SERVER -u:username -p:password -m:"LOCAL_FOLDER"|"FTP_FOLDER"
Using Windows Task Scheduler, you can run this command to synchronize the two folders periodically.
6. FTP Command References
After you log on to an FTP server, you can send FTP commands to the FTP server. Windows FTP client supports the following commands.
Please note these commands are not the same as FTP commands defined in the FTP Protocol.
Each FTP Protocol Command usually only handles one simple issue. An FTP command in Windows FTP client may use multiple FTP Protocol Commands.
DriveHQ Command FTP is similar to the Windows FTP client. It supports similar commands and syntax. In addition, it also supports a few DriveHQ-specific
advanced FTP commands, e.g. commands to copy, move, upload, download or delete folders.
6.1 Windows FTP Client Commands
Windows FTP client (ftp.exe) supports the following FTP commands:
FTP Commands | Description |
---|---|
! | This command toggles between the local operating system and the FTP server. When you log on to an FTP server, it defaults to the FTP server. If you want to run a command locally, you can usually use !CMD_NAME, e.g. !dir, !mkdir, etc. |
? | Displays the Help information. |
append | Append to a file. |
ascii | Set ASCII transfer mode. |
bell | Turn on «Beep when command completed». |
binary | Set binary transfer mode. |
bye | Disconnect the FTP session and exit. |
cd | Change directory. |
close | Terminate the FTP session. |
delete | Deletes a file. |
debug | Toggle debugging mode on or off. |
dir | Lists files and sub-folders in a directory. |
disconnect | Disconnect the FTP session. |
get | Get file from the remote FTP server. |
glob | Set globbing on or off. When turned off, wildcard characters in file names (in the put and get commands) are taken literally. |
hash | Toggle printing «#» for each buffer transferred. |
help | Display the Help information; usually use help COMMAND_NAME. |
lcd | Display the current local working directory if typed alone; otherwise, change the local working directory. |
literal | Send arbitrary command to the connected FTP server with an expected one-line response. |
ls | List files in the FTP folder. |
mdelete | Delete multiple files on the FTP server. |
mdir | Lists files/subfolders of multiple FTP directories. |
mget | Download multiple files from the FTP server to your local working folder. |
mkdir | Create a new directory. |
mls | List contents of multiple FTP directories. |
mput | Upload multiple local files to the FTP server. |
open | Connect to an FTP server. |
prompt | Enables or disables interactive prompting on multiple commands. |
put | Upload one file to the FTP server. |
pwd | Print working directory on the FTP server. |
quit | Disconnect from FTP server and exit. |
quote | Same as the literal command (Send arbitrary ftp command). |
recv | Download / receive a file from the FTP server. |
remotehelp | Get help from remote server. |
rename | Rename a file on the FTP server. |
rmdir | Remove a directory on the FTP server. |
send | Send one file. |
status | Shows status of current options. |
trace | Toggle packet tracing. |
Type | Set file transfer type. |
user | Send new user information (username). |
verbose | Set verbose on or off. |
6.2 DriveHQ Advanced FTP Commands
DriveHQ Command FTP supports a few more advanced FTP commands:
FTP Commands | Description |
---|---|
download | Download a folder or file. Syntax: Download [FTP-FILEorFOLDER-PATH] [LOCAL-FILEorFOLDER-PATH] |
upload | Upload a folder or file. Syntax: Upload [LOCAL-FILEorFOLDER-PATH] [FTP-FILEorFOLDER-PATH] |
mirror | Mirror a local folder and an FTP folder. Syntax: MIRROR [LOCAL-FOLDER-PATH] [FTP-FOLDER-PATH] |
deleteoldfiles | In the specified folder, delete files older than x days. Syntax: RMDIR [FTP-PATH] /xo:[time] |