Skip to content

Latest commit

 

History

History
251 lines (187 loc) · 9.6 KB

README.md

File metadata and controls

251 lines (187 loc) · 9.6 KB
Raw

node-sftp-server

A small derivative from original work by @BriteVerify - node-sftp-server.

A simple interface to be able to implement an SFTP Server using Node.js. Based on excellent work by @mscdex - ssh2 and ssh2-streams. Without which none of this would be possible.

In all cases, this library will only ever perform a subset of what can be accomplished with ssh2. If there's something more advanced you need to do and this library won't support it, that one is probably the one to look at. And certainly pull requests would be welcome, too!

The easiest way to get the hang of this library is probably to look at the server_example.js to start with, until this documentation gets more fully fleshed-out.

Installation

npm install --save https://github.com/mvtm-dn/node-sftp-server.git

Usage

var SFTPServer=require('node-sftp-server');

SFTPServer Object

constructor

var myserver = new SFTPServer({ privateKeyFile: "path_to_private_key_file" });

This returns a new SFTPServer() object, which is an EventEmitter. If the private key is not specified, the constructor will try to use ssh_host_rsa_key in the current directory.

debugging

You can supply a debug: true or debug: msg=>mylogger.log(msg) option to the constructor like this:

var myserver = new SFTPServer({
    privateKeyFile: "path_to_private_key_file",
    debug: true
});

The debug option turns on console logging for SSH2 streams so you can see what's going on under the hood to help debug authentication problems, or other low level issues you may encounter.

Same two options for error and warn

temporary files

The server stores temporary files while users are downloading. These are handled by the tmp library. Permissions for these files are set to 600 (read and write for the node user, no permission for any other users) and are stored in your platform's default temporary file location. You can control which directory these files appear in by passing the temporaryFileDirectory to the constructor like this:

var myserver = new SFTPServer({
    privateKeyFile: "path_to_private_key_file",
    temporaryFileDirectory: "/some/temporary/file/path/here"
});

methods

.listen(portnumber)

Listens for an SFTP client to connect to the server on this port.

events

connect - passes along two parameters. The first is a simple context object which has -

  • username:
  • password:
  • method:

The second is a client-info parameter, which has elements like: {"ip":"::1","header":{"identRaw":"SSH-2.0-FileZilla_3.27.1","versions":{"protocol":"2.0","software":"FileZilla_3.27.1"}}}

  • ip (the remote IP)
  • header
    • identRaw (client identification string, like "SSH-2.0-FileZilla_3.27.1")
    • versions
      • protocol (example: "2.0")
      • software (example: "FileZilla_3.27.1")

With the context object, you can call .reject(methodsLeft, isPartial) to reject the connection, or call .accept(callback) to work with the new connection. The accept callback will be passed a Session object as its parameter. The methodsLeft parameter is an array of acceptable authentication methods, two of which are 'password' and 'none'. isPartial is whether or not the attempt should be considered a partial success.

end - emitted when the user disconnects from the server.

error - emitted when the ssh server throws an error. passes error object

Session Object

This object is passed to you when you call .accept(callback) - your callback should expect to be passed a session object as a parameter. The session object is an EventEmitter as well.

events

.on("realpath",function (path,callback) { }) - the server wants to determine the 'real' path for some user. For instance, if a user, when they log in, is immediately deposited into /home/<username>/ - you could implement that here. Invoke the callback with the calculated path - e.g. callback("/home/"+username). TODO - Error management here!

.on("stat",function (path,statkind,statresponder) { }) - on any of STAT, LSTAT, or FSTAT requests (the type will be passed in "statkind"). The statresponder object is a Statter object from the source code. Communicate status back by calling methods and setting properties on the object like this:

Directory

session.on('stat', function(path, statkind, statresponder) {
    statresponder.is_directory();      // Tells statresponder that we're describing a directory.
    statresponder.permissions = 0o755; // Octal permissions, like what you'd send to a chmod command
    statresponder.uid = 1;             // User ID that owns the file.
    statresponder.gid = 1;             // Group ID that owns the file.
    statresponder.size = 0;            // File size in bytes.
    statresponder.atime = 123456;      // Created at (unix style timestamp in seconds-from-epoch).
    statresponder.mtime = 123456;      // Modified at (unix style timestamp in seconds-from-epoch).

    statresponder.file();   // Tells the statter to actually send the values above down the wire.
});

