FTPLOGON - Connect to a remote site

Syntax:	FTPLOGON	[ site ] [ /options ]
Arguments:	[ site ]	Variable or string defining the Managed Site name, URL or IP address of remote server; if [ site ] is omitted, the default Managed Site record is used; site names are not case-sensitive.
Options:	/acct=xx	Define account to use when logging on to an FTP site.
	/allowerrors	Some poorly configured servers return errors when Robo-FTP tries to verify the existence of a directory. This option enables you to ignore those errors. This option applies only to SFTP, HTTP, and HTTPS connections.
	/clientcert	Specify this option if you are connecting to an SSL server and you wish to provide a client certificate to the site used and this site wasn’t preconfigured to use client certificates. This is optional if the SSL server automatically requests that Robo-FTP send its certificate. If you know that a particular site requires a client certificate, it is a good idea to specify this option because it is possible that the server will not request the certificate which will cause the connection to fail.
	/compression=n	Sets the data compression level. The value must be between 0 - 9. The default is 0 (not used).
	/dynamicdirs	Specify this option when connecting an FTP site that presents different (dynamic) directory listings to a client depending on which directory is active. This option may always be present if you are in doubt - there may be a minor decrease in performance since Robo-FTP may request directory listings more often.
	/disable=xx	Don't send the sepecified raw FTP command. This option can seriously degrade performance; use it only when the remote site has a severe negative reaction to a a particular raw FTP protocol command. This option may be used multiple times. See also /nocwd and /nolist below.
	/httpauth=xx	Some web servers require authentication before allowing access to certain resources. Allowed values are: none, auto, basic, digest, and ntlm. You must provide credentials for NTLM authentication so this option is not appropriate for a "single sign-on" solution.
	/ibm	Enable IBM Host Features mode.
	/keyauth	Specify this option if you are connecting to an SSH server and you wish to enable key authentication. This is optional if the SSH server only requires password authentication. This option requires a private key to be previously defined using the Robo-FTP Configurator.
	/keypw=xx	Password to use with the key specified by the /privatekey option.
	/listtype=n	Specify this option to instruct Robo-FTP to issue alternate forms of the LIST command. See details below.
	/maxport=nn	Highest permissible port number to use with the PORT command for active mode data transfers.
	/minport=nn	Lowest permissible port number to use with the PORT command for active mode data transfers.
	/myipaddr=xx	IP address to use with the PORT command for active mode data transfers.
	/nocwd	Prevents sending the CWD verb during the connection. This option cannot be used with /allowerrors.
	/nolist	Do not allow Robo-FTP to request directory listings. This option is mostly useful on HTTP connections where requesting a directory listing could jeopardize the transaction state. Don't use this unless you know you need it because it limits Robo-FTP's functionality.
	/pasv=x	Enable or disable passive mode for FTP data transfers. Passive mode is enabled by default so one would normally only use this command to disable passive mode with the following syntax: /pasv=false Robo-FTP uses active mode for data transfers when passive mode is disabled.
	/pasvport=nn	Outgoing data connection port to use when connecting using passive mode.
	/port=nn	FTP port to connect to.
	/precisetime	Some servers do not provide complete time date information in directory listings. This option attempts to use protocol dependent alternative methods to retrieve complete UTC time/date stamps for each file. Not all servers support this option and its use will adversely affect performance, due to secondary requests made for each file found in any directory listing.
	/privatekey=x	Specify the private key to use for secure authentication. When connecting to an SSL site this option may be paired with the /clientcert option.
	/proxy=xx	Define the name or IP address of a proxy server (/gw= is also accepted).
	/proxyport=nn	Proxy server port to connect to (/gwport= is also accepted).
	/proxypw=xx	Define password to use when logging on to a proxy server (/gwpw= is also accepted).
	/proxytype=xx	Supported types include: FTPACCT, FTPOPEN, FTPSITE, FTPUSER, SimpleRelay, SOCKS4, SOCKS4a, SOCKS5, WindowsIE, and WebStandard. For more information, see the help topic named Proxy Server Settings.
	/proxyuser=xx	Define user name to use when logging on to a proxy server (/gwuser= is also accepted).
	/pw=xx	Define password to use when logging on to an FTP site.
	/restrictipaddr=x	Specify this option to restrict the data connection to the same IP address used for the control connection (as opposed to allowing a connection to whatever IP address is returned in reply to PASV command from the Server). This option is enabled by default so one would normally only use this to allow connecting to a different address with the following syntax: /restrictipaddr=false This option only applies to passive mode data transfers.
	/retrycount	How many times to retry an action before giving up and returning an error. Default is zero.
	/retrydelay	How many seconds to wait before retrying. Defaults to 1 second.
	/savehost[=xx]	Creates or updates a Managed Site definition. If /savehost is used without specifying a xx then the value of the [ site ] argument is also used as the name of the new Managed Site record.
	/servertype=xx	Select the FTP site type from the list below.
	/sslmethod=xx	Specifies sending an SSL Client HELLO conforming to the given SSL/TLS version. Supported SSL methods include: sslv2, sslv23, sslv3, tlsv1, tlsv11, and tlsv12. If this option is not provided, the method defaults to sslv23.
	/sslciphers=xx	Specifies the ciphers allowed by the client. If this option is not provided, the default is "ALL:!EXPORT:!LOW:!aNULL:!eNULL:!SSLv2"
	/sslminversion=xx	Specifies the minimum version of SSL allowed by the client. Supported versions include sslv2, sslv3, tlsv1, tlsv11, and tlsv12. If this option is not provided, the minimum version defaults to sslv3.
	/sslmaxversion=xx	Specifies the maximum version of SSL allowed by the client. Supported versions include: sslv2, sslv3, tlsv1, tlsv11, and tlsv12. If this option is not provided, the minimum version defaults to no maximum version.
	/ssloptions=xx	Specifies a list of OpenSSL options to enable. Each option should be separated by a \| (pipe) character. If not otherwise specified, a default value of SSL_OP_ALL is assumed. See Advanced SSL Options for the complete list of available options.
	/timeout=nn	Time-out in seconds to wait for logon to complete. The specified number also serves as the default timeout for network activity on the connection. The default period is 30 seconds.
	/trust=xx	Action to take when an untrusted certificate is received from an SSL secured server or when an unknown SSH server identifies itself during key authentication. The default action if this option is not specified is DENY.
	/user=xx	Define user name to use when logging on to an FTP site.

