Chapter 1 - Introduction to Azure RTOS NetX FTP

The File Transfer Protocol (FTP) is a protocol designed for file transfers. FTP utilizes reliable Transmission Control Protocol (TCP) services to perform its file transfer function. Because of this, FTP is a highly reliable file transfer protocol. FTP is also high-performance. The actual FTP file transfer is performed on a dedicated FTP connection.

FTP Requirements

In order to function properly, the Azure RTOS NetX FTP package requires that a NetX IP instance has already been created. In addition, TCP must be enabled on that same IP instance. The FTP Client portion of the NetX FTP package has no further requirements.

The FTP Server portion of the NetX FTP package has several additional requirements. First, it requires complete access to TCP well-known port 21 for handling all Client FTP command requests and well-known port 20 for handling all Client FTP data transfers. The FTP Server is also designed for use with the FileX embedded file system. If FileX is not available, the user may port the portions of FileX used to their own environment. This is discussed in later sections of this guide.

FTP Constraints

The FTP standard has many options regarding the representation of file data. Similar to Unix implementations, NetX FTP assumes the following file format constraints:

  • File Type: Binary
  • File Format: Nonprint Only
  • File Structure: File Structure Only
  • Transmission Mode: Stream Mode Only

FTP File Names

FTP file names should be in the format of the target file system (usually FileX). They should be NULL terminated ASCII strings, with full path information if necessary. There is no specified limit for the size of FTP file names in the NetX FTP implementation. However, the packet pool payload size should be able to accommodate the maximum path and/or file name.

FTP Client Commands

The FTP has a simple mechanism for opening connections and performing file and directory operations. There is basically a set of standard FTP commands that are issued by the Client after a connection has been successfully established on the TCP well-known port 21. The following shows some of the basic FTP commands:

FTP Command and Meaning

  • CWD path: Change working directory
  • DELE filename: Delete specified file name
  • LIST directory: Get directory listing
  • MKD directory: Make new directory
  • NLST directory: Get directory listing
  • NOOP: No operation, returns success
  • PASS password: Provide password for login
  • PASV: Request passive transfer mode
  • PWD path: Pickup current directory path
  • QUIT: Terminate Client connection
  • RETR filename: Read specified file
  • RMD directory: Delete specified directory
  • RNFR oldfilename: Specify file to rename
  • RNTO newfilename: Rename file to supplied file name
  • STOR filename: Write specified file
  • TYPE I: Select binary file image
  • USER username: Provide username for login
  • PORT ip_address,port: Provide IP address and Client data port

These ASCII commands are used internally by the NetX FTP Client software to perform FTP operations with the FTP Server.

FTP Server Responses

The FTP Server utilizes the well-known TCP port 21 to field Client command requests. Once the FTP Server processes the Client command, it returns a 3-digit numeric response in ASCII followed by an optional ASCII string. The numeric response is used by the FTP Client software to determine whether the operation succeeded or failed. The following lists various FTP Server responses to Client commands:

First Numeric Field and Meaning

  • 1xx: Positive preliminary status – another reply coming.
  • 2xx: Positive completion status.
  • 3xx: Positive preliminary status – another command must be sent.
  • 4xx: Temporary error condition.
  • 5xx: Error condition.

Second Numeric Field and Meaning

  • x0x: Syntax error in command.
  • x1x: Informational message.
  • x2x: Connection related.
  • x3x: Authentication related.
  • x4x: Unspecified.
  • x5x: File system related.

For example, a Client request to disconnect an FTP connection with the QUIT command will typically be responded with a "221" code from the Server – if the disconnect is successful.

FTP Passive Transfer Mode

By default, the NetX FTP Client uses the active transport mode to exchange data over the data socket with the FTP server. The problem with this arrangement is that it requires the FTP Client to open a TCP server socket for the FTP Server to connect to. This represents a possible security risk and may be blocked by the Client firewall. Passive transfer mode differs from active transport mode by having the FTP server create the TCP server socket on the data connection. This eliminates the security risk (for the FTP Client).

To enable passive data transfer, the application calls nx_ftp_client_passive_mode_set on a previously created FTP Client with the second argument set to NX_TRUE. Thereafter, all subsequent NetX FTP Client services for transferring data (NLST, RETR, STOR) are attempted in the passive transport mode.

The FTP Client first sends the PASV command (no arguments). If the FTP server supports this request it will return the 227 "OK" response. Then the Client sends the request e.g. RETR. If the server refuses passive transfer mode, the NetX FTP Client service returns an error status.

To disable passive transport mode and return to active transport mode, the application calls nx_ftp_client_passive_mode_set with the second argument set to NX_FALSE.

FTP Communication

The FTP Server utilizes the well-known TCP port 21 to field Client requests. FTP Clients may use any available TCP port. The general sequence of FTP events is as follows:

