FTP Server

File Transfer Protocol (FTP) is a standard network protocol used to exchange and manipulate files over a TCP/IP-based network. FTP is built on a client-server architecture and utilizes separate control and data connections between the client and server applications. FTP is used with user-based password authentication or with anonymous user access.

FTP file manipulation means that you can: create and delete files on FTP server, rename files, create folders and subfolders, print the folder listings, etc.

FTP applications were originally interactive command-line tools with a standardized command syntax. Various graphical user interfaces have been developed for all types of operating systems in use today.

FTP can be run in active or in passive mode, which control how the data connection is opened. The mode of operation is defined by the command, received from the client.

• In active mode the client sends the server the IP address port number that the client will use for the data connection, and the server opens the connection.
• In passive mode the server sends the client an IP address and port number and the client opens the connection to the server. This mode is used, when the client is located behind a firewall and unable to accept incoming TCP connection.

An embedded FTP Server can also be used to upload HTTP Web pages or to download log files to a remote PC. In this case, the File System Component must be used, and the Embedded Web Server must be properly configured.

Supported Features

The Embedded FTP server has integrated several advanced features:

• Access Filtering allows you to filter out the hosts, which are not allowed to connect to the FTP Server.
• Multi-user Authentication allows you to add additional user accounts and different access rights for each user.
• User Application Notification sends notification about events in FTP server to the user application.

File System Interface

The Embedded FTP Server can store files in a generic File System. All interface functions are located in FTP_Server_FS.c, which will be automatically added to your project's Network folder. The file is preconfigured for the File System Component, so no modifications are required. If you want to use another type of file system or to use a different storage media such as a hard disk, you need to add a similar file to your project.

The following functions are implemented in this module:

• ftp_server_fopen - open a file for reading or writing.
• ftp_server_fclose - close a file that was previously opened.
• ftp_server_fread - read a block of data from a file to the FTP data buffer.
• ftp_server_fwrite - write a block of data from the FTP data buffer to a file.
• ftp_server_fdelete - delete a specified file.
• ftp_server_frename - rename a file from old to a new name.
• ftp_server_ffind - find a file in a folder for printing a directory listing.

Access Filtering

For access filtering the function ftp_accept_client is used. It is part of the file FTP_Server_Access.c. You need to adapt the function to the application's needs.

Code Example FTP_Server_Access.c

#include "rl_net.h"
 
// Accept or deny connection from remote FTP client.
// If this function is missing, all remote clients are accepted.
bool ftp_accept_client (const uint8_t *ip_addr, uint16_t port) {
  /* Example
  if (ip_addr[0] == 192  &&
      ip_addr[1] == 168  &&
      ip_addr[2] == 0    &&
      ip_addr[3] == 1) {
    // Accept connection.
    return (true);
  }
  // Deny connection.
  return (false);
  */
  return (true);
}

Multi-user Authentication

The multi-user login allows you to create different profiles for different users or groups of users. The profiles define the access rights to different files on the FTP server. The users which are allowed to access the FTP server are stored in an user database.

If you want to use multi-user authentication, you check the Enable User Authentication in the Net_Config_FTP_Server.h configuration file. The default account defined in the Net_Config_FTP_Server.h file is a system administrator account, which has no restrictions. All other accounts are created in a separate FTP_Server_Multiuser.c module. To add the module to your project, simply right-click on the Source group, select Add Net Item to Group, then click on User Code Template and scroll in the template files list until you find the FTP Server Multi-user template. To enable a list of users, you need to adapt the following functions that are included in this module:

• ftp_check_username - checks if the user account exists for the provided credentials.
• ftp_check_password - checks if the password fits to the user account for the provided credentials.
• ftp_file_access - check if the access to the file is allowed for a provided user.

The following function is included in the Network Component library rl_net.h:

• ftp_get_user_id - retrieves the user identification number for the user, which is trying to access the file or folder.

Code Example FTP_Server_Multiuser.c

#include <string.h>
#include "rl_net.h"
 
// Check if an user account exist in the user database.
uint8_t ftp_check_username (const char *username) {
  /* Example
  if (strcmp (username, "guest") == 0) {
    // Username is correct
    return (1);
  }
  */
  return (0);
}
 
// Check user account password in the user database.
bool ftp_check_password (uint8_t user_id, const char *password) {
  /* Example
  if (user_id == 1) {
    if (strcmp (password, "guest") == 0) {
      // Password is correct
      return (true);
    }
  }
  */
  return (false);
}
 
// Check if remote user is allowed to access a file on FTP server.
bool ftp_file_access (uint8_t user_id, const char *fname, uint8_t mode) {
  /* Example
  if (user_id == 1) {
    if ((strcmp (fname, "test.txt") == 0) && (mode == 1)) {
      // User "guest" is not allowed to modify or delete "test.txt"
      return (false);
    }
  }
  */
  return (true);
}