This script command logs on to a remote server. If the [ site ] argument matches the name of a Managed Site record created in the Configurator, the server address, username, password and other parameters associated with that record are used. If the [ site ] argument does not match a Managed Site record, Robo-FTP interprets [ site ] as a server network address. [ site ] names are not case-sensitive.

The /user, /pw, /port, and /acct options may be used to override the predefined user name and/or password associated with an existing site, or may be used with a site that has not been previously defined. Not all sites utilize the /acct option.

The /servertype option (/type also recognized for backward compatibility with pre-v2.0 versions) may be used to override the predefined site type, or may be used with a site that has not been previously defined. The possible choices are:

The /trust option controls whether the connection is allowed when credentials presented by a secure site are not trusted. The possible values are:

The /clientcert option may be used to force an SSL connection to send a client certificate when it may not have been pre-configured to do so. The /keyauth option may be used to enable SSH private key authentication when connecting to this site.

When access to a remote site is controlled by a proxy server, the /proxy, /proxyuser, /proxyport, and /proxypw options may be used to define or override a predefined proxy (gateway) server name, user name, port, and/or password. When connecting to an HTTP/HTTPS site Robo-FTP uses the WindowsIE /proxytype by default.

Some servers require an alternate form of the LIST command to return directory contents:

The /listtype option cannot be directly configured for the FTP client applet or pre-configured as a default option for a specific site. However, a manual setting value does exist for this option. Access the online Knowledge Base at http://www.robo-ftp.com for more information.)

The /ibm option enables IBM Host Features for the FTP session if the logon is successful. IBM Host Features mode permits JES queue options to be selected and allows EBCDIC transfer mode for the SENDFILE, RCVFILE, and SYNC script commands.

The /pasv=false option disables passive mode operation for the FTP session if the logon is successful. Passive mode operation may be required to list directories, and send and receive files with certain FTP sites. Using this option overrides the settings for a given site that may have been set when it was configured with the Robo-FTP Configurator. Consequentially, passive mode can also be enabled for a managed site previously configured to use active mode by using the /pasv=true option (or simply /pasv) to override that setting.

In FTP and FTPS modes with passive mode operation, the /restrictipaddr=false allows the data connection to be on a different IP address than the control connection. This option may be required to connect to some servers.

The /httpauth option is useful when connecting to a restricted web resource. The following authentication methods are available:

Any logon, either with this script command or with the Logon button within the Robo-FTP client applet, serves as a general logon for either or both script and applet operation within Robo-FTP.

The [ site ] argument can also take the name of a Managed Site. In this case, the server address, username, password, and other connection details are obtained from the Managed Site definition maintained by the Configurator.

Consider the following example where Robo-FTP attempts to connect with a previously undefined FTP site.

Consider the following example where Robo-FTP attempts to connect with an SSL server and accept the FTP site’s certificate, regardless of whether or not that certificate has been previously trusted.

Finally, consider the following example where Robo-FTP attempts to connect with the default Managed Site and specifies a different password that overrides the password listed on the property sheet for the Managed Site.

The /retry_count and /retry_delay options are used to have Robo-FTP retry actions that fail. If retry count is greater than zero and an error is returned from the protocol stack that is not known to be permanent Robo-FTP will disconnect and pause for retry delay seconds before logging back on and changing the working directory on the new connection to be the same as it was then retrying the action that failed previously.

The best way to ensure the security of a password for a server is to provide it through a site definition in the Configurator's Managed Sites page. This is also the easiest way of handling passwords that contain certain special characters. Otherwise, when providing a password directly in the FTPLOGON command with the /pw option, some care must be taken when the password contains special characters that may otherwise be misinterpreted by the script parser itself. For example, if a password contains a space, the password should be surrounded with double quotes, like so:

If the password itself contains double quotes, you can surround it by single quotes instead:

FTPLOGON will return an error ($ERROR_FTP_IS_LOGGED_ON) and refuse to log on to a new server if the user is currently logged on to a site. When a script does not issue an FTPLOGOFF command at the end of processing, this can cause easily lead to unexpected errors, especially when dealing with scripts that run sequentially from a single Robo-FTP session, such as when using the CRON and PERFORM commands. An effective solution for mitigating this issue is to ensure that each FTPLOGON command is preceded by an FTPLOGOFF command.