![\"ftp-srv\"](\"logo.png\")
\n \n\n \n \n \n
\n Modern, extensible FTP Server\n
\n\n\n\n---\n\n## Overview\n`ftp-srv` is a modern and extensible FTP server designed to be simple yet configurable.\n\n## Features\n- Extensible [file systems](#file-system) per connection\n- Passive and active transfers\n- [Explicit](https://en.wikipedia.org/wiki/FTPS#Explicit) & [Implicit](https://en.wikipedia.org/wiki/FTPS#Implicit) TLS connections\n- Promise based API\n\n## Install\n`npm install ftp-srv --save`\n\n## Usage\n\n```js\n// Quick start, create an active ftp server.\nconst FtpSrv = require('ftp-srv');\n\nconst port=21;\nconst ftpServer = new FtpSrv({\n url: \"ftp://0.0.0.0:\" + port,\n anonymous: true\n});\n\nftpServer.on('login', ({ connection, username, password }, resolve, reject) => { \n if(username === 'anonymous' && password === 'anonymous'){\n return resolve({ root:\"/\" }); \n }\n return reject(new errors.GeneralError('Invalid username or password', 401));\n});\n\nftpServer.listen().then(() => { \n console.log('Ftp server is starting...')\n});\n```\n\n## API\n\n### `new FtpSrv({options})`\n#### url\n[URL string](https://nodejs.org/api/url.html#url_url_strings_and_url_objects) indicating the protocol, hostname, and port to listen on for connections.\nSupported protocols:\n- `ftp` Plain FTP\n- `ftps` Implicit FTP over TLS\n\n_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. \n__Default:__ `\"ftp://127.0.0.1:21\"`\n\n#### `pasv_url`\n`FTP-srv` provides an IP address to the client when a `PASV` command is received in the handshake for a passive connection. Reference [PASV verb](https://cr.yp.to/ftp/retr.html#pasv). This can be one of two options:\n- 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.\nExample:\n ```js\nconst { networkInterfaces } = require('os');\nconst { Netmask } = require('netmask');\n\nconst nets = networkInterfaces();\nfunction getNetworks() {\n let networks = {};\n for (const name of Object.keys(nets)) {\n for (const net of nets[name]) {\n if (net.family === 'IPv4' && !net.internal) {\n networks[net.address + \"/24\"] = net.address\n }\n }\n }\n return networks;\n}\n\nconst resolverFunction = (address) => {\n // const networks = {\n // '$GATEWAY_IP/32': `${public_ip}`, \n // '10.0.0.0/8' : `${lan_ip}`\n // } \n const networks = getNetworks();\n for (const network in networks) {\n if (new Netmask(network).contains(address)) {\n return networks[network];\n }\n }\n return \"127.0.0.1\";\n}\n\nnew FtpSrv({pasv_url: resolverFunction});\n```\n\n- 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. \n\nIf not provided, clients can only connect using an `Active` connection.\n\n#### `pasv_min`\nThe starting port to accept passive connections. \n__Default:__ `1024`\n\n#### `pasv_max`\nThe ending port to accept passive connections. \nThe range is then queried for an available port to use when required. \n__Default:__ `65535`\n\n#### `greeting`\nA human readable array of lines or string to send when a client connects. \n__Default:__ `null`\n\n#### `tls`\nNode [TLS secure context object](https://nodejs.org/api/tls.html#tls_tls_createsecurecontext_options) used for implicit (`ftps` protocol) or explicit (`AUTH TLS`) connections. \n__Default:__ `false`\n\n#### `anonymous`\nIf true, will allow clients to authenticate using the username `anonymous`, not requiring a password from the user. \nCan also set as a string which allows users to authenticate using the username provided. \nThe `login` event is then sent with the provided username and `@anonymous` as the password. \n__Default:__ `false`\n\n#### `blacklist`\nArray of commands that are not allowed. \nResponse code `502` is sent to clients sending one of these commands. \n__Example:__ `['RMD', 'RNFR', 'RNTO']` will not allow users to delete directories or rename any files. \n__Default:__ `[]`\n\n#### `whitelist`\nArray of commands that are only allowed. \nResponse code `502` is sent to clients sending any other command. \n__Default:__ `[]`\n\n#### `file_format`\nSets the format to use for file stat queries such as `LIST`. \n__Default:__ `\"ls\"` \n__Allowable values:__\n - `ls` [bin/ls format](https://cr.yp.to/ftp/list/binls.html)\n - `ep` [Easily Parsed LIST format](https://cr.yp.to/ftp/list/eplf.html)\n - `function () {}` A custom function returning a format or promise for one.\n - Only one argument is passed in: a node [file stat](https://nodejs.org/api/fs.html#fs_class_fs_stats) object with additional file `name` parameter\n\n#### `log`\nA [bunyan logger](https://github.com/trentm/node-bunyan) instance. Created by default.\n\n#### `timeout`\nSets the timeout (in ms) after that an idle connection is closed by the server \n__Default:__ `0`\n\n## CLI\n\n`ftp-srv` also comes with a builtin CLI.\n\n```bash\n$ ftp-srv [url] [options]\n```\n\n```bash\n$ ftp-srv ftp://0.0.0.0:9876 --root ~/Documents\n```\n\n#### `url`\nSet the listening URL.\n\nDefaults to `ftp://127.0.0.1:21`\n\n#### `--pasv_url`\nThe hostname to provide a client when attempting a passive connection (`PASV`). \nIf not provided, clients can only connect using an `Active` connection.\n\n#### `--pasv_min`\nThe starting port to accept passive connections. \n__Default:__ `1024`\n\n#### `--pasv_max`\nThe ending port to accept passive connections. \nThe range is then queried for an available port to use when required. \n__Default:__ `65535`\n\n#### `--root` / `-r`\nSet the default root directory for users.\n\nDefaults to the current directory.\n\n#### `--credentials` / `-c`\nSet the path to a json credentials file.\n\nFormat:\n\n```js\n[\n {\n \"username\": \"...\",\n \"password\": \"...\",\n \"root\": \"...\" // Root directory\n },\n ...\n]\n```\n\n#### `--username`\nSet the username for the only user. Do not provide an argument to allow anonymous login.\n\n#### `--password`\nSet the password for the given `username`.\n\n#### `--read-only`\nDisable write actions such as upload, delete, etc.\n\n## Events\n\nThe `FtpSrv` class extends the [node net.Server](https://nodejs.org/api/net.html#net_class_net_server). Some custom events can be resolved or rejected, such as `login`.\n\n### `client-error`\n```js\nftpServer.on('client-error', ({connection, context, error}) => { ... });\n```\n\nOccurs when an error arises in the client connection.\n\n`connection` [client class object](src/connection.js) \n`context` string of where the error occurred \n`error` error object\n\n### `disconnect`\n```js\nftpServer.on('disconnect', ({connection, id, newConnectionCount}) => { ... });\n```\n\nOccurs when a client has disconnected.\n\n`connection` [client class object](src/connection.js) \n`id` string of the disconnected connection id \n`id` number of the new connection count (exclusive the disconnected client connection)\n\n### `closed`\n```js\nftpServer.on('closed', ({}) => { ... });\n```\n\nOccurs when the FTP server has been closed.\n\n### `closing`\n```js\nftpServer.on('closing', ({}) => { ... });\n```\n\nOccurs when the FTP server has started closing.\n\n### `login`\n```js\nftpServer.on('login', ({connection, username, password}, resolve, reject) => { ... });\n```\n\nOccurs when a client is attempting to login. Here you can resolve the login request by username and password.\n\n`connection` [client class object](src/connection.js) \n`username` string of username from `USER` command \n`password` string of password from `PASS` command \n`resolve` takes an object of arguments: \n- `fs`\n - Set a custom file system class for this connection to use.\n - See [File System](#file-system) for implementation details.\n- `root`\n - If `fs` is not provided, this will set the root directory for the connection.\n - The user cannot traverse lower than this directory.\n- `cwd`\n - If `fs` is not provided, will set the starting directory for the connection\n - This is relative to the `root` directory.\n- `blacklist`\n - Commands that are forbidden for only this connection\n- `whitelist`\n - If set, this connection will only be able to use the provided commands\n\n`reject` takes an error object\n\n### `server-error`\n```js\nftpServer.on('server-error', ({error}) => { ... });\n```\n\nOccurs when an error arises in the FTP server.\n \n`error` error object\n\n### `RETR`\n```js\nconnection.on('RETR', (error, filePath) => { ... });\n```\n\nOccurs when a file is downloaded.\n\n`error` if successful, will be `null` \n`filePath` location to which file was downloaded\n\n### `STOR`\n```js\nconnection.on('STOR', (error, fileName) => { ... });\n```\n\nOccurs when a file is uploaded.\n\n`error` if successful, will be `null` \n`fileName` name of the file that was uploaded\n\n### `RNTO`\n```js\nconnection.on('RNTO', (error, fileName) => { ... });\n```\n\nOccurs when a file is renamed.\n\n`error` if successful, will be `null` \n`fileName` name of the file that was renamed\n\n## Supported Commands\n\nSee the [command registry](src/commands/registration) for a list of all implemented FTP commands.\n\n## File System\nThe default [file system](src/fs.js) can be overwritten to use your own implementation. \nThis can allow for virtual file systems, and more. \nEach connection can set it's own file system based on the user. \n\nThe default file system is exported and can be extended as needed: \n```js\nconst {FtpSrv, FileSystem} = require('ftp-srv');\n\nclass MyFileSystem extends FileSystem {\n constructor() {\n super(...arguments);\n }\n\n get(fileName) {\n ...\n }\n}\n```\n\nCustom file systems can implement the following variables depending on the developers needs:\n\n### Methods\n#### [`currentDirectory()`](src/fs.js#L40)\nReturns a string of the current working directory \n__Used in:__ `PWD`\n\n#### [`get(fileName)`](src/fs.js#L44)\nReturns a file stat object of file or directory \n__Used in:__ `LIST`, `NLST`, `STAT`, `SIZE`, `RNFR`, `MDTM`\n\n#### [`list(path)`](src/fs.js#L50)\nReturns array of file and directory stat objects \n__Used in:__ `LIST`, `NLST`, `STAT`\n\n#### [`chdir(path)`](src/fs.js#L67)\nReturns new directory relative to current directory \n__Used in:__ `CWD`, `CDUP`\n\n#### [`mkdir(path)`](src/fs.js#L114)\nReturns a path to a newly created directory \n__Used in:__ `MKD`\n\n#### [`write(fileName, {append, start})`](src/fs.js#L79)\nReturns a writable stream \nOptions: \n `append` if true, append to existing file \n `start` if set, specifies the byte offset to write to \n__Used in:__ `STOR`, `APPE`\n\n#### [`read(fileName, {start})`](src/fs.js#L90)\nReturns a readable stream \nOptions: \n `start` if set, specifies the byte offset to read from \n__Used in:__ `RETR`\n\n#### [`delete(path)`](src/fs.js#L105)\nDelete a file or directory \n__Used in:__ `DELE`\n\n#### [`rename(from, to)`](src/fs.js#L120)\nRenames a file or directory \n__Used in:__ `RNFR`, `RNTO`\n\n#### [`chmod(path)`](src/fs.js#L126)\nModifies a file or directory's permissions \n__Used in:__ `SITE CHMOD`\n\n#### [`getUniqueName(fileName)`](src/fs.js#L131)\nReturns a unique file name to write to. Client requested filename available if you want to base your function on it. \n__Used in:__ `STOU`\n\n## Contributing\n\nSee [CONTRIBUTING.md](CONTRIBUTING.md).\n\n## License\n\nThis software is licensed under the MIT Licence. See [LICENSE](LICENSE).\n\n## References\n\n- [https://cr.yp.to/ftp.html](https://cr.yp.to/ftp.html)\n","maintainers":[{"name":"trs","email":"npm@tylerstewart.ca"},{"name":"botovance","email":"bot@autovance.com"}],"time":{"modified":"2023-10-09T06:04:40.020Z","created":"2017-03-08T01:32:50.911Z","1.0.0":"2017-03-08T01:32:50.911Z","2.0.0":"2017-03-08T01:43:02.658Z","2.0.1":"2017-03-08T19:47:00.941Z","2.0.2":"2017-03-08T23:18:06.418Z","2.1.0":"2017-03-10T21:10:09.825Z","2.2.0":"2017-03-29T16:16:54.859Z","2.2.1":"2017-03-30T18:27:57.529Z","2.3.0":"2017-03-31T23:15:59.097Z","2.3.1":"2017-04-27T19:29:39.476Z","2.4.0":"2017-05-06T00:06:55.355Z","2.5.0":"2017-05-06T00:30:15.723Z","2.6.0":"2017-05-11T23:35:43.265Z","2.7.0":"2017-05-16T03:40:05.516Z","2.7.1":"2017-05-19T19:03:02.612Z","2.7.2":"2017-05-21T03:35:41.575Z","2.7.3":"2017-06-08T21:22:55.259Z","2.8.0":"2017-06-08T23:37:38.848Z","2.9.0":"2017-06-09T16:33:07.569Z","2.9.1":"2017-06-16T21:20:15.665Z","2.9.2":"2017-06-20T23:22:54.046Z","2.10.0":"2017-06-27T01:56:14.371Z","2.10.1":"2017-07-10T16:05:54.819Z","2.11.0":"2017-07-24T17:02:16.183Z","2.11.1":"2017-08-14T23:10:12.411Z","0.0.0":"2017-08-18T18:36:51.182Z","2.11.2":"2017-08-18T18:48:07.642Z","2.11.3":"2017-09-30T17:43:46.090Z","2.11.4":"2017-10-25T18:25:10.881Z","2.12.0":"2017-10-26T03:52:00.450Z","2.13.0":"2017-10-30T23:57:46.135Z","2.13.1":"2017-10-31T00:50:31.641Z","2.13.2":"2017-10-31T22:21:18.946Z","2.13.3":"2017-11-06T21:21:17.363Z","2.14.0":"2017-12-09T00:53:46.135Z","2.15.0":"2018-01-10T18:05:45.262Z","2.16.0":"2018-02-10T03:00:09.376Z","2.16.1":"2018-03-30T05:28:57.223Z","2.16.2":"2018-05-07T17:09:55.612Z","2.17.0":"2018-05-18T20:54:47.103Z","2.18.0":"2018-05-18T21:23:50.200Z","2.19.0":"2018-05-25T22:51:29.930Z","2.19.1":"2018-05-31T14:30:12.616Z","2.19.2":"2018-06-08T01:54:43.293Z","2.19.3":"2018-07-23T00:53:41.134Z","2.19.4":"2018-07-24T17:48:07.098Z","2.19.5":"2018-08-09T01:08:40.294Z","3.0.0":"2018-09-02T16:22:29.153Z","3.0.1":"2018-10-30T01:52:52.110Z","3.0.2":"2018-11-12T03:20:34.011Z","3.0.3":"2018-11-19T16:48:55.618Z","3.0.4":"2018-11-19T16:50:22.967Z","3.0.5":"2018-12-21T22:52:22.244Z","3.1.0":"2019-02-21T18:05:31.407Z","3.1.1":"2019-02-21T18:31:44.497Z","3.2.0":"2019-02-21T18:39:46.254Z","4.0.0":"2019-02-21T18:54:45.736Z","4.0.1":"2019-03-03T04:44:08.000Z","4.1.0":"2019-03-08T18:16:15.291Z","4.1.1":"2019-06-21T20:42:20.007Z","4.2.0":"2019-08-22T21:00:36.287Z","4.3.0":"2019-11-12T16:51:30.859Z","4.3.1":"2020-01-08T16:50:39.154Z","4.3.2":"2020-07-20T22:48:43.503Z","4.3.3":"2020-08-13T14:41:21.001Z","4.3.4":"2020-08-17T19:27:12.170Z","3.1.2":"2020-08-17T20:09:42.179Z","0.0.0-development":"2020-08-17T20:21:47.321Z","2.19.6":"2020-08-17T20:22:46.035Z","4.4.0":"2020-12-16T23:00:01.901Z","4.5.0":"2021-08-09T20:03:13.282Z","4.6.0":"2022-04-18T22:27:31.657Z","4.6.1":"2022-05-09T06:04:40.199Z","4.6.2":"2022-06-24T17:03:57.989Z","4.6.3":"2023-10-09T06:04:39.643Z"},"homepage":"https://github.com/autovance/ftp-srv#readme","keywords":["ftp","ftp-server","ftp-srv","ftp-svr","ftpd","ftpserver","server"],"repository":{"type":"git","url":"git+https://github.com/autovance/ftp-srv.git"},"bugs":{"url":"https://github.com/autovance/ftp-srv/issues"},"license":"MIT","readmeFilename":"README.md","users":{"kinshi":true,"ethanliew":true,"cryogena":true,"unification":true,"heartnett":true}}![\"npm\"](\"https://img.shields.io/npm/dm/ftp-srv.svg?style=for-the-badge\")
\n ![\"circleci\"](\"https://img.shields.io/circleci/project/github/autovance/ftp-srv/master.svg?style=for-the-badge\")
\n