Note

• If the FTP_Server_Multiuser.c is not added to the project, but Authentication is enabled, the FTP server runs in single user authentication mode.
• You can disable a system administrator account, if you define an empty string for the Authentication Username.

User Application Notification

In case you need to notify your application about events that are happening on the FTP server, the function ftp_server_notify is to be used. It is part of the file FTP_Server_Event.c. You need to adapt the function to the application's needs.

Code Example FTP_Server_Event.c

#include "rl_net.h"
 
// Notify the user application about events in FTP server service.
void ftp_server_notify (ftpServerEvent event) {

  switch (event) {
    case ftpServerLogin:
      // User logged in, session is busy
      break;

    case ftpServerLogout:
      // User logged out, session is idle
      break;

    case ftpServerLoginFailed:
      // User login failed (invalid credentials)
      break;

    case ftpServerDownload:
      // File download ended
      break;

    case ftpServerUpload:
      // File upload ended
      break;

    case ftpServerDelete:
      // File deleted
      break;

    case ftpServerRename:
      // File or directory renamed
      break;

    case ftpServerMakeDirectory:
      // Directory created
      break;

    case ftpServerRemoveDirectory:
      // Directory removed
      break;

    case ftpServerOperationDenied:
      // Requested file operation denied
      break;

    case ftpServerLocalFileError:
      // Local file operation error
      break;

    case ftpServerFileError:
      // Generic file operation error

    case ftpServerError:
      // Generic FTP server error
      break;
  }
}

Supported FTP Commands

The Network Component's FTP Server supports only a subset of standard FTP Commands. The following FTP Commands are supported:

Code	Command	Description
USER	User Name	Starts login with name identifying the user.
PASS	Password	Continues login with the user's password.
QUIT	Logout	Closes the user connection.
SYST	System	Identifies the operating system at the server.
NOOP	No Operation	Sends an OK reply.
XNOP	No Operation	Same as NOOP
PWD	Print Working Directory	Returns the name of the current working directory.
XPWD	Print Working Directory	Same as PWD
CWD	Change Working Directory	Changes the current working directory of the user.
XCWD	Change Working Directory	Same as CWD
CDUP	Change Directory Up	Changes working directory to the parent of the current directory.
XCUP	Change Directory Up	Same as CDUP
MKD	Make Directory	Creates a sub directory in the current working directory.
XMKD	Make Directory	Same as MKD
RMD	Remove Directory	Removes the directory.
XRMD	Remove Directory	Same as RMD
TYPE	Representation Type	Supports ASCII and Image types.
PORT	Data Port	Specifies the data port to be used in data connection.
PASV	Passive	Requests the server to listen on a data port and wait for a connection.
LIST	List	Sends a directory listing to the user.
NLST	Name List	Sends a directory listing to the user.
RETR	Retrieve	Sends a file content to the user.
STOR	Store	Saves a captured user file on server.
APPE	Append	Appends a captured user file to an existing file on server.
DELE	Delete	Deletes a specified file from server.
RNFR	Rename From	Specifies the name of existing file to rename (must be followed by RNTO).
RNTO	Rename To	Renames an existing file to new name.
HELP	Help	Returns a list of supported commands.
SIZE	Size	Returns the size of a specified file.
MDTM	Last-modified Time	Returns last-modified time of a specified file.

FTP Server Configuration

FTP Server Configuration File

The FTP server configuration file Net_Config_FTP_Server.h contains the following settings:

• Number of FTP Sessions specifies the number of available FTP sessions. The default value is one, and this enables only one concurrent client connection. You should increase this number if multiple FTP clients must connect to the FTP server at the same time. If you are using Windows Explorer as a FTP client, you should also increase this number because Windows Explorer creates multiple simultaneous connections.
• Port Number specifies the listening TCP port number. The default FTP server listening port is 21.
• Welcome Message specifies the custom FTP server welcome message. This message is sent to the user on login. When this option contains an empty string, a default Welcome Message from the library is used instead.
• Idle Session Timeout in seconds specifies the interval of user inactivity, after which the connection is automatically closed. During an idle session, no TCP frames are exchanged. A value of 0 disables a disconnection on timeout.
• The Enable User Authentication switch enables or disables authentication with a username and a password.
  • Authentication Realm is the string which is displayed in the browser's authentication dialogue if an authentication is required. This is a zero terminated string.
  • Authentication Username is the username for authentication.
  • Authentication Password is the default password, that must be stored in non-volatile memory. The user can change the password later.

Note

One FTP session uses two TCP sockets, one control and one data socket. Have this in mind when you are configuring the number of TCP sockets.