FTP Read File Requests

  1. Client issues TCP connect to Server port 21.
  2. Server sends "220" response to signal success.
  3. Client sends "USER" message with "username."
  4. Server sends "331" response to signal success.
  5. Client sends "PASS" message with "password."
  6. Server sends "230" response to signal success.
  7. Client sends "TYPE I" message for binary transfer.
  8. Server sends "200" response to signal success.
  9. Client sends "PORT" message with IP address and port.
  10. Server sends "200" response to signal success.
  11. Client sends "RETR" message with file name to read.
  12. Server creates data socket and connects with client data port specified in the "PORT" command.
  13. Server sends "125" response to signal file read has started.
  14. Server sends contents of file through the data connection. This process continues until file is completely transferred.
  15. When finished, Server disconnects data connection.
  16. Server sends "250" response to signal file read is successful.
  17. Clients sends "QUIT" to terminate FTP connection.
  18. Server sends "221" response to signal disconnect is successful.
  19. Server disconnects FTP connection.

As mentioned previously, the only difference between FTP running over IPv4 and IPv6 is the PORT command is replaced with the EPRT command for IPv6

If the FTP Client makes a read request in the passive transfer mode, the command sequence is as follows (bolded lines indicates a different step from active transfer mode):

  1. Client issues TCP connect to Server port 21.
  2. Server sends "220" response to signal success.
  3. Client sends "USER" message with "username."
  4. Server sends "331" response to signal success.
  5. Client sends "PASS" message with "password."
  6. Server sends "230" response to signal success.
  7. Client sends "TYPE I" message for binary transfer.
  8. Server sends "200" response to signal success.
  9. Client sends "PASV" message.
  10. Server sends "227" response, and IP address and port for the Client to connect to, to signal success.
  11. Client sends "RETR" message with file name to read.
  12. Server creates data server socket and listens for the Client connect request on this socket using the port specified in the "227" response.
  13. Server sends "150" response on the control socket to signal file read has started.
  14. Server sends contents of file through the data connection. This process continues until file is completely transferred.
  15. When finished, Server disconnects data connection.
  16. Server sends "226" response on the control socket to signal file read is successful.
  17. Client sends "QUIT" to terminate FTP connection.
  18. Server sends "221" response to signal disconnect is successful.
  19. Server disconnects FTP connection.

FTP Write Requests

  1. Client issues TCP connect to Server port 21.
  2. Server sends "220" response to signal success.
  3. Client sends "USER" message with "username."
  4. Server sends "331" response to signal success.
  5. Client sends "PASS" message with "password."
  6. Server sends "230" response to signal success.
  7. Client sends "TYPE I" message for binary transfer.
  8. Server sends "200" response to signal success.
  9. Client sends "PORT" message with IP address and port.
  10. Server sends "200" response to signal success.
  11. Client sends "STOR" message with file name to write.
  12. Server creates data socket and connects with client data port specified in the "PORT" command.
  13. Server sends "125" response to signal file write has started.
  14. Client sends contents of file through the data connection. This process continues until file is completely transferred.
  15. When finished, Client disconnects data connection.
  16. Server sends "250" response to signal file write is successful.
  17. Clients sends "QUIT" to terminate FTP connection.
  18. Server sends "221" response to signal disconnect is successful.
  19. Server disconnects FTP connection.

If the FTP Client makes a write request in the passive transfer mode, the command sequence is as follows (bolded lines indicates a different step from active transfer mode):

  1. Client issues TCP connect to Server port 21.
  2. Server sends "220" response to signal success.
  3. Client sends "USER" message with "username."
  4. Server sends "331" response to signal success.
  5. Client sends "PASS" message with "password."
  6. Server sends "230" response to signal success.
  7. Client sends "TYPE I" message for binary transfer.
  8. Server sends "200" response to signal success.
  9. Client sends "PASV" message.
  10. Server sends "227" response, and IP address and port for the Client to connect to, to signal success.
  11. Client sends "STOR" message with file name to write.
  12. Server creates data server socket and listens for the Client connect request on this socket using the port specified in the "227" response.
  13. Server sends "150" response on the control socket to signal file write has started.
  14. Client sends contents of file through the data connection. This process continues until file is completely transferred.
  15. When finished, Client disconnects data connection.
  16. Server sends "226" response on the control socket to signal file write is successful.
  17. Client sends "QUIT" to terminate FTP connection.
  18. Server sends "221" response to signal disconnect is successful.
  19. Server disconnects FTP connection.

FTP Authentication

Whenever an FTP connection takes place, the Client must provide the Server with a username and password. Some FTP sites allow what is called Anonymous FTP, which allows FTP access without a specific username and password. For this type of connection, "anonymous" should be supplied for username and the password should be a complete e-mail address.

The user is responsible for supplying NetX FTP with login and logout authentication routines. These are supplied during the nx_ftp_server_create function and called from the password processing. If the login function returns NX_SUCCESS, the connection is authenticated and FTP operations are allowed. Otherwise, if the login function returns something other than NX_SUCCESS, the connection attempt is rejected.

FTP Multi-Thread Support

The NetX FTP Client services can be called from multiple threads simultaneously. However, read or write requests for a particular FTP Client instance should be done in sequence from the same thread.

FTP RFCs

NetX FTP is compliant with RFC959 and related RFCs.