# FTPd : FTP server

This module provides a multi-user FTP server. This module is valid in EdgerOS 2.1.7 and above.

User can use the following code to import the FTPd module.

var FTPd = require('ftpd');

EdgerOS apps needs permission.network permission to use this module. For details, please refer to permission.

# Support

The following shows FTPd module APIs available for each permissions.

# FTPd Class

# new FTPd(options)

• options {Object} FTP server options.
• Returns: {Object} Returns FTP object.

Create an FTP server with specified options. The options parameter can contain the following members:

• flt {Function} User login filter.
• tls {Object} If using SSL/TLS, you need to specify the certificate, see TLS. Optional.
• cnf {Object} Server configuration. Optional.
  • addr {String} FTP server binding local IP address. Optional. default: '0.0.0.0'.
  • port {Integer} FTP server port. Optional default: 21.
  • securePort {Integer} FTPS server port. Optional. default: 990.
  • maxConnections {Integer} Maximum number of connections. Optional default: 10.
  • basefolder {String} Default base folder path. Optional default: /.
• hdl {Object} Hooks. Optional.
  • upload {Function} File upload hook. Optional.
  • download {Function} File download hook. Optional.
  • remove {Function} File or folder remove hook. Optional.
  • rename {Function} File or folder rename hook. Optional.

# Example

var ftp = new FTPd({ cnf: { port: 4000 }}); // Create FTP server with port 4000

The cnf.securePort indicates the unconditional mode FTP TLS server port. If set to 0, it means that the unconditional mode FTP TLS server will not be created. This configuration does not affect the negotiated FTP TLS server (RFC 2228). As long as the tls parameter is specified, server created using cnf.port parameter run negotiated upgrade to FTP TLS connection.

The user login filter function type is as follows:

• username {String} User login name.
• Returns: {Object} Returns this user configuration, If there is no such user, undefined is returned.

The returned user configuration can contain the following information:

• password {String} This user login password.
• basefolder {String} Base folder specified by this user.
• allowLoginWithoutPassword {Boolean} Whether to allow login without password. Optional default: false.
• allowUserFileCreate {Boolean} Whether to allow file creation. Optional default: true.
• allowUserFileRetrieve {Boolean} Whether to allow file retrieval. Optional default: true.
• allowUserFileOverwrite {Boolean} Whether to allow file overwrite. Optional default: true.
• allowUserFileDelete {Boolean} Whether to allow deletion of files. Optional default: true.
• allowUserFolderDelete {Boolean} Whether to allow folder creation. Optional default: true.
• allowUserFolderCreate {Boolean} Whether to allow deletion of folder. Optional default: true.

# Example

var users = {
  jack: { password: '123', basefolder: '/jack' },
  rose: { password: '456', basefolder: '/rose', allowUserFileDelete: false }
};
var ftp = new FTPd({
  flt: username => users[username]
});

The hook functions:

# hdl.upload(username, filePath)

• username {String} User login name.
• filePath {String} Full file path.
• Returns: {Boolean | Promise} Whether to allow uploading.

# hdl.download(username, filePath)

• username {String} User login name.
• filePath {String} Full file path.
• Returns: {Boolean | Promise} Whether to allow download.

# hdl.remove(username, filePath)

• username {String} User login name.
• filePath {String} Full file path.
• Returns: {Boolean | Promise} Whether to allow remove.

# hdl.rename(username, from, to)

• username {String} User login name.
• from {String} Original Full file or folder name.
• to {String} Target Full file or folder name.
• Returns: {Boolean | Promise} Whether to allow rename.

# Example

// Synchronize
var ftp = new FTPd({
  hdl: {
    remove: (username, filePath) => {
      return: false; // Delete not allowed
    }
  }
});

// Asynchronous
var ftp = new FTPd({
  hdl: {
    remove: async (username, filePath) => {
      return: false; // Delete not allowed
    }
  }
});

# FTPd Object

# ftpd.start()

Start the FTP server, an exception will be thrown on error.

# ftpd.stop()

Stop FTP server.

# ftpd.kick([username])

• username {String} User name.

Disconnect the current connection of the specified user, If username is undefined, disconnect all currently connection. If username is 'anonymous', it means disconnecting all anonymous user links.

# FTPd Events

The FTPd object inherits from the EventEmitter class. The following events are thrown in some specific situations.

# login

• info {Object}
  • username {String} User name.
  • address {String} User address.
  • total {Integer} Current total number of connections.

This event generated when the user login successfully.

# logout

• info {Object}
  • username {String} User name.
  • address {String} User address.
  • total {Integer} Current total number of connections.

This event generated when the user logout successfully.

# log

• msg {String}

Current log information generated by the FTP server.

# debug

• msg {String}

Current debug information generated by the FTP server.

log and debug can be used for debugging output. These event will slow down the server. It is recommended not to use this event in official products.