Modern, extensible FTP server (daemon) for Node.js with ESM support. Based on ftp-srv.
npm install ftp-srv-esmnpm install ftp-srv-esm
js
// Quick start, create an active ftp server.
import FtpSrv from 'ftp-srv-esm';
const ftpServer = new FtpSrv({
url: "ftp://0.0.0.0:21,
anonymous: false
});
ftpServer.on('login', ({ connection, username, password }, resolve, reject) => {
if(username === 'john' && password === 'doe'){
return resolve({ root: '/' });
}
return reject(new errors.GeneralError('Invalid username or password', 401));
});
ftpServer.listen().then(() => {
console.log('FTP server is starting...')
});
`
API
$3
#### 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. 0.0.0.0 will listen on any available hosts for server and passive connections.
__Default:__ "ftp://127.0.0.1:21"
#### pasv_hostname
ftp-srv-esm 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:
`js
import os from 'os';
import { Netmask } from 'netmask';
import FtpSrv from 'ftp-srv-esm';
const nets = os.networkInterfaces();
function getNetworks() {
let networks = {};
for (const name of Object.keys(nets)) {
for (const net of nets[name]) {
if (net.family === 'IPv4' && !net.internal) {
networks[net.address + "/24"] = net.address;
}
}
}
return networks;
}
const resolverFunction = (address) => {
// const networks = {
// '$GATEWAY_IP/32': ${public_ip},
// '10.0.0.0/8' : ${lan_ip}
// }
const networks = getNetworks();
for (const network in networks) {
if (new Netmask(network).contains(address)) {
return networks[network];
}
}
return '127.0.0.1';
};
new FtpSrv({pasv_hostname: resolverFunction});
`
- 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, the server will attempt to fetch and use the WAN IP for passive mode transfers.
#### wan_ip_check_url
The URL to use for automatic WAN IP detection when pasv_hostname is not provided. This is useful when deploying the server in different environments that may need alternative IP detection services.
__Default:__ "https://checkip.amazonaws.com"
#### pasv_min
The starting port to accept passive connections.
__Default:__ 1024
#### pasv_max
The ending port to accept passive connections.
The range is then queried for an available port to use when required.
__Default:__ 65535
#### 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 protocol) or explicit (AUTH TLS) connections.
__Example:__ { key: readFileSync('server.key'), cert: readFileSync('server.crt'), ca: readFileSync('server.csr') }
__Default:__ false
#### anonymous
If true, will allow clients to authenticate using the username anonymous, 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 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:__ []
#### list_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 winston logger instance. Created by default.
#### timeout
Sets the timeout (in ms) after that an idle connection is closed by the server
__Default:__ 0
#### endOnProcessSignal
Whether to close ftp server and exit process on SIGTERM/SIGINT/SIGQUIT signals or not
__Default:__ true
CLI
ftp-srv-esm also comes with a builtin CLI.
`bash
$ ftp-srv [url] [options]
`
`bash
$ ftp-srv-esm ftp://0.0.0.0:9876 --root ~/Documents
`
#### url
Set the listening URL.
Defaults to ftp://127.0.0.1:21
#### --pasv_hostname
The hostname to provide a client when attempting a passive connection (PASV).
If not provided, clients can only connect using an Active connection.
#### --pasv_min
The starting port to accept passive connections.
__Default:__ 1024
#### --pasv_max
The ending port to accept passive connections.
The range is then queried for an available port to use when required.
__Default:__ 65535
#### --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:
`js
[
{
"username": "...",
"password": "...",
"root": "..." // Root directory
},
...
]
`
#### --username
Set the username for the only user. Do not provide an argument to allow anonymous login.
#### --password
Set the password for the given username.
#### --read-only
Disable write actions such as upload, delete, etc.
Events
The FtpSrv class extends the node net.Server. Some custom events can be resolved or rejected, such as login.
$3
`js
import FtpSrv from 'ftp-srv-esm';.on('client-error', ({connection, context, error}) => { ... });
`
Occurs when an error arises in the client connection.
connection client class object
context string of where the error occurred
error error object
$3
`js
ftpServer.on('disconnect', ({connection, id, newConnectionCount}) => { ... });
`
Occurs when a client has disconnected.
connection client class object
id string of the disconnected connection id
id number of the new connection count (exclusive the disconnected client connection)
$3
`js
ftpServer.on('closed', ({}) => { ... });
`
Occurs when the FTP server has been closed.
$3
`js
ftpServer.on('closing', ({}) => { ... });
`
Occurs when the FTP server has started closing.
$3
`js
ftpServer.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.
connection 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
reject takes an error object
$3
`js
ftpServer.on('server-error', ({error}) => { ... });
`
Occurs when an error arises in the FTP server.
error error object
$3
`js
connection.on('RETR', (error, filePath) => { ... });
`
Occurs when a file is downloaded.
error if successful, will be null
filePath location to which file was downloaded
$3
`js
connection.on('STOR', (error, fileName) => { ... });
`
Occurs when a file is uploaded.
error if successful, will be null
fileName name of the file that was uploaded
$3
`js
connection.on('RNTO', (error, fileName) => { ... });
`
Occurs when a file is renamed.
error 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:
`js
import {FtpSrv, FileSystem} from 'ftp-srv-esm';
class MyFileSystem extends FileSystem {
constructor() {
super(...arguments);
}
get(fileName) {
...
}
}
`
Custom file systems can implement the following variables depending on the developers needs:
$3
#### 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:__ LIST, NLST, STAT, SIZE, RNFR, MDTM
#### list(path)
Returns array of file and directory stat objects
__Used in:__ LIST, NLST, 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, start})
Returns a writable stream
Options:
append 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:
start if set, specifies the byte offset to read from
__Used in:__ RETR
#### delete(path)
Delete a file or directory
__Used in:__ DELE
#### rename(from, to)
Renames a file or directory
__Used in:__ RNFR, RNTO
#### chmod(path)
Modifies a file or directory's permissions
__Used in:__ SITE CHMOD
#### 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:__ STOU`