ftp-srv

Modern, extensible FTP Server

• Overview
• Features
• Install
• Usage
  • API
  • Events
  • Supported Commands
  • File System
• Contributing
• License

Overview

ftp-srv is a modern and extensible FTP server designed to be simple yet configurable.

Features

• Extensible file systems per connection
• Passive and active transfers
• Implicit TLS connections

Install

npm install ftp-srv --save

Usage

// Quick start

const FtpSvr = require('ftp-srv');
const ftpServer = new FtpSvr('ftp://0.0.0.0:9876', { options ... });

ftpServer.on('login', (data, resolve, reject) => { ... });
...

ftpServer.listen()
.then(() => { ... });

API

new FtpSrv(url, [{options}])

url

URL string indicating the protocol, hostname, and port to listen on for connections.
Supported protocols:

• ftp Plain FTP
• ftps Implicit FTP over TLS Note: The hostname must be the external IP address to accept external connections. Setting the hostname to 0.0.0.0 will automatically set the external IP.
  Default: "ftp://127.0.0.1:21"

options

• pasv_range

A starting port (eg 8000) or a range (eg "8000-9000") to accept passive connections.
This range is then queried for an available port to use when required.
Default: 22

• greeting

A human readable array of lines or string to send when a client connects.
Default: null

• tls

Node TLS secure context object used for implicit ftps.
Default: {}

• anonymous

If true, will call the event login after USER, not requiring a password from the user.
Default: false

• blacklist

Array of commands that are not allowed.
Response code 502 is sent to clients sending one of these commands.
Example: ['RMD', 'RNFR', 'RNTO'] will not allow users to delete directories or rename any files.
Default: []

• whitelist

Array of commands that are only allowed.
Response code 502 is sent to clients sending any other command.
Default: []

• file_format

Sets the format to use for file stat queries such as LIST.
Default: "ls"
Allowable values:

• ls bin/ls format

• ep Easily Parsed LIST format

• function () {} A custom function returning a format or promise for one.

  • Only one argument is passed in: a node file stat object with additional file name parameter

• log

A bunyan logger instance. Created by default.

Events

The FtpSvr class extends the node net.Server. Some custom events can be resolved or rejected, such as login.

login

on('login', {connection, username, password}, resolve, reject) => { ... }

Occurs when a client is attempting to login. Here you can resolve the login request by username and password.
resolve takes an object of arguments:

• fs
  • Set a custom file system class for this connection to use.
  • See File System for implementation details.
• root
  • If fs is not provided, this will set the root directory for the connection.
  • The user cannot traverse lower than this directory.
• cwd
  • If fs is not provided, will set the starting directory for the connection
  • This is relative to the root directory.
• blacklist
  • Commands that are forbidden for only this connection
• whitelist
  • If set, this connection will only be able to use the provided commands

reject takes an error object

client-error

on('client-error', {connection, context, error}) => { ... }

Occurs when an error occurs in the client connection.

Supported Commands

See commands for a list of all implemented FTP commands.

File System

The default file system can be overwritten to use your own implementation.
This can allow for virtual file systems, and more.
Each connection can set it's own file system based on the user.

Custom file systems can implement the following variables depending on the developers needs.

Methods

currentDirectory()

Returns a string of the current working directory
Used in: PWD

get(fileName)

Returns a file stat object of file or directory
Used in: STAT, SIZE, RNFR, MDTM

list(path)

Returns array of file and directory stat objects

Used in: LIST, STAT

chdir(path)

Returns new directory relative to current directory
Used in: CWD, CDUP

mkdir(path)

Returns a path to a newly created directory
Used in: MKD

write(fileName, {append = false})

Returns a writable stream
Options: append if true, append to existing file
Used in: STOR, APPE

read(fileName)

Returns a readable stream
Used in: RETR

delete(path)

Delete a file or directory
Used in: DELE

rename(from, to)

Rename a file or directory
Used in: RNFR, RNTO

chmod(path)

Modify a file or directory's permissions
Used in: SITE CHMOD

getUniqueName()

Returns a unique file name to write to
Used in: STOU

Contributing

See CONTRIBUTING.md.

License

This software is licensed under the MIT Licence. See LICENSE.