ftp-srv

Modern, extensible FTP Server

---

Overview

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

Features

• Extensible file systems per connection
• Passive and active transfers
• Explicit & Implicit TLS connections
• Promise based API

Install

Usage

API

new FtpSrv({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.

will listen on any available hosts for server and passive connections.
Default:

"ftp://127.0.0.1:21"

pasv_url

provides an IP address to the client when a

PASV

command is received in the handshake for a passive connection. Reference PASV verb. This can be one of two options:

• A function which takes one parameter containing the remote IP address of the FTP client. This can be useful when the user wants to return a different IP address depending if the user is connecting from Internet or from an LAN address. Example:

• A static IP address (ie. an external WAN IP address that the FTP server is bound to). In this case, only connections from localhost are handled differently returning
  127.0.0.1
  to the client.

If not provided, clients can only connect using an

connection.

pasv_min

The starting port to accept passive connections.
Default:

pasv_max

The ending port to accept passive connections.
The range is then queried for an available port to use when required.
Default:

greeting

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

tls

Node TLS secure context object used for implicit (

protocol) or explicit (

AUTH TLS

) connections.
Default:

false

anonymous

If true, will allow clients to authenticate using the username

, not requiring a password from the user.
Can also set as a string which allows users to authenticate using the username provided.
The

login

event is then sent with the provided username and

@anonymous

as the password.
Default:

false

blacklist

Array of commands that are not allowed.
Response code

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

is sent to clients sending any other command.
Default:

[]

file_format

Sets the format to use for file stat queries such as

.
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.

timeout

Sets the timeout (in ms) after that an idle connection is closed by the server
Default:

CLI

also comes with a builtin CLI.

url

Set the listening URL.

Defaults to

--pasv_url

The hostname to provide a client when attempting a passive connection (

).
If not provided, clients can only connect using an

Active

connection.

--pasv_min

The starting port to accept passive connections.
Default:

--pasv_max

The ending port to accept passive connections.
The range is then queried for an available port to use when required.
Default:

--root

/

-r

Set the default root directory for users.

Defaults to the current directory.

--credentials

/

-c

Set the path to a json credentials file.

Format:

--username

Set the username for the only user. Do not provide an argument to allow anonymous login.

--password

Set the password for the given

.

--read-only

Disable write actions such as upload, delete, etc.

Events

The

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

login

.

client-error

Occurs when an error arises in the client connection.

client class object

context

string of where the error occurred

error

error object

disconnect

Occurs when a client has disconnected.

client class object

id

string of the disconnected connection id

id

number of the new connection count (exclusive the disconnected client connection)

closed

Occurs when the FTP server has been closed.

closing

Occurs when the FTP server has started closing.

login

Occurs when a client is attempting to login. Here you can resolve the login request by username and password.

client class object

username

string of username from

USER

command

password

string of password from

PASS

command

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

takes an error object

server-error

Occurs when an error arises in the FTP server.

error object

RETR

Occurs when a file is downloaded.

if successful, will be

null

filePath

location to which file was downloaded

STOR

Occurs when a file is uploaded.

if successful, will be

null

fileName

name of the file that was uploaded

RNTO

Occurs when a file is renamed.

if successful, will be

null

fileName

name of the file that was renamed

Supported Commands

See the command registry 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.

The default file system is exported and can be extended as needed:

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:

get(fileName)

Returns a file stat object of file or directory
Used in:

,

NLST

,

STAT

,

SIZE

,

RNFR

,

MDTM

list(path)

Returns array of file and directory stat objects
Used in:

,

NLST

,

STAT

chdir(path)

Returns new directory relative to current directory
Used in:

,

CDUP

mkdir(path)

Returns a path to a newly created directory
Used in:

write(fileName, {append, start})

Returns a writable stream
Options:

if true, append to existing file

start

if set, specifies the byte offset to write to
Used in:

STOR

,

APPE

read(fileName, {start})

Returns a readable stream
Options:

if set, specifies the byte offset to read from
Used in:

RETR

delete(path)

Delete a file or directory
Used in:

rename(from, to)

Renames a file or directory
Used in:

,

RNTO

chmod(path)

Modifies a file or directory's permissions
Used in:

getUniqueName(fileName)

Returns a unique file name to write to. Client requested filename available if you want to base your function on it. Used in:

Contributing

See CONTRIBUTING.md.

License

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

References

• https://cr.yp.to/ftp.html