Network Component  Version 6.7.7
MDK-Professional Middleware for IP Networking
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:

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:

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.
switch (event) {
// User logged in, session is busy
break;
// User logged out, session is idle
break;
// User login failed (invalid credentials)
break;
// File download ended
break;
// File upload ended
break;
// File deleted
break;
// File or directory renamed
break;
// Directory created
break;
// Directory removed
break;
// Requested file operation denied
break;
// Local file operation error
break;
// Generic file operation error
// 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.