Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
An FTP client module for node.js
JavaScript

Fetching latest commit…

Cannot retrieve the latest commit at this time

Failed to load latest commit information.
LICENSE
README.md
TODO
ftp.js
package.json
xregexp.js

README.md

Description

node-ftp is an FTP client module for node.js that provides an asynchronous interface for communicating with an FTP server.

Requirements

Install

npm install ftp

Examples

  • Get a directory listing of the current (remote) working directory:
  var FTPClient = require('ftp');

  var c = new FTPClient();
  c.on('ready', function() {
    c.list(function(err, list) {
      if (err) throw err;
      console.dir(list);
      c.end();
    });
  });
  // connect to localhost:21 as anonymous
  c.connect();
  • Download remote file 'foo.txt' and save it to the local file system:
  var FTPClient = require('ftp');
  var fs = require('fs');

  var c = new FTPClient();
  c.on('ready', function() {
    c.get('foo.txt', function(err, stream) {
      if (err) throw err;
      stream.once('close', function() { c.end(); });
      stream.pipe(fs.createWriteStream('foo.local-copy.txt'));
    });
  });
  // connect to localhost:21 as anonymous
  c.connect();
  • Upload local file 'foo.txt' to the server:
  var FTPClient = require('ftp');
  var fs = require('fs');

  var c = new FTPClient();
  c.on('ready', function() {
    c.put('foo.txt', 'foo.remote-copy.txt', function(err) {
      if (err) throw err;
      c.end();
    });
  });
  // connect to localhost:21 as anonymous
  c.connect();

API

Events

  • ready() - Emitted when connection and authentication were sucessful.

  • close(< boolean >hadErr) - Emitted when the connection has fully closed.

  • end() - Emitted when the connection has ended.

  • error(< Error >err) - Emitted when an error occurs. In case of protocol-level errors, err contains a 'code' property that references the related 3-digit FTP response code.

Methods

* Note: As with the 'error' event, any error objects passed to callbacks will have a 'code' property for protocol-level errors.

  • (constructor)() - Creates and returns a new FTP client instance.

  • connect(< object >config) - (void) - Connects to an FTP server. Valid config properties:

    • host - string - The hostname or IP address of the FTP server. Default: 'localhost'

    • port - integer - The port of the FTP server. Default: 21

    • user - string - Username for authentication. Default: 'anonymous'

    • password - string - Password for authentication. Default: 'anonymous@'

    • connTimeout - integer - How long (in milliseconds) to wait for the main connection to be established. Default: 10000

    • pasvTimeout - integer - How long (in milliseconds) to wait for a PASV data connection to be established. Default: 10000

    • keepalive - integer - How often (in milliseconds) to send a 'dummy' (NOOP) command to keep the connection alive. Default: 10000

  • end() - (void) - Closes the connection to the server.

Required "standard" commands (RFC 959)

  • list([< string >path, ]< function >callback) - (void) - Retrieves the directory listing of path. path defaults to the current working directory. callback has 2 parameters: < Error >err, < array >list. list is an array of objects with these properties:

    • name - string - The name of the entry.

    • size - string - The size of the entry in bytes.

    • date - Date - The last modified date of the entry.

    • rights - object - The various permissions for this entry (*NIX only).

      • user - string - An empty string or any combination of 'r', 'w', 'x'.

      • group - string - An empty string or any combination of 'r', 'w', 'x'.

      • other - string - An empty string or any combination of 'r', 'w', 'x'.

    • type - string - A single character denoting the entry type: 'd' for directory, '-' for file (or 'l' for symlink on *NIX only).

    • owner - string - The user name or ID that this entry belongs to (*NIX only).

    • group - string - The group name or ID that this entry belongs to (*NIX only).

    • target - string - For symlink entries, this is the symlink's target (*NIX only).

  • get(< string >path, < function >callback) - (void) - Retrieves a file, path, from the server. callback has 2 parameters: < Error >err, < ReadableStream >fileStream.

  • put(< mixed >input, < string >path, < function >callback) - (void) - Sends data to the server to be stored as path. input can be a ReadableStream, a Buffer, or a path to a file. callback has 1 parameter: < Error >err.

  • append(< mixed >input, < string >path, < function >callback) - (void) - Same as put(), except if path already exists, it will be appended to instead of overwritten.

  • rename(< string >oldPath, < string >newPath, < function >callback) - (void) - Renames oldPath to newPath on the server. callback has 1 parameter: < Error >err.

  • delete(< string >path, < function >callback) - (void) - Deletes a file, path, on the server. callback has 1 parameter: < Error >err.

  • cwd(< string >path, < function >callback) - (void) - Changes the current working directory to path. callback has 1 parameter: < Error >err.

  • abort(< function >callback) - (void) - Aborts the current data transfer (e.g. from get(), put(), or list()). callback has 1 parameter: < Error >err.

  • status(< function >callback) - (void) - Retrieves human-readable information about the server's status. callback has 2 parameters: < Error >err, < string >status.

Optional "standard" commands (RFC 959)

  • mkdir(< string >path, < function >callback) - (void) - Creates a new directory, path, on the server. callback has 1 parameter: < Error >err.

  • rmdir(< string >path, < function >callback) - (void) - Removes a directory, path, on the server. callback has 1 parameter: < Error >err.

  • cdup(< function >callback) - (void) - Changes the working directory to the parent of the current directory. callback has 1 parameter: < Error >err.

  • pwd(< function >callback) - (void) - Retrieves the current working directory. callback has 2 parameters: < Error >err, < string >cwd.

  • system(< function >callback) - (void) - Retrieves the server's operating system. callback has 2 parameters: < Error >err, < string >OS.

Extended commands (RFC 3659)

  • size(< string >path, < function >callback) - (void) - Retrieves the size of path. callback has 2 parameters: < Error >err, < integer >numBytes.

  • lastMod(< string >path, < function >callback) - (void) - Retrieves the last modified date and time for path. callback has 2 parameters: < Error >err, < Date >lastModified.

  • restart(< integer >byteOffset, < function >callback) - (void) - Sets the file byte offset for the next file transfer action (get/put/append) to byteOffset. callback has 1 parameter: < Error >err.

Something went wrong with that request. Please try again.