Code Monkey home page Code Monkey logo

ftp-srv's Introduction

ftp-srv

Modern, extensible FTP Server

npm npm npm


Overview

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

Features

Install

npm install ftp-srv --save

Usage

// 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(() => { ... });

API

new FtpSrv(url, [{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. Setting the hostname to 0.0.0.0 will automatically set the external IP.
Default: "ftp://127.0.0.1:21"

options

pasv_range

A 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

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.
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: []

file_format

Sets the format to use for file stat queries such as LIST.
Default: "ls"
Allowable values:

log

A bunyan logger instance. Created by default.

Events

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

login

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

client-error

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 occured
error error object

RETR

on('RETR', (error, filePath) => { ... });

Occurs when a file is downloaded.

error if successful, will be null filePath location to which file was downloaded

STOR

on('STOR', (error, fileName) => { ... });

Occurs when a file is uploaded.

error if successful, will be null fileName name of the file that was downloaded

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:

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:

Methods

Returns a string of the current working directory
Used in: PWD

Returns a file stat object of file or directory
Used in: LIST, NLST, STAT, SIZE, RNFR, MDTM

Returns array of file and directory stat objects
Used in: LIST, NLST, STAT

Returns new directory relative to current directory
Used in: CWD, CDUP

Returns a path to a newly created directory
Used in: MKD

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

Returns a readable stream
Options:
start if set, specifies the byte offset to read from
Used in: RETR

Delete a file or directory
Used in: DELE

Renames a file or directory
Used in: RNFR, RNTO

Modifies a file or directory's permissions
Used in: SITE CHMOD

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.

References

ftp-srv's People

Contributors

crabl avatar jorinvo avatar ozairp avatar pkeuter avatar trs avatar voxsoftware avatar

Watchers

 avatar

Recommend Projects

  • React photo React

    A declarative, efficient, and flexible JavaScript library for building user interfaces.

  • Vue.js photo Vue.js

    ๐Ÿ–– Vue.js is a progressive, incrementally-adoptable JavaScript framework for building UI on the web.

  • Typescript photo Typescript

    TypeScript is a superset of JavaScript that compiles to clean JavaScript output.

  • TensorFlow photo TensorFlow

    An Open Source Machine Learning Framework for Everyone

  • Django photo Django

    The Web framework for perfectionists with deadlines.

  • D3 photo D3

    Bring data to life with SVG, Canvas and HTML. ๐Ÿ“Š๐Ÿ“ˆ๐ŸŽ‰

Recommend Topics

  • javascript

    JavaScript (JS) is a lightweight interpreted programming language with first-class functions.

  • web

    Some thing interesting about web. New door for the world.

  • server

    A server is a program made to process requests and deliver data to clients.

  • Machine learning

    Machine learning is a way of modeling and interpreting data that allows a piece of software to respond intelligently.

  • Game

    Some thing interesting about game, make everyone happy.

Recommend Org

  • Facebook photo Facebook

    We are working to build community through open source technology. NB: members must have two-factor auth.

  • Microsoft photo Microsoft

    Open source projects and samples from Microsoft.

  • Google photo Google

    Google โค๏ธ Open Source for everyone.

  • D3 photo D3

    Data-Driven Documents codes.