ftp-srv

Modern, extensible FTP Server

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

Overview

ftp-srv is designed to be easy, exensible, and modern.
Configuration is very minimal for a basic FTP server, but can easily grow to fit a larger scale project.

Features

• Supports passive and active connections
• Allows extensible file systems on a per connection basis

Install

npm install ftp-srv --save

Usage

// Quick start

const FtpSvr = require('ftp-srv');
const ftpServer = new FtpSvr(url, [{ options ... }]);

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

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

API

new FtpSrv(url, [options])

• url :: ftp://127.0.0.1:21
  • A full href url, indicating the protocol, and external IP with port to listen for connections.
  • Supported protocols:
    • ftp
  • To accept external connections, the hostname must be the box's external IP address. This can be fetched automatically by setting the hostname to 0.0.0.0.
• options :: {}
  • pasv_range :: 22
    • Starting port or min - max range to accept passive connections
      • Ports will be queried for an unused port in the range to use for the connection.
      • If none are found, the connection cannot be established
    • If an integer is supplied: will indicate the minimum allowable port
    • If a range is defined (3000-3100): only ports within that range will be used
  • anonymous :: false
    • If true, will authenticate connections after passing the USER command. Passwords will not be required.
  • blacklist :: []
    • Array of commands to be blacklisted globally
      • ['RMD', 'RNFR', 'RNTO']
    • A connection sending one of these commands will be replied with code 502
  • whitelist :: []
    • If set, only commands within this array are allowed
    • A connection sending any other command will be replied to with code 502
  • file_format :: ls
    • Set the format to use for file stat queries, such as LIST
    • Possible values include:
      • ls : bin/ls format
      • ep : Easily Parsed LIST format
      • Function : pass in a function as the parameter to use your own
        • Only one argument is passed in: a node file stat object with additional file name parameter
  • log :: bunyan.createLogger()
    • A bunyan logger instance
    • By default, one is created, but a custom instance can be passed in as well

Events

"login" ({connection, username, password}, resolve, reject)

Occurs after PASS command is set, or after USER if anonymous is true

• connection
  • Instance of the FTP client
• username
  • Username provided in the USER command
• password
  • Password provided in the PASS command
  • Only provided if anonymous is set to false
• resolve ({fs, root, cwd, blacklist, whitelist})
  • fs [optional]
    • Optional file system class for connection to use
    • See File System for implementation details
  • root [optional]
    • If fs not provided, will set the root directory for the connection
    • The user cannot traverse lower than this directory
  • cwd [optional]
    • If fs not provided, will set the starting directory for the connection
  • blacklist [optional]
    • Commands that are forbidden for this connection only
  • whitelist [optional]
    • If set, this connection will only be able to use the provided commands
• reject (error)
  • error
    • Error object

File System

The default file system can be overriden to use your own implementation. This can allow for virtual file systems and more.
Each connection can be given it's own file system depending on the user.

Functions

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 cwd

Used in CWD, CDUP

mkdir(path)
Returns a path to a newly created directory

Used in MKD

write(fileName, options)
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.