Description

SSH2 and SFTP(v3) client/server protocol streams for node.js.

Requirements

• node.js -- v0.8.7 or newer

Install

npm install ssh2-streams

API

require('ssh2').SSH2Stream returns an SSH2Stream constructor.

require('ssh2').SFTPStream returns an SFTPStream constructor.

require('ssh2').utils returns an object of useful utility functions.

require('ssh2').constants returns an object containing useful SSH protocol constants.

SSH2Stream events

Client/Server events

• header(< object >headerInfo) - Emitted when the protocol header is seen. headerInfo contains:

  • greeting - string - (Client-only) An optional greeting message presented by the server.

  • identRaw - string - The raw identification string sent by the remote party.

  • versions - object - Contains various information parsed from identRaw:

    • protocol - string - The protocol version (always 1.99 or 2.0) supported by the remote party.

    • software - boolean - The software name used by the remote party.

  • comments - string - Any additional text that comes after the software name.

• CHANNEL_DATA:(< Buffer >data)

• CHANNEL_EXTENDED_DATA:(< integer >type, < Buffer >data)

• CHANNEL_WINDOW_ADJUST:(< integer >bytesToAdd)

• CHANNEL_SUCCESS:()

• CHANNEL_FAILURE:()

• CHANNEL_EOF:()

• CHANNEL_CLOSE:()

• CHANNEL_OPEN_CONFIRMATION:(< object >channelInfo) - channelInfo contains:

  • recipient - integer - The local channel number.

  • sender - integer - The remote party's channel number.

  • window - integer - The initial window size for the channel.

  • packetSize - integer - The maximum packet size for the channel.

• CHANNEL_OPEN_FAILURE:(< object >failInfo) - failInfo contains:

  • recipient - integer - The local channel number.

  • reasonCode - integer - The reason code of the failure.

  • reason - string - A text representation of the reasonCode.

  • description - string - An optional description of the failure.

• DISCONNECT(< string >reason, < integer >reasonCode, < string >description)

• DEBUG(< string >message)

• NEWKEYS()

Client-only events

• fingerprint(< Buffer >hostKey, < function >callback) - This event allows you to (synchronously) verify a host's key. If callback is called with any value other than undefined or true, a disconnection will occur. The default behavior is to auto-allow any host key.

• SERVICE_ACCEPT(< string >serviceName)

• USERAUTH_PASSWD_CHANGEREQ(< string >message)

• USERAUTH_INFO_REQUEST(< string >name, < string >instructions, < string >lang[, < array >prompts])

• USERAUTH_PK_OK()

• USERAUTH_SUCCESS()

• USERAUTH_FAILURE(< array >methodsContinue, < boolean >partialSuccess)

• USERAUTH_BANNER(< string >message)

• REQUEST_SUCCESS([< Buffer >resData])

• REQUEST_FAILURE()

• CHANNEL_OPEN(< object >channelInfo) - channelInfo contains:

  • type - string - The channel type (e.g. x11, forwarded-tcpip).

  • sender - integer - The remote party's channel number.

  • window - integer - The initial window size for the channel.

  • packetSize - integer - The maximum packet size for the channel.

  • data - object - The properties available depend on type:

    • x11:

      • srcIP - string - Source IP address of X11 connection request.

      • srcPort - string - Source port of X11 connection request.

    • forwarded-tcpip:

      • srcIP - string - Source IP address of incoming connection.

      • srcPort - string - Source port of incoming connection.

      • destIP - string - Destination IP address of incoming connection.

      • destPort - string - Destination port of incoming connection.

    • forwarded-streamlocal@openssh.com:

      • socketPath - string - Source socket path of incoming connection.

    • auth-agent@openssh.com has no extra data.

• CHANNEL_REQUEST:(< object >reqInfo) - reqInfo properties depend on reqInfo.request:

  • exit-status:

    • code - integer - The exit status code of the remote process.

  • exit-signal:

    • signal - string - The signal name.

    • coredump - boolean - Was the exit the result of a core dump?

    • description - string - An optional error message.

Server-only events

• SERVICE_REQUEST(< string >serviceName)

• USERAUTH_REQUEST(< string >username, < string >serviceName, < string >authMethod, < mixed >authMethodData) - authMethodData depends on authMethod:

  • For password, it's a string containing the password.

  • For publickey, it's an object containing:

    • keyAlgo - string - The public key algorithm.

    • key - Buffer - The public key data.

    • signature - mixed - If set, it is a Buffer containing the signature to be verified.

    • blob - mixed - If set, it is a Buffer containing the data to sign. The resulting signature is what is compared to signature.

• USERAUTH_INFO_RESPONSE([< array >responses])

• GLOBAL_REQUEST(< string >reqName, < boolean >wantReply, < mixed >reqData) - reqData depends on reqName:

  • For tcpip-forward/cancel-tcpip-forward, it's an object containing:

    • bindAddr - string - The IP address to start/stop binding to.

    • bindPort - string - The port to start/stop binding to.

  • For streamlocal-forward@openssh.com/cancel-streamlocal-forward@openssh.com, it's an object containing:

    • socketPath - string - The socket path to start/stop listening on.

  • For no-more-sessions@openssh.com, there is no reqData.

  • For any other requests, it's a Buffer containing the raw request-specific data.

• CHANNEL_OPEN(< object >channelInfo) - channelInfo contains:

  • type - string - The channel type (e.g. session, direct-tcpip).

  • sender - integer - The remote party's channel number.

  • window - integer - The initial window size for the channel.

  • packetSize - integer - The maximum packet size for the channel.

  • data - object - The properties available depend on type:

    • direct-tcpip:

      • srcIP - string - Source IP address of outgoing connection.

      • srcPort - string - Source port of outgoing connection.

      • destIP - string - Destination IP address of outgoing connection.

      • destPort - string - Destination port of outgoing connection.

    • direct-streamlocal@openssh.com:

      • socketPath - string - Destination socket path of outgoing connection.

    • session has no extra data.

• CHANNEL_REQUEST:(< object >reqInfo) - reqInfo properties depend on reqInfo.request:

  • pty-req:

    • wantReply - boolean - The client is requesting a response to this request.

    • term - string - The terminal type name.

    • cols - integer - The number of columns.

    • rows - integer - The number of rows.

    • width - integer - The width in pixels.

    • height - integer - The height in pixels.

    • modes - object - The terminal modes.

  • window-change:

    • cols - integer - The number of columns.

    • rows - integer - The number of rows.

    • width - integer - The width in pixels.

    • height - integer - The height in pixels.

  • x11-req:

    • wantReply - boolean - The client is requesting a response to this request.

    • single - boolean - Whether only a single X11 connection should be allowed.

    • protocol - string - The X11 authentication protocol to be used.

    • cookie - string - The hex-encoded X11 authentication cookie.

    • screen - integer - The screen number for incoming X11 connections.

  • env:

    • wantReply - boolean - The client is requesting a response to this request.

    • key - string - The environment variable name.

    • val - string - The environment variable value.

  • shell:

    • wantReply - boolean - The client is requesting a response to this request.

  • exec:

    • wantReply - boolean - The client is requesting a response to this request.

    • command - string - The command to be executed.

  • subsystem:

    • wantReply - boolean - The client is requesting a response to this request.

    • subsystem - string - The name of the subsystem.

  • signal:

    • signal - string - The signal name (prefixed with SIG).

  • xon-xoff:

    • clientControl - boolean - Client can/can't perform flow control (control-S/control-Q processing).

  • auth-agent-req@openssh.com has no reqInfo.

SSH2Stream methods

• (constructor)(< object >config) - Creates and returns a new SSH2Stream instance. SSH2Stream instances are Duplex streams. config can contain:

  • server - boolean - Set to true to create an instance in server mode. Default: false

  • privateKey - mixed - If in server mode, a Buffer or string that contains the required host private key (OpenSSH format). Default: (none)

  • passphrase - string - For an encrypted host private key, this is the passphrase used to decrypt it. Default: (none)

  • banner - string - If in server mode, an optional message to send to the user immediately upon connection, before the handshake. Default: (none)

  • ident - string - A custom software name/version identifier. Default: 'ssh2js' + moduleVersion + 'srv' (server mode) 'ssh2js' + moduleVersion (client mode)

  • maxPacketSize - string - This is the maximum packet size that will be accepted. It should be 35000 bytes or larger to be compatible with other SSH2 implementations. Default: 35000

  • highWaterMark - integer - This is the highWaterMark to use for the stream. Default: 32 * 1024

  • debug - function - Set this to a function that receives a single string argument to get detailed (local) debug information. Default: (none)

Client/Server methods

• ping() - boolean - Writes a ping packet. Returns false if you should wait for the drain event before sending any more traffic.

• disconnect([< integer >reasonCode]) - boolean - Writes a disconnect packet and closes the stream. Returns false if you should wait for the drain event before sending any more traffic.

• channelEOF(< integer >channel) - boolean - Writes a channel EOF packet for the given channel. Returns false if you should wait for the drain event before sending any more traffic.

• channelClose(< integer >channel) - boolean - Writes a channel close packet for the given channel. Returns false if you should wait for the drain event before sending any more traffic.

• channelWindowAdjust(< integer >channel, < integer >amount) - boolean - Writes a channel window adjust packet for the given channel where amount is the number of bytes to add to the channel window. Returns false if you should wait for the drain event before sending any more traffic.

• channelData(< integer >channel, < mixed >data) - boolean - Writes a channel data packet for the given channel where data is a Buffer or string. Returns false if you should wait for the drain event before sending any more traffic.

• channelExtData(< integer >channel, < mixed >data, < integer >type) - boolean - Writes a channel extended data packet for the given channel where data is a _Buffer_ or _string_. Returns falseif you should wait for thedrain` event before sending any more traffic.

• channelOpenConfirm(< integer >remoteChannel, < integer >localChannel, < integer >initWindow, < integer >maxPacket) - boolean - Writes a channel open confirmation packet. Returns false if you should wait for the drain event before sending any more traffic.

• channelOpenFail(< integer >remoteChannel, < integer >reasonCode[, < string >description]) - boolean - Writes a channel open failure packet. Returns false if you should wait for the drain event before sending any more traffic.

Client-only methods

• service(< string >serviceName) - boolean - Writes a service request packet for serviceName. Returns false if you should wait for the drain event before sending any more traffic.

• tcpipForward(< string >bindAddr, < integer >bindPort[, < boolean >wantReply]) - boolean - Writes a tcpip forward global request packet. wantReply defaults to true. Returns false if you should wait for the drain event before sending any more traffic.

• cancelTcpipForward(< string >bindAddr, < integer >bindPort[, < boolean >wantReply]) - boolean - Writes a cancel tcpip forward global request packet. wantReply defaults to true. Returns false if you should wait for the drain event before sending any more traffic.

• authPassword(< string >username, < string >password) - boolean - Writes a password userauth request packet. Returns false if you should wait for the drain event before sending any more traffic.

• authPK(< string >username, < object >pubKey[, < function >cbSign]) - boolean - Writes a publickey userauth request packet. pubKey is the object returned from using utils.parseKey() on a private or public key. If cbSign is not present, a pubkey check userauth packet is written. Otherwise cbSign is called with (blob, callback), where blob is the data to sign with the private key and the resulting signature Buffer is passed to callback as the first argument. Returns false if you should wait for the drain event before sending any more traffic.

• authKeyboard(< string >username) - boolean - Writes a keyboard-interactive userauth request packet. Returns false if you should wait for the drain event before sending any more traffic.

• authNone(< string >username) - boolean - Writes a "none" userauth request packet. Returns false if you should wait for the drain event before sending any more traffic.

• authInfoRes(< array >responses) - boolean - Writes a userauth info response packet. responses is an array of zero or more strings corresponding to responses to prompts previously sent by the server. Returns false if you should wait for the drain event before sending any more traffic.

• directTcpip(< integer >channel, < integer >initWindow, < integer >maxPacket, < object >config) - boolean - Writes a direct tcpip channel open packet. config must contain srcIP, srcPort, dstIP, and dstPort. Returns false if you should wait for the drain event before sending any more traffic.

• session(< integer >channel, < integer >initWindow, < integer >maxPacket) - boolean - Writes a session channel open packet. Returns false if you should wait for the drain event before sending any more traffic.

• openssh_agentForward(< integer >channel[, < boolean >wantReply]) - boolean - Writes an auth-agent-req@openssh.com channel request packet. wantReply defaults to true. Returns false if you should wait for the drain event before sending any more traffic.

• windowChange(< integer >channel, < integer >rows, < integer >cols, < integer >height, < integer >width) - boolean - Writes a window change channel request packet. Returns false if you should wait for the drain event before sending any more traffic.

• pty(< integer >channel, < integer >rows, < integer >cols, < integer >height, < integer >width, < string >terminalType, < mixed >terminalModes[, < boolean >wantReply]) - boolean - Writes a pty channel request packet. If terminalType is falsey, vt100 is used. terminalModes can be the raw bytes, an object of the terminal modes to set, or a falsey value for no modes. wantReply defaults to true. Returns false if you should wait for the drain event before sending any more traffic.

• env(< integer >channel, < string >key, < mixed >value[, < boolean >wantReply]) - boolean - Writes an env channel request packet. value can be a string or Buffer. wantReply defaults to true. Returns false if you should wait for the drain event before sending any more traffic.

• shell(< integer >channel[, < boolean >wantReply]) - boolean - Writes a shell channel request packet. wantReply defaults to true. Returns false if you should wait for the drain event before sending any more traffic.

• exec(< integer >channel, < string >command[, < boolean >wantReply]) - boolean - Writes an exec channel request packet. wantReply defaults to true. Returns false if you should wait for the drain event before sending any more traffic.

• signal(< integer >channel, < string >signalName) - boolean - Writes a signal channel request packet. Returns false if you should wait for the drain event before sending any more traffic.

• x11Forward(< integer >channel, < object >config[, < boolean >wantReply]) - boolean - Writes an X11 forward channel request packet. wantReply defaults to true. Returns false if you should wait for the drain event before sending any more traffic. config can contain:

  • single - boolean - true if only a single connection should be forwarded.

  • protocol - string - The name of the X11 authentication method used (e.g. MIT-MAGIC-COOKIE-1).

  • cookie - string - The X11 authentication cookie encoded in hexadecimal.

  • screen - integer - The screen number to forward X11 connections for.

• subsystem(< integer >channel, < string >name[, < boolean >wantReply]) - boolean - Writes a subsystem channel request packet. name is the name of the subsystem (e.g. sftp or netconf). wantReply defaults to true. Returns false if you should wait for the drain event before sending any more traffic.

• openssh_noMoreSessions([< boolean >wantReply]) - boolean - Writes a no-more-sessions@openssh.com request packet. wantReply defaults to true. Returns false if you should wait for the drain event before sending any more traffic.

• openssh_streamLocalForward(< string >socketPath[, < boolean >wantReply]) - boolean - Writes a streamlocal-forward@openssh.com request packet. wantReply defaults to true. Returns false if you should wait for the drain event before sending any more traffic.

• openssh_cancelStreamLocalForward(< string >socketPath[, < boolean >wantReply]) - boolean - Writes a cancel-streamlocal-forward@openssh.com request packet. wantReply defaults to true. Returns false if you should wait for the drain event before sending any more traffic.

• openssh_directStreamLocal(< integer >channel, < integer >initWindow, < integer >maxPacket, < object >config) - boolean - Writes a direct-streamlocal@openssh.com channel open packet. config must contain socketPath. Returns false if you should wait for the drain event before sending any more traffic.

Server-only methods

• serviceAccept(< string >serviceName) - boolean - Writes a service accept packet. Returns false if you should wait for the drain event before sending any more traffic.

• authFailure([< array >authMethods[, < boolean >partialSuccess]]) - boolean - Writes a userauth failure packet. authMethods is an array of authentication methods that can continue. Returns false if you should wait for the drain event before sending any more traffic.

• authSuccess() - boolean - Writes a userauth success packet. Returns false if you should wait for the drain event before sending any more traffic.

• authPKOK(< string >keyAlgorithm, < Buffer >keyData) - boolean - Writes a userauth PK OK packet. Returns false if you should wait for the drain event before sending any more traffic.

• authInfoReq(< string >name, < string >instructions, < array >prompts) - boolean - Writes a userauth info request packet. prompts is an array of { prompt: 'Prompt text', echo: true } objects (prompt being the prompt text and echo indicating whether the client's response to the prompt should be echoed to their display). Returns false if you should wait for the drain event before sending any more traffic.

• requestSuccess([< Buffer >data]) - boolean - Writes a request success packet. Returns false if you should wait for the drain event before sending any more traffic.

• requestFailure() - boolean - Writes a request failure packet. Returns false if you should wait for the drain event before sending any more traffic.

• forwardedTcpip(< integer >channel, < integer >initWindow, < integer >maxPacket, < object >info) - boolean - Writes a forwarded tcpip channel open packet. info must contain boundAddr, boundPort, remoteAddr, and remotePort. Returns false if you should wait for the drain event before sending any more traffic.

• x11(< integer >channel, < integer >initWindow, < integer >maxPacket, < object >info) - boolean - Writes an X11 channel open packet. info must contain originAddr and originPort. Returns false if you should wait for the drain event before sending any more traffic.

• openssh_forwardedStreamLocal(< integer >channel, < integer >initWindow, < integer >maxPacket, < object >info) - boolean - Writes an forwarded-streamlocal@openssh.com channel open packet. info must contain socketPath. Returns false if you should wait for the drain event before sending any more traffic.

• channelSuccess() - boolean - Writes a channel success packet. Returns false if you should wait for the drain event before sending any more traffic.

• channelFailure() - boolean - Writes a channel failure packet. Returns false if you should wait for the drain event before sending any more traffic.

• exitStatus(< integer >channel, < integer >exitCode) - boolean - Writes an exit status channel request packet. Returns false if you should wait for the drain event before sending any more traffic.

• exitSignal(< integer >channel, < string >signalName, < boolean >coreDumped, < string >errorMessage) - boolean - Writes an exit signal channel request packet. Returns false if you should wait for the drain event before sending any more traffic.

SFTP events

Client/Server events

• ready() - Emitted after initial protocol version check has passed.

Server-only events

• OPEN(< integer >reqID, < string >filename, < integer >flags, < ATTRS>attrs)

• READ(< integer >reqID, < Buffer >handle, < integer >offset, < integer >length)

• WRITE(< integer >reqID, < Buffer >handle, < integer >offset, < Buffer >data)

• FSTAT(< integer >reqID, < Buffer >handle)

• FSETSTAT(< integer >reqID, < Buffer >handle, < ATTRS >attrs)

• CLOSE(< integer >reqID, < Buffer >handle)

• OPENDIR(< integer >reqID, < string >path)

• READDIR(< integer >reqID, < Buffer >handle)

• LSTAT(< integer >reqID, < string >path)

• STAT(< integer >reqID, < string >path)

• REMOVE(< integer >reqID, < string >path)

• RMDIR(< integer >reqID, < string >path)

• REALPATH(< integer >reqID, < string >path)

• READLINK(< integer >reqID, < string >path)

• SETSTAT(< integer >reqID, < string >path, < ATTRS >attrs)

• MKDIR(< integer >reqID, < string >path, < ATTRS >attrs)

• RENAME(< integer >reqID, < string >oldPath, < string >newPath)

• SYMLINK(< integer >reqID, < string >linkPath, < string >targetPath)

SFTP static constants

• SFTPStream.STATUS_CODE - object - Contains the various status codes (for use especially with status()):

  • OK

  • EOF

  • NO_SUCH_FILE

  • PERMISSION_DENIED

  • FAILURE

  • BAD_MESSAGE

  • OP_UNSUPPORTED

• SFTPStream.OPEN_MODE - object - Contains the various open file flags:

  • READ

  • WRITE

  • APPEND

  • CREAT

  • TRUNC

  • EXCL

SFTP methods

• (constructor)(< object >config[, < string >remoteIdentRaw]) - Creates and returns a new SFTPStream instance. SFTPStream instances are Duplex streams. remoteIdentRaw can be the raw SSH identification string of the remote party. This is used to change internal behavior based on particular SFTP implementations. config can contain:

  • server - boolean - Set to true to create an instance in server mode. Default: false

  • highWaterMark - integer - This is the highWaterMark to use for the stream. Default: 32 * 1024

  • debug - function - Set this to a function that receives a single string argument to get detailed (local) debug information. Default: (none)

Client-only methods

• fastGet(< string >remotePath, < string >localPath[, < object >options], < function >callback) - (void) - Downloads a file at remotePath to localPath using parallel reads for faster throughput. options can have the following properties:

  • concurrency - integer - Number of concurrent reads Default: 25

  • chunkSize - integer - Size of each read in bytes Default: 32768

  • step - function(< integer >total_transferred, < integer >chunk, < integer >total) - Called every time a part of a file was transferred

  callback has 1 parameter: < Error >err.

• fastPut(< string >localPath, < string >remotePath[, < object >options], < function >callback) - (void) - Uploads a file from localPath to remotePath using parallel reads for faster throughput. options can have the following properties:

  • concurrency - integer - Number of concurrent reads Default: 25

  • chunkSize - integer - Size of each read in bytes Default: 32768

  • step - function(< integer >total_transferred, < integer >chunk, < integer >total) - Called every time a part of a file was transferred

  callback has 1 parameter: < Error >err.

• createReadStream(< string >path[, < object >options]) - ReadStream - Returns a new readable stream for path. options has the following defaults:

  { flags: 'r',
    encoding: null,
    handle: null,
    mode: 0666,
    autoClose: true
  }

  options can include start and end values to read a range of bytes from the file instead of the entire file. Both start and end are inclusive and start at 0. The encoding can be 'utf8', 'ascii', or 'base64'.

  If autoClose is false, then the file handle won't be closed, even if there's an error. It is your responsiblity to close it and make sure there's no file handle leak. If autoClose is set to true (default behavior), on error or end the file handle will be closed automatically.

  An example to read the last 10 bytes of a file which is 100 bytes long:

  sftp.createReadStream('sample.txt', {start: 90, end: 99});

• createWriteStream(< string >path[, < object >options]) - WriteStream - Returns a new writable stream for path. options has the following defaults:

  { flags: 'w',
    encoding: null,
    mode: 0666 }

  options may also include a start option to allow writing data at some position past the beginning of the file. Modifying a file rather than replacing it may require a flags mode of 'r+' rather than the default mode 'w'.

  If 'autoClose' is set to false and you pipe to this stream, this stream will not automatically close after there is no more data upstream -- allowing future pipes and/or manual writes.

• open(< string >filename, < string >mode, [< ATTRS >attributes, ]< function >callback) - boolean - Opens a file filename for mode with optional attributes. mode is any of the modes supported by fs.open (except sync mode). Returns false if you should wait for the drain event before sending any more traffic. callback has 2 parameters: < Error >err, < Buffer >handle.

• close(< Buffer >handle, < function >callback) - boolean - Closes the resource associated with handle given by open() or opendir(). Returns false if you should wait for the drain event before sending any more traffic. callback has 1 parameter: < Error >err.

• readData(< Buffer >handle, < Buffer >buffer, < integer >offset, < integer >length, < integer >position, < function >callback) - boolean - Reads length bytes from the resource associated with handle starting at position and stores the bytes in buffer starting at offset. Returns false if you should wait for the drain event before sending any more traffic. callback has 4 parameters: < Error >err, < integer >bytesRead, < Buffer >buffer (offset adjusted), < integer >position.

• writeData(< Buffer >handle, < Buffer >buffer, < integer >offset, < integer >length, < integer >position, < function >callback) - boolean - Writes length bytes from buffer starting at offset to the resource associated with handle starting at position. Returns false if you should wait for the drain event before sending any more traffic. callback has 1 parameter: < Error >err.

• fstat(< Buffer >handle, < function >callback) - boolean - Retrieves attributes for the resource associated with handle. Returns false if you should wait for the drain event before sending any more traffic. callback has 2 parameters: < Error >err, < Stats >stats.

• fsetstat(< Buffer >handle, < ATTRS >attributes, < function >callback) - boolean - Sets the attributes defined in attributes for the resource associated with handle. Returns false if you should wait for the drain event before sending any more traffic. callback has 1 parameter: < Error >err.

• futimes(< Buffer >handle, < mixed >atime, < mixed >mtime, < function >callback) - boolean - Sets the access time and modified time for the resource associated with handle. atime and mtime can be Date instances or UNIX timestamps. Returns false if you should wait for the drain event before sending any more traffic. callback has 1 parameter: < Error >err.

• fchown(< Buffer >handle, < integer >uid, < integer >gid, < function >callback) - boolean - Sets the owner for the resource associated with handle. Returns false if you should wait for the drain event before sending any more traffic. callback has 1 parameter: < Error >err.

• fchmod(< Buffer >handle, < mixed >mode, < function >callback) - boolean - Sets the mode for the resource associated with handle. mode can be an integer or a string containing an octal number. Returns false if you should wait for the drain event before sending any more traffic. callback has 1 parameter: < Error >err.

• opendir(< string >path, < function >callback) - boolean - Opens a directory path. Returns false if you should wait for the drain event before sending any more traffic. callback has 2 parameters: < Error >err, < Buffer >handle.

• readdir(< mixed >location, < function >callback) - boolean - Retrieves a directory listing. location can either be a Buffer containing a valid directory handle from opendir() or a string containing the path to a directory. Returns false if you should wait for the drain event before sending any more traffic. callback has 2 parameters: < Error >err, < mixed >list. list is an Array of { filename: 'foo', longname: '....', attrs: {...} } style objects (attrs is of type ATTR). If location is a directory handle, this function may need to be called multiple times until list is boolean false, which indicates that no more directory entries are available for that directory handle.

• unlink(< string >path, < function >callback) - boolean - Removes the file/symlink at path. Returns false if you should wait for the drain event before sending any more traffic. callback has 1 parameter: < Error >err.

• rename(< string >srcPath, < string >destPath, < function >callback) - boolean - Renames/moves srcPath to destPath. Returns false if you should wait for the drain event before sending any more traffic. callback has 1 parameter: < Error >err.

• mkdir(< string >path, [< ATTRS >attributes, ]< function >callback) - boolean - Creates a new directory path. Returns false if you should wait for the drain event before sending any more traffic. callback has 1 parameter: < Error >err.

• rmdir(< string >path, < function >callback) - boolean - Removes the directory at path. Returns false if you should wait for the drain event before sending any more traffic. callback has 1 parameter: < Error >err.

• stat(< string >path, < function >callback) - boolean - Retrieves attributes for path. Returns false if you should wait for the drain event before sending any more traffic. callback has 2 parameter: < Error >err, < Stats >stats.

• lstat(< string >path, < function >callback) - boolean - Retrieves attributes for path. If path is a symlink, the link itself is stat'ed instead of the resource it refers to. Returns false if you should wait for the drain event before sending any more traffic. callback has 2 parameters: < Error >err, < Stats >stats.

• setstat(< string >path, < ATTRS >attributes, < function >callback) - boolean - Sets the attributes defined in attributes for path. Returns false if you should wait for the drain event before sending any more traffic. callback has 1 parameter: < Error >err.

• utimes(< string >path, < mixed >atime, < mixed >mtime, < function >callback) - boolean - Sets the access time and modified time for path. atime and mtime can be Date instances or UNIX timestamps. Returns false if you should wait for the drain event before sending any more traffic. callback has 1 parameter: < Error >err.

• chown(< string >path, < integer >uid, < integer >gid, < function >callback) - boolean - Sets the owner for path. Returns false if you should wait for the drain event before sending any more traffic. callback has 1 parameter: < Error >err.

• chmod(< string >path, < mixed >mode, < function >callback) - boolean - Sets the mode for path. mode can be an integer or a string containing an octal number. Returns false if you should wait for the drain event before sending any more traffic. callback has 1 parameter: < Error >err.

• readlink(< string >path, < function >callback) - boolean - Retrieves the target for a symlink at path. Returns false if you should wait for the drain event before sending any more traffic. callback has 2 parameters: < Error >err, < string >target.

• symlink(< string >targetPath, < string >linkPath, < function >callback) - boolean - Creates a symlink at linkPath to targetPath. Returns false if you should wait for the drain event before sending any more traffic. callback has 1 parameter: < Error >err.

• realpath(< string >path, < function >callback) - boolean - Resolves path to an absolute path. Returns false if you should wait for the drain event before sending any more traffic. callback has 2 parameters: < Error >err, < string >absPath.

• ext_openssh_rename(< string >srcPath, < string >destPath, < function >callback) - boolean - OpenSSH extension Performs POSIX rename(3) from srcPath to destPath. Returns false if you should wait for the drain event before sending any more traffic. callback has 1 parameter: < Error >err.

• ext_openssh_statvfs(< string >path, < function >callback) - boolean - OpenSSH extension Performs POSIX statvfs(2) on path. Returns false if you should wait for the drain event before sending any more traffic. callback has 2 parameters: < Error >err, < object >fsInfo. fsInfo contains the information as found in the statvfs struct.

• ext_openssh_fstatvfs(< Buffer >handle, < function >callback) - boolean - OpenSSH extension Performs POSIX fstatvfs(2) on open handle handle. Returns false if you should wait for the drain event before sending any more traffic. callback has 2 parameters: < Error >err, < object >fsInfo. fsInfo contains the information as found in the statvfs struct.

• ext_openssh_hardlink(< string >targetPath, < string >linkPath, < function >callback) - boolean - OpenSSH extension Performs POSIX link(2) to create a hard link to targetPath at linkPath. Returns false if you should wait for the drain event before sending any more traffic. callback has 1 parameter: < Error >err.

• ext_openssh_fsync(< Buffer >handle, < function >callback) - boolean - OpenSSH extension Performs POSIX fsync(3) on the open handle handle. Returns false if you should wait for the drain event before sending any more traffic. callback has 1 parameter: < Error >err.

Server-only methods

• status(< integer >reqID, < integer >statusCode[, < string >message]) - boolean - Sends a status response for the request identified by id. Returns false if you should wait for the drain event before sending any more traffic.

• handle(< integer >reqID, < Buffer >handle) - boolean - Sends a handle response for the request identified by id. handle must be less than 256 bytes. Returns false if you should wait for the drain event before sending any more traffic.

• data(< integer >reqID, < mixed >data[, < string >encoding]) - boolean - Sends a data response for the request identified by id. data can be a Buffer or string. If data is a string, encoding is the encoding of data. Returns false if you should wait for the drain event before sending any more traffic.

• name(< integer >reqID, < array >names) - boolean - Sends a name response for the request identified by id. Returns false if you should wait for the drain event before sending any more traffic. names must be an array of object where each object can contain:

  • filename - string - The entry's name.

  • longname - string - This is the ls -l-style format for the entry (e.g. -rwxr--r-- 1 bar bar 718 Dec 8 2009 foo)

  • attrs - ATTRS - This is an optional ATTRS object that contains requested/available attributes for the entry.

• attrs(< integer >reqID, < ATTRS >attrs) - boolean - Sends an attrs response for the request identified by id. attrs contains the requested/available attributes.

Utility methods

• parseKey(< mixed >keyData) - object - Parses a private/public key in OpenSSH and RFC4716 formats.

• decryptKey(< object >privKeyInfo, < string >passphrase) - (void) - Takes a private key parsed with parseKey() and decrypts it with passphrase. The decrypted key data overwrites the original encrypted copy.

• genPublicKey(< object >privKeyInfo) - object - Takes a private key parsed with parseKey() and generates the associated public key and returns the public key information in the same format as parseKey().

ATTRS

An object with the following valid properties:

• mode - integer - Mode/permissions for the resource.

• uid - integer - User ID of the resource.

• gid - integer - Group ID of the resource.

• size - integer - Resource size in bytes.

• atime - integer - UNIX timestamp of the access time of the resource.

• mtime - integer - UNIX timestamp of the modified time of the resource.

When supplying an ATTRS object to one of the SFTP methods:

• atime and mtime can be either a Date instance or a UNIX timestamp.

• mode can either be an integer or a string containing an octal number.

Stats

An object with the same attributes as an ATTRS object with the addition of the following methods:

• stats.isDirectory()

• stats.isFile()

• stats.isBlockDevice()

• stats.isCharacterDevice()

• stats.isSymbolicLink()

• stats.isFIFO()

• stats.isSocket()