@alancnet/ftp-srv
Advanced tools
Modern, extensible FTP Server
ftp-srv is a modern and extensible FTP server designed to be simple yet configurable.
npm install ftp-srv --save
// Quick start
const FtpSrv = require('ftp-srv');
const ftpServer = new FtpSrv('ftp://0.0.0.0:9876', { options ... });
ftpServer.on('login', (data, resolve, reject) => { ... });
...
ftpServer.listen()
.then(() => { ... });
new FtpSrv(url, [{options}])URL string indicating the protocol, hostname, and port to listen on for connections. Supported protocols:
ftp Plain FTPftps Implicit FTP over TLSNote: 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_urlThe hostname to provide a client when attempting a passive connection (PASV). This defaults to the provided url hostname.
Note: If set to 0.0.0.0, this will automatically resolve to the external IP of the box.
Default: "127.0.0.1"
pasv_rangeA 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
greetingA human readable array of lines or string to send when a client connects.
Default: null
tlsNode TLS secure context object used for implicit (ftps protocol) or explicit (AUTH TLS) connections.
Default: false
anonymousIf 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
blacklistArray 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: []
whitelistArray of commands that are only allowed.
Response code 502 is sent to clients sending any other command.
Default: []
file_formatSets the format to use for file stat queries such as LIST.
Default: "ls"
Allowable values:
ls bin/ls formatep Easily Parsed LIST formatfunction () {} A custom function returning a format or promise for one.
name parameterlogA bunyan logger instance. Created by default.
ftp-srv also comes with a builtin CLI.
$ ftp-srv [url] [options]
$ ftp-srv ftp://0.0.0.0:9876 --root ~/Documents
urlSet the listening URL.
Defaults to ftp://127.0.0.1:21
--root / -rSet the default root directory for users.
Defaults to the current directory.
--credentials / -cSet the path to a json credentials file.
Format:
[
{
"username": "...",
"password": "...",
"root": "..." // Root directory
},
...
]
--usernameSet the username for the only user. Do not provide an argument to allow anonymous login.
--passwordSet the password for the given username.
The FtpSrv class extends the node net.Server. Some custom events can be resolved or rejected, such as login.
loginftpServer.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
root
fs is not provided, this will set the root directory for the connection.cwd
fs is not provided, will set the starting directory for the connectionroot directory.blacklist
whitelist
reject takes an error object
client-errorftpServer.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
RETRconnection.on('RETR', (error, filePath) => { ... });
Occurs when a file is downloaded.
error if successful, will be null
filePath location to which file was downloaded
STORconnection.on('STOR', (error, fileName) => { ... });
Occurs when a file is uploaded.
error if successful, will be null
fileName name of the file that was uploaded
See the command registry for a list of all implemented FTP commands.
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:
const {FtpSrv, FileSystem} = require('ftp-srv');
class MyFileSystem extends FileSystem {
constructor() {
super(...arguments);
}
get(fileName) {
...
}
}
Custom file systems can implement the following variables depending on the developers needs:
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()Returns a unique file name to write to
Used in: STOU
See CONTRIBUTING.md.
This software is licensed under the MIT Licence. See LICENSE.
FAQs
Modern, extensible FTP Server
We found that @alancnet/ftp-srv demonstrated a not healthy version release cadence and project activity because the last version was released a year ago. It has 1 open source maintainer collaborating on the project.
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Research
Security News
Socket’s threat research team has detected six malicious npm packages typosquatting popular libraries to insert SSH backdoors.
Security News
MITRE's 2024 CWE Top 25 highlights critical software vulnerabilities like XSS, SQL Injection, and CSRF, reflecting shifts due to a refined ranking methodology.
Security News
In this segment of the Risky Business podcast, Feross Aboukhadijeh and Patrick Gray discuss the challenges of tracking malware discovered in open source softare.