File

session.on('stat', function(path, statkind, statresponder) {
    statresponder.is_file();           // Tells statresponder that we're describing a file.
    statresponder.permissions = 0o644; // Octal permissions, like what you'd send to a chmod command
    statresponder.uid = 1;             // User ID that owns the file.
    statresponder.gid = 1;             // Group ID that owns the file.
    statresponder.size = 1234;         // File size in bytes.
    statresponder.atime = 123456;      // Created at (unix style timestamp in seconds-from-epoch).
    statresponder.mtime = 123456;      // Modified at (unix style timestamp in seconds-from-epoch).

    statresponder.file();   // Tells the statter to actually send the values above down the wire.
});

Errors

You can also respond with file not found messages like this:

session.on('stat', function(path, statkind, statresponder) {
    statresponder.nofile(); // Tells the statter to send a file not found stat down the wire.
});

.on("readdir",function (path,directory_emitter) { }) - on a directory listing attempt, the directory_emitter will keep emitting dir messages with a responder as a parameter, allowing you to respond with responder.file(filename, attrs) to return a file entry in the directory, or responder.end() if the directory listing is complete.

Some explanation on attrs param:

var fs = require('fs');

/*
* Explanation for attrs.mode 
* 
* You may use type bit from fs lib constants and add permissions to it
* 
* Permissions mask would look like 0oXXX where XXX is file octal permissions
* 
* If you'd like to explain directory use:
* fs.constants.S_IFDIR | 0oXXX
* 
* If you'd like to explain file use:
* fs.constants.S_IFREG | 0oXXX
* 
*/

var attrs = {
	'mode': fs.constants.S_IFDIR | 0o644 	// Bit mask of file type and permissions 
	'permissions': 0o644, 					// Octal permissions, like what you'd send to a chmod command
	'uid': 1, 								// User ID that owns the file.
	'gid': 1, 								// Group ID that owns the file.
	'size': 1234, 							// File size in bytes.
	'atime': 123456, 						// Created at (unix style timestamp in seconds-from-epoch).
	'mtime': 123456 						// Modified at (unix style timestamp in seconds-from-epoch).
}

.on("readfile",function (path,writable_stream) { }) - the client is attempting to read a file from the server - place or pipe the contents of the file into the writable_stream.

.on("writefile",function (path,readable_stream) { }) - the client is attempting to write a file to the server - the readable_stream corresponds to the actual file. You may .pipe() that into a writable stream of your own, or use it directly. Also you can abort uploading operation from server by readable_stream.destroy("Access denied")

.on("delete",function (path,callback) { }) - the client wishes to delete a file. Respond with callback.ok() or callback.fail() or any of the other error types

.on("rename",function (oldPath,newPath,callback) { }) - the client wishes to rename a file. Respond with callback.ok() or callback.fail() or any of the other error types

.on("mkdir",function (path,callback) { }) - the client wishes to create a directory. Respond with callback.ok() or callback.fail() or any of the other error types

.on("rmdir",function (oldPath,callback) { }) - the client wishes to remove a directory. Respond with callback.ok() or callback.fail() or any of the other error types

.on("realpath",function (path,callback) { }) as a callback parameters you can place not only filename, but fully defined

{"name":name,"longname":longname,"attr":attributes}

.on("readdir",function (path,directory_emitter) { }) - on a directory listing attempt, the directory_emitter responder now accept as parameter fully qualified name object like

{"name":name,"longname":longname,"attr":attributes}

or even array of names

Error Callbacks

Many of the session events pass some kind of 'responder' or 'callback' object as a parameter. Those typically will have several error conditions that you can use to refuse the request -

  • responder.fail() - general failure?
  • responder.nofile() - no such file or directory
  • responder.denied() - access denied
  • responder.bad_message() - protocol error; bad message (unusual)
  • responder.unsupported() - operation not supported
  • responder.ok() - success

Improvements