FTP - Logon
Declaration
<AMFTP ACTIVITY="logon" SERVER="text" USERNAME="text" PASSWORD="text (encrypted)" ANONYMOUSLOGIN="YES/NO" SESSION="text" TYPE="text (options)" PORT="number" PASSIVEMODE="YES/NO" COMPRESSION="YES/NO" ENCRYPTDATACHANNEL="YES/NO" IGNOREINVALIDCERTIFICATE="YES/NO" CLEARCOMMANDCHANNEL="YES/NO" TUMBLEWEEDSERVER="YES/NO" FIPS="YES/NO" FTPOPTIONS="text (options)" CERTIFICATESOURCE="text (options)" CERTIFICATEISSUERID="text" CERTIFICATESERIAL="text" CERTIFICATE="text" CERTIFICATEPASSPHRASE="text (encrypted)" CERTIFICATEPRIVATEKEY="text" TLSCIPHERS="text (options)" TLSOPTIONS="text (options)" SSLVERSION="text (options)" SFTPVERSIONS="text (options)" SFTPAUTHTYPE="text (options)" SFTPHOSTKEY="text (options)" SFTPHOSTKEYNOTFOUND="text (options)" CIPHERSELECTION="text (options)" SSHENCRYPTION="text (options)" SSHKEYEXCHANGE="text (options)" SSHMAC="text (options)" SSHPUBLICKEY="text (options)" LOGFILE="text" OVERWRITELOG="YES/NO" TRANSFERBLOCKSELECTION="text (options)" "PIPELINELENGTH="number" UPLOADSIZE="number" DOWNLOADSIZE="number" TIMEOUT="number" MEASURE="text (options)" UPLOADBUFFERSIZE="number" PROXYTYPE="text (options)" PROXYSERVER="text" PROXYPORT="number" PROXYUSERNAME="text" PROXYPASSWORD="text (encrypted)" />
Description
Starts a transaction with a File Transfer Protocol (FTP) server and creates a session for the current connection. Other FTP related actions can follow this step. This activity allows simultaneous FTP connections using the same username/password.
NOTE: Be sure to end FTP sessions
with an FTP - Log Off step.
Practical usage
Used to connect to an FTP server. Other FTP activities can be used to following this step.
Parameters
Connection
| Property | Type | Required | Default | Markup | Description |
|---|---|---|---|---|---|
| Host | Text | Yes | (Empty) |
|
The IP address (xxx.xxx.xxx.xxx) or the server and domain name (for example, server.domain.com) of the FTP server. |
| Username | Text | Yes | (Empty) | USERNAME="Clark.Kent" | The username to use when logging on to the FTP Server. The username is preconfigured at the server level. |
| Password | Text | No | (Empty) | PASSWORD="password" | The password to use when logging on to the FTP Server. When the step is created using the Task Builder it is written to the task encrypted. |
| Use anonymous log on | Yes/No | No | No | ANONYMOUSLOGIN="YES" | If selected, the FTP server is logged on as an "Anonymous" user and the Username and Password parameters are disabled (disabled by default). The server must be configured to accept anonymous connections. |
| Session | Text | Yes | FTPSession1 | SESSION="FTPSession2" | The session name to assign to this activity. This allows several FTP activities to be linked to a specific session. Numerous sessions can be used within a single task. |
Advanced
| Property | Type | Required | Default | Markup | Description |
|---|---|---|---|---|---|
| Connection type | Text (options) | Yes | FTP (standard) |
|
The
type of FTP connection to use. The available options
are:
|
| Port | Text | Yes | 21 | PORT="1000" | The
port to use to connect to the FTP server. Most standard
FTP servers operate on port 21 (the default port specified) however,
this parameter can be customized in case the FTP server operates
on other ports. NOTE: Other default ports may be assigned depending on the server connection
type selected. |
| Passive mode (for firewalls) | Yes/No | No | No | PASSIVEMODE="YES" | Determines
how an FTP data connection is made. If selected, Automate Desktop issues
the PASV command and the server tells Automate Desktop where to establish
the data connection. Automate Desktop initiates both connections to the
server, solving the problem of firewalls filtering the incoming
data port connection to the client from the server. If disabled (default), the PORT method is used. Automate Desktop listens for a data connection
which is established by the server and the PORT command tells
the server where to connect to. Automate Desktop then connects to the
server where the server indicated. This method is sometimes used
with some proxy configurations. However, some proxy configurations
require PORT transfers and some FTP servers do not support PASV
transfers. This parameter is available only if the FTP (standard), FTP with SSL/TLS (implicit), or FTP with SSL/TLS (explicit) option is selected from the Connection type parameter. |
| Use compression | Yes/No | No | No | COMPRESSION="YES" | If selected, data is compressed using a single algorithm to reduce the total amount of data that is transmitted. If transmission speeds are slow, transfers can be sped up significantly when using compression, particularly if text files are being transferred. Media files (for example, JPEG and MPEG) are usually compressed already, thus, there will be little or no benefit in using compression. |
| Encrypt data channel | Yes/No | No | No | ENCRYPTDATACHANNEL="YES" | If
selected, specifies that all data channel communication between
the client and server are to be encrypted (disabled by default). This parameter is available only if the FTP with SSL/TLS (implicit) or FTP
with SSL/TLS (explicit) option is selected from the
Connection type parameter. It may not be advantageous to use data channel encryption when performing transfers under the following scenarios:
|
| Ignore invalid server certificates | Yes/No | No | No | IGNOREINVALIDCERTIFICATE="YES" | If selected, specifies that this action will ignore invalid certificates when connecting to an FTP server using SSL (disabled by default). This parameter is available only if the FTP with SSL/TLS (implicit) or FTP with SSL/TLS (explicit) option is selected from the Connection type parameter. |
| Clear command channel | Yes/No | No | No | CLEARCOMMANDCHANNEL="YES" | If
selected, this option enables support for the Clear Command Channel
(CCC) functionality (disabled by default). The CCC command can be issued by a remote
FTPS client and will cause Automate Desktop's FTP client to fall out of
secure mode and back in to unsecured mode. This option is useful
for clients who only need to secure the authentication portion
of the session. Once the USER/PASS has completed, some clients
will use CCC to return to unsecured mode, which is faster. This parameter is available only if the FTP with SSL/TLS (implicit) or FTP with SSL/TLS (explicit) option is selected from the Connection type parameter. |
| Enable Tumbleweed mode | Yes/No | No | No | TUMBLEWEEDSERVER="YES" | If selected, allows compatibility with Tumbleweed Secure Content Delivery (disabled by default). This parameter is available only if the FTP with SSL/TLS (implicit) or FTP with SSL/TLS (explicit) option is selected from the Connection type parameter. |
| Enable FIPS mode | Yes/No | No | No | FIPS="YES" | If
selected, FIPS 140-2 validated cryptography mode is enabled
(disabled by default). The Federal
Information Processing Standard (FIPS) Publication 140-2 specifies
the security requirements of cryptographic modules used to protect
sensitive information. Most
government agencies such as the Department of Defense and companies
in the public sector such as healthcare, financial and manufacturing
require FIPS validation to protect the integrity of data traffic
traveling across their networks. This parameter is available only if the FTP with SSL/TLS (implicit), FTP with SSL/TLS (explicit), SFTP (password), or SFTP (key) option is selected from the Connection type parameter |
| FTP options | Text (options) | Yes | None |
|
Specifies
the advanced FTP option to apply during the transfer. The following
lists all FTP options supported by Automate Desktop's built-in FTP
client:
|
| Client certificate source | Text (options) | No | No certificate |
|
FTP
over SSL allows sessions to be encrypted between an FTP client
and server. This property is used to select the source of the
certificate. A certificate is a digitally-signed statement that
binds the value of a public key to the identity of the person,
device, or service that holds the corresponding private key. One
of the main benefits of certificates is that hosts no longer have
to maintain a set of passwords for individual subjects who need
to be authenticated as a prerequisite to access. Instead, the
host merely establishes trust in a certificate issuer. The available options are:
This option is available only if the FTP with SSL/TLS (implicit) or FTP with SSL/TLS (explicit) option is selected from the Connection type parameter. |
| Certificate issuer | Text | No | (Empty) | CERTIFICATEISSUERID="Name" | Specifies information regarding the certification authority that issued the certificate. This parameter is available only when Certificate store option is selected from the Client certificate source parameter. |
| Certificate serial number | Number | No | (Empty) | CERTIFICATESERIAL="c7 f5 fa f8 6d ab 77 87 43 4a 11 43 f1 cd 3c 0f" | Specifies the unique serial number that the issuing certification authority assigns to the certificate. The serial number is unique for all certificates issued by a given certification authority. This parameter is available only when Certificate store option is selected from the Client certificate source parameter. |
| Certificate file | Text | No | (Empty) | CERTIFICATE="C:\Temp\Certificate_Location" | Specifies the path and file name of the certificate file. This parameter is available only when the File(s) option is selected from the Client certificate source parameter. |
| Passphrase | Text | No | (Empty) | CERTIFICATEPASSPHRASE="passphrase" | Specifies the passphrase used to authenticate connection. A passphrase is a password that comprises a whole phrase. This parameter is available only when the File(s) option is selected from the Client certificate source parameter. |
| Certificate private key | Text | No | (Empty) | CERTIFICATEPRIVATEKEY="C:\Temp\Private_Key" | Specifies the path and file name of the Private key file. This parameter is available only when the File(s) option is selected from the Client certificate source parameter. |
| TLS cipher(s) | Text (options) | Yes | All | TLSCIPHERS="All" | The specified group of allowed TLS/SSL cipher suites. Connection type must be host to use. The following cipher options are:
|
| TLS options | Text (options) | Yes | None | TLSOPTIONS="None" | The specified TLS/SSL versions allowed. Connection type must be host to use. Connection type must be host to use. The following cipher options are:
|
| SSL versions | Text (options) | No | SSL30,TLS10,TLS11 | SSLVERSION="SSL3" | Specifies the versions of SSL (Secure Sockets Layer) and/or TLS (Transport Layer Security) protocols to use to secure the connection to the server. To select multiple versions, manually enter and separate each version with a comma (see default setting). The available options are:
|
| SFTP versions | Options | No | Sftp2,Sftp3,Sftp4 | SFTPVERSIONS="Sftp5,Sftp6" | Indicates
the SFTP versions that the server supports.
To select multiple versions, manually enter and separate each version with a comma (see default setting). The available options are:
This parameter is available only if the Connection type parameter is set to SFTP (password) or SFTP (key). |
| Authentication type | Text (options) | No | Auto | SFTPAUTHTYPE="Password" | Indicates
the SFTP authentication type that the server supports.
To select multiple types, manually enter and separate each version with a comma (for example, Password,Hostbased). The available options are:
This parameter is available only if the Connection type parameter is set to SFTP (password) or SFTP (key). |
| Ignore sftp server's host key/Validate sftp server's host key | Options | No | None | SFTPHOSTKEY="validate" | Indicates whether to ignore or validate the SFTP server's host key. This parameter is available only if the Connection type parameter is set to SFTP (password) or SFTP (key). |
| If server host key is not found then | Options | No | Store it | SFTPHOSTKEYNOTFOUND="throw_error" | Indicates
what action to perform if the server host key is not found. The available options are:
This parameter is available only if the Validate sftp server's host key parameter is selected. |
| Cipher(s) selection | Options | No | Auto | CIPHERSELECTION="custom" | Specifies the cypher algorithm to use. The available options are:
|
| Encryption algorithm(s) | Text (options) | Yes | All | SSHENCRYPTION="EA_DES" | Specifies the encryption algorithms to use during the SSH session.
To select multiple algorithms, manually enter and separate each one with a comma (for example, EA_3DES,EA_AES256). The encryption algorithms supported by Automate Desktop are:
This parameter is available only if the Cipher selection(s) parameter is set to Custom. |
| Key-Exchange algorithm(s) | Text (options) | Yes | All | SSHKEYEXCHANGE="DH_GROUP" | Specifies the key-exchange algorithms to use during the SSH session. To select multiple algorithms, manually enter and separate each one with a comma (for example, DH_GROUP,RSA1024_SHA1). The key-exchange algorithms supported by Automate Desktop are:
This parameter is available only if the Cipher selection(s) parameter is set to Custom. |
| MAC algorithm(s) | Text (options) | Yes | All | SSHMAC="HMAC_SHA1_96" | Specifies the MAC algorithms to use during the SSH session. To select multiple algorithms, manually enter and separate each one with a comma (for example, HMAC_SHA1,UMAC32). The MAC algorithms supported by Automate Desktop are:
This parameter is available only if the Cipher selection(s) parameter is set to Custom. |
| Public key algorithm(s) | Text (options) | Yes | All | SSHPUBLICKEY="X509_SIGN_RSA" | Specifies the public key algorithms to use during the SSH session. To select multiple algorithms, manually enter and separate each one with a comma (for example, DSS,RSA). The public key algorithms supported by Automate Desktop are:
This parameter is available only if the Cipher selection(s) parameter is set to Custom. |
| Log file | Text | No | (Empty) | LOGFILE="c:\temp\error.log" | The location of a detailed FTP log file. This log file contains the exact text of the FTP session which can be useful in diagnosing particular errors or elusive problems. |
| Overwrite existing log file | Yes/No | No | Yes | OVERWRITELOG="NO" | If selected (default), specifies the log file should be overwritten if the same file already exists. If disabled, the file will not be overwritten, however, an error will occur at runtime as a result. |
| Transfer blocks | Text (options) | Yes, if the Connection type parameter is set to SFTP (password) or SFTP (key) | Auto-Adjust |
|
Specifies how blocks are transferred over SFTP. The available options are:
|
| Pipeline length | Number | Yes, if the Transfer blocks parameter is set to Custom | 1 | PIPELINELENGTH="13" | Specifies the pipeline length to use when transferring blocks over SFTP. |
| Upload block size | Number | Yes, if the Transfer blocks parameter is set to Custom | 16384 | UPLOADSIZE="163548" | Specifies the upload block size to use during SFTP transfers. |
| Download block size | Number | Yes, if the Transfer blocks parameter is set to Custom | 16384 | DOWNLOADSIZE="163548" | Specifies the download block size to use during SFTP transfers. |
| Timeout | Number | Yes | 30 | TIMEOUT="60" | Indicates a connection time out to customize how long Automate Desktop will wait before aborting a connection attempt. If connection is not established within the time out value specified, it is automatically aborted. The default value is 30 seconds. |
| Measure (unlabeled) | Text (options) | Yes | seconds |
|
The
time measurement corresponding to the value entered in
the Timeout parameter.
The available options are:
|
| Upload buffer size (bytes) | Number | Yes |
|
UPLOADBUFFERSIZE="54443" | The
upload buffer size value (in bytes) for files being uploaded.
In some cases changing the upload buffer size can make a difference;
particularly in transfers over high loss or high speed connections
where latency plays an important role. Depending on the connection type, the default value/maximum buffer size will vary:
NOTE: Setting the Upload buffer size value too high for slow connections
might cause timeouts and the transfer speed calculation may become
inaccurate. |
Proxy
| Property | Type | Required | Default | Markup | Description |
|---|---|---|---|---|---|
| Proxy type | Text (options) | No | None |
|
Specifies the proxy protocol to use. If you are unsure of
the value to use in this parameter, contact your network administrator.
The available options are:
|
| Proxy server | Text | Yes | (Empty) | PROXYSERVER="proxy.host.com" | The hostname (for example, server.domain.com) or IP address (for example, xxx.xxx.xxx.xxx) of the proxy server. |
| Proxy port | Text | Yes | 1028 | PROXYPORT="1000" | The
port to use to connect to the FTP server. Most standard
FTP servers operate on port 1028 (the default port specified), however,
this parameter can be customized in case the FTP server operates
on other ports. NOTE: Other default ports may be assigned
depending on the server connection type selected. |
| Use authentication | --- | --- | --- | --- | If
selected, specifies the connection to the proxy server requires
authentication (disabled by default). NOTE: This parameter does not contain markup and is only displayed in visual mode for task construction and configuration purposes. |
| Proxy username | Text | No | (Empty) | PROXYUSERNAME="username" | The username to use to authenticate with the proxy server. This option is only valid when Socks 5 is specified in the Proxy type as it is the only version that supports authentication. |
| Proxy password | Text | No | (Empty) | PROXYPASSWORD="encrypted" | The password to use to authenticate with the proxy server. When the step is created using the Task Builder it is written to the task encrypted. This option is only valid when Socks 5 is specified in the Proxy type as it is the only version that supports authentication. |
Additional notes
Public/private key encryption
In public/private key encryption, different keys are used to encrypt and decrypt information. The first key is a private key (a key that is known only to its owner), while the second key (called the public key) can be made known and available to other entities on the network. The two keys are different but complementary in function. For example, a user’s public key can be published in a certificate in a directory so that it is accessible to other people in the organization. The sender of a message can retrieve the user’s certificate from Active Directory, obtain the public key from the certificate, and then encrypt the message by using the recipient's public key. Information that is encrypted with the public key can be decrypted only by using the corresponding private key of the set, which remains with its owner, the recipient of the message.
When you authenticate with a public/private key pair using the SFTP (key) connection type, you have a private key on your computer, a key that only you have access to (this is crucial). The server to which you are connecting has a copy of your public key. This key is safe for anyone to have. When you logon using your key pair, the server sends a challenge, encrypted with your public key (to which it has access to, since you uploaded it to the appropriate place in your home directory). The only key that will unencrypt the challenge is your private key. Your SSH/SCP/SFTP program (in this case, Automate Desktop) does this, and the server then knows you are who you claim to be.
Examples
NOTE:
- Copy and paste the sample AML code below directly into the Task Builder Steps Panel.
- To successfully run the sample code, update parameters containing user credentials, files, file paths, or other information specific to the task to match your environment.
Example 1
This sample task will log onto an FTP site, download a single file, and then log off.
Copy
<AMFTP ACTIVITY="logon" SERVER="YourFTPHost" USERNAME="YourUsername" PASSWORD="AM1MoyAfpKHilpraHBIX6ei1E/2ZhM5egRHalje6g6YThM=aME" />
<AMFTP SOURCE="/home/ftp/filename.txt" DEST="C:\Temp\*.*" />
<AMFTP ACTIVITY="logoff" />Example 2
This sample task demonstrates the activities used to download files from one FTP server to another. The first two steps logs onto two separate FTP hosts and creates a unique session name for each connection. The third step performs the file transfer from one server to another. The last two steps are used to log off each FTP server. In order for this task to work in your environment, please make the appropriate modifications in the properties of each activity.
Copy
<AMFTP ACTIVITY="logon" SESSION="Server1Session" SERVER="ftp.server1.com" USERNAME="theuser" PASSWORD="AM2WknKdIcXr7JaSdh0lRfctA==aME" />
<AMFTP ACTIVITY="logon" SESSION="Server2Session" SERVER="ftp.server2.com" USERNAME="theuser" PASSWORD="AM2WknKdIcXr7JaSdh0lRfctA==aME" />
<AMFTP ACTIVITY="fxp" SOURCE="/Server1/myFolder/*.*" DEST="/Server2/myFolder/*.*" SUBFOLDERS="YES" KEEPFOLDERSTRUCT="YES" OVERWRITE="YES" RESULTDATASET="theDataset" SESSION="Server1Session" DESTINATIONSESSION="Server2Session" />
<AMFTP ACTIVITY="logoff" SESSION="Server1Session" />
<AMFTP ACTIVITY="logoff" SESSION="Server2Session" />