Robo-FTP User's Guide > Script Programming > Script Commands > All Script Commands > FTPLOGON

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. It also will ignore any SSL_SHORT_READ errors generated when misbehaving FTP servers do not cleanly shutdown a TLS connection after returning an empty listing.
	/biglistings=xx	Improves the efficiency of file listings for very large directories by aborting the listing transfer midway with the ABOR command, when per-file attribute commands like SIZE, MDTM, and MLST are not supported by the server. This option only applies to FTP and FTPS connections. Supported values are true and false. The default option is false. This option does not provide any benefit if the target server already supports SIZE and MDTM, or the MLST command. Some servers are not capable of properly responding to an ABOR command during a listing and instead abruptly drop the connection, so enable this option with caution.
	/clientcert	Specify this option if you are connecting to a TLS 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 TLS 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 a TLS 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/TLS 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/TLS 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.
	/sslreusesession	Reuse the same TLS session settings in the FTP data channel as used in the control channel. (Applies only to FTPS.)
	/timeout=nn	Specifies the 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. A %datetime value can also be given as an argument instead of a number of seconds.
	/trust=xx	Action to take when an untrusted certificate is received from a TLS 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:

FTP	Normal FTP (the default)
SFTP	FTP + SSH
FTPS	FTP + TLS (control and data channels both encrypted)
FTPSCONTROL	FTP + TLS (control channel encrypted only)
FTPSCCC	FTP + TLS (data channel encrypted only)
FTPSIMP	FTP + TLS (implicit mode)
HTTP	HTTP
HTTPS	HTTP + TLS

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

DENY	The connection to the remote site fails if the server's TLS certificate is not trusted or the SSH server is unknown. This is the default action.
ALLOW	The connection to the remote site is allowed if the server's TLS certificate is not trusted or the SSH server's key is unknown.
ALL	The connection to the remote site is allowed if the server's TLS certificate is not trusted or the SSH server's key is unknown. The server's credentials are saved as a file and the site will not be considered unknown or untrusted if it presents the same credentials during future connections.

The /clientcert option may be used to force a TLS 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:

/listtype=1	This option forces Robo-FTP to issue alternate “LIST .” (vs. simply “LIST”) when requesting directory listings from an FTP site.
/listtype=2	This option forces Robo-FTP to issue alternate “NLST” (vs. simply “LIST”) when requesting directory listings from an FTP site. In this later case, the server does not return any information about its files (e.g. file size and date/time) so the associated internal variables (e.g. %sitefiledate and %sitefiletime) cannot be properly populated. Also some features of Robo-FTP (such as requesting the most recent file on the server) are not supported when /listtype=2 is used.
/listtype=3	This option causes Robo-FTP to issue "LIST" even when the remote FTP site supports the "MLSD" command.
/listtype=4	This option causes Robo-FTP to use the "MLSD" command when requesting directory listings from an FTP site.

Important

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:

none	No authentication sent.
auto	Tries first without any authentication. If the attempt fails, the resource is re-requested using Digest authentication, then NTLM, then Basic.
basic	Sends base64 encoded username and password.
digest	Primarily used with WebDAV servers, this type sends one challenge/response and password is never sent in clear text.
ntlm	NTLM mode sends sequence of challenges/responses with the (proxy) server but without ever sending plaintext password over insecure network.

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 use take either an IP address or URL.

FTPLOGON "ftp.acme-widget.com"

-or-

FTPLOGON "20.178.128.17"

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.

FTPLOGON "The Robo-FTP Site"

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

FTPLOGON "ftp.new.com" /user=anonymous /pw=itchy

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

FTPLOGON "ftp.secure.com" /servertype=FTPS /trust=ALLOW /user=Tom /pw=secret

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.

FTPLOGON /pw=adv50095

The /retrycount and /retrydelay 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:

FTPLOGON "ftp.example.com" /user=x /pw="this pw has spaces"

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

FTPLOGON "ftp.example.com" /user=x /pw='this "pw" has double quotes too'

Related command(s): FTPLOGOFF