An SSH2 client module written in pure JavaScript for node.js.
Development/testing is done against OpenSSH (6.1 currently).
- node.js -- v0.8.7 or newer
npm install ssh2
- Authenticate using keys, execute
uptime
on a server, and disconnect afterwards:
var Connection = require('ssh2');
var c = new Connection();
c.on('connect', function() {
console.log('Connection :: connect');
});
c.on('ready', function() {
console.log('Connection :: ready');
c.exec('uptime', function(err, stream) {
if (err) throw err;
stream.on('data', function(data, extended) {
console.log((extended === 'stderr' ? 'STDERR: ' : 'STDOUT: ')
+ data);
});
stream.on('end', function() {
console.log('Stream :: EOF');
});
stream.on('close', function() {
console.log('Stream :: close');
});
stream.on('exit', function(code, signal) {
console.log('Stream :: exit :: code: ' + code + ', signal: ' + signal);
c.end();
});
});
});
c.on('error', function(err) {
console.log('Connection :: error :: ' + err);
});
c.on('end', function() {
console.log('Connection :: end');
});
c.on('close', function(had_error) {
console.log('Connection :: close');
});
c.connect({
host: '192.168.100.100',
port: 22,
username: 'frylock',
privateKey: require('fs').readFileSync('/here/is/my/key')
});
// example output:
// Connection :: connect
// Connection :: ready
// STDOUT: 17:41:15 up 22 days, 18:09, 1 user, load average: 0.00, 0.01, 0.05
//
// Stream :: exit :: code: 0, signal: undefined
// Connection :: end
// Connection :: close
- Authenticate using password, send a (raw) HTTP request to port 80 on the server, and disconnect afterwards:
var Connection = require('ssh2');
var c = new Connection();
c.on('connect', function() {
console.log('Connection :: connect');
});
c.on('ready', function() {
console.log('Connection :: ready');
c.forwardOut('192.168.100.102', 8000, '127.0.0.1', 80, function(err, stream) {
if (err) throw err;
stream.on('data', function(data) {
console.log('TCP :: DATA: ' + data);
});
stream.on('end', function() {
console.log('TCP :: EOF');
});
stream.on('error', function(err) {
console.log('TCP :: ERROR: ' + err);
});
stream.on('close', function(had_err) {
console.log('TCP :: CLOSED');
c.end();
});
var data = [
'HEAD / HTTP/1.1',
'User-Agent: curl/7.27.0',
'Host: 127.0.0.1',
'Accept: */*',
'Connection: close',
'',
''
];
stream.write(data.join('\r\n'));
});
});
c.on('error', function(err) {
console.log('Connection :: error :: ' + err);
});
c.on('end', function() {
console.log('Connection :: end');
});
c.on('close', function(had_error) {
console.log('Connection :: close');
});
c.connect({
host: '192.168.100.100',
port: 22,
username: 'frylock',
password: 'nodejsrules'
});
// example output:
// Connection :: connect
// Connection :: ready
// TCP :: DATA: HTTP/1.1 200 OK
// Date: Thu, 15 Nov 2012 13:52:58 GMT
// Server: Apache/2.2.22 (Ubuntu)
// X-Powered-By: PHP/5.4.6-1ubuntu1
// Last-Modified: Thu, 01 Jan 1970 00:00:00 GMT
// Content-Encoding: gzip
// Vary: Accept-Encoding
// Connection: close
// Content-Type: text/html; charset=UTF-8
//
//
// TCP :: EOF
// TCP :: CLOSED
// Connection :: end
// Connection :: close
- Authenticate using password and forward remote connections on port 8000 to us:
var Connection = require('ssh2');
var c = new Connection();
c.on('connect', function() {
console.log('Connection :: connect');
});
c.on('tcp connection', function(info, accept, reject) {
console.log('TCP :: INCOMING CONNECTION: ' + require('util').inspect(info));
var stream = accept();
stream.on('data', function(data) {
console.log('TCP :: DATA: ' + data);
});
stream.on('end', function() {
console.log('TCP :: EOF');
});
stream.on('error', function(err) {
console.log('TCP :: ERROR: ' + err);
});
stream.on('close', function(had_err) {
console.log('TCP :: CLOSED');
});
var response = [
'HTTP/1.1 404 Not Found',
'Date: Thu, 15 Nov 2012 02:07:58 GMT',
'Server: ForwardedConnection',
'Content-Length: 0',
'Connection: close',
'',
''
];
stream.end(response.join('\r\n'));
});
c.on('ready', function() {
console.log('Connection :: ready');
c.forwardIn('127.0.0.1', 8000, function(err) {
if (err) throw err;
console.log('Listening for connections on server on port 8000!');
});
});
c.on('error', function(err) {
console.log('Connection :: error :: ' + err);
});
c.on('end', function() {
console.log('Connection :: end');
});
c.on('close', function(had_error) {
console.log('Connection :: close');
});
c.connect({
host: '192.168.100.100',
port: 22,
username: 'frylock',
password: 'nodejsrules'
});
// example output:
// Connection :: connect
// Connection :: ready
// Listening for connections on server on port 8000!
// (.... then from another terminal on the server: `curl -I http://127.0.0.1:8000`)
// TCP :: INCOMING CONNECTION: { destIP: '127.0.0.1',
// destPort: 8000,
// srcIP: '127.0.0.1',
// srcPort: 41969 }
// TCP DATA: HEAD / HTTP/1.1
// User-Agent: curl/7.27.0
// Host: 127.0.0.1:8000
// Accept: */*
//
//
// TCP :: CLOSED
- Authenticate using password, start an SFTP session, and get a directory listing:
var Connection = require('ssh2');
var c = new Connection();
c.on('connect', function() {
console.log('Connection :: connect');
});
c.on('ready', function() {
console.log('Connection :: ready');
c.sftp(function(err, sftp) {
if (err) throw err;
sftp.on('end', function() {
console.log('SFTP :: SFTP session closed');
});
sftp.opendir('foo', function readdir(err, handle) {
if (err) throw err;
sftp.readdir(handle, function(err, list) {
if (err) throw err;
if (list === false) {
sftp.close(handle, function(err) {
if (err) throw err;
console.log('SFTP :: Handle closed');
sftp.end();
});
return;
}
console.dir(list);
readdir(undefined, handle);
});
});
});
});
c.on('error', function(err) {
console.log('Connection :: error :: ' + err);
});
c.on('end', function() {
console.log('Connection :: end');
});
c.on('close', function(had_error) {
console.log('Connection :: close');
});
c.connect({
host: '192.168.100.100',
port: 22,
username: 'frylock',
password: 'nodejsrules'
});
// example output:
// Connection :: connect
// Connection :: ready
// [ { filename: '.',
// longname: 'drwxr-xr-x 3 mscdex mscdex 4096 Nov 18 15:03 .',
// attrs:
// { size: 1048576,
// uid: 1000,
// gid: 1000,
// mode: 16877,
// atime: 1353269008,
// mtime: 1353269007 } },
// { filename: '..',
// longname: 'drwxr-xr-x 45 mscdex mscdex 4096 Nov 18 11:03 ..',
// attrs:
// { size: 1048576,
// uid: 1000,
// gid: 1000,
// mode: 16877,
// atime: 1353254582,
// mtime: 1353254581 } },
// { filename: 'test.txt',
// longname: '-rw-r--r-- 1 mscdex mscdex 12 Nov 18 11:05 test.txt',
// attrs:
// { size: 12,
// uid: 1000,
// gid: 1000,
// mode: 33188,
// atime: 1353254750,
// mtime: 1353254744 } },
// { filename: 'mydir',
// longname: 'drwxr-xr-x 2 mscdex mscdex 4096 Nov 18 15:03 mydir',
// attrs:
// { size: 1048576,
// uid: 1000,
// gid: 1000,
// mode: 16877,
// atime: 1353269007,
// mtime: 1353269007 } } ]
// SFTP :: Handle closed
// SFTP :: SFTP session closed
require('ssh2')
returns a Connection object
-
connect() - A connection to the server was successful.
-
banner(< string >message, < string >language) - A notice was sent by the server upon connection.
-
ready() - Authentication was successful.
-
tcp connection(< object >details, < function >accept, < function >reject) - An incoming forwarded TCP connection is being requested. Calling
accept
accepts the connection and returns aChannelStream
object. Callingreject
rejects the connection and no further action is needed.details
contains:-
srcIP - string - The originating IP of the connection.
-
srcPort - integer - The originating port of the connection.
-
dstIP - string - The remote IP the connection was received on (given in earlier call to
forwardIn()
). -
dstPort - integer - The remote port the connection was received on (given in earlier call to
forwardIn()
).
-
-
keyboard-interactive(< string >name, < string >instructions, < string >instructionsLang, < array >prompts, < function >finish) - The server is asking for replies to the given
prompts
for keyboard-interactive user authentication.name
is generally what you'd use as a window title (for GUI apps).prompts
is an array of{ prompt: 'Password: ', echo: false }
style objects (hereecho
indicates whether user input should be displayed on the screen). The answers for all prompts must be provided as an array of strings and passed tofinish
when you are ready to continue. Note: It's possible for the server to come back and ask more questions. -
change password(< string >message, < string >language, < function >done) - If using password-based user authentication, the server has requested that the user's password be changed. Call
done
with the new password. -
error(< Error >err) - An error occurred. A 'level' property indicates 'connection-socket' for socket-level errors and 'connection-ssh' for SSH disconnection messages. In the case of 'connection-ssh' messages, there may be a 'description' property that provides more detail.
-
end() - The socket was disconnected.
-
close(< boolean >hadError) - The socket was closed.
hadError
is set to true if this was due to error. -
debug(< string >message) - If
debug
is set in the object passed to connect(), then this event will be emitted when the server sends debug messages. For OpenSSH, these usually are messages like "Pty allocation disabled.", "X11 forwarding disabled.", etc. when options are set for particular keys in~/.ssh/authorized_keys
.
-
(constructor)() - Creates and returns a new Connection instance.
-
connect(< object >config) - (void) - Attempts a connection to a server using the information given in
config
:-
host - < string > - Hostname or IP address of the server. Default: 'localhost'
-
port - < integer > - Port number of the server. Default: 22
-
hostHash - < string > - 'md5' or 'sha1'. The host's key is hashed using this method and passed to the hostVerifier function. Default: (none)
-
hostVerifier - < function > - Function that is passed a string hex hash of the host's key for verification purposes. Return true to continue with the connection, false to reject and disconnect. Default: (none)
-
username - < string > - Username for authentication. Default: (none)
-
password - < string > - Password for password-based user authentication. Default: (none)
-
agent - < string > - Path to ssh-agent's UNIX socket for ssh-agent-based user authentication. Windows users: set to 'pageant' for authenticating with Pageant. Default: (none)
-
privateKey - < mixed > - Buffer or string that contains a private key for key-based user authentication (OpenSSH format). Default: (none)
-
passphrase - < string > - For an encrypted private key, this is the passphrase used to decrypt it. Default: (none)
-
publicKey - < mixed > - Optional Buffer or string that contains a public key for key-based user authentication (OpenSSH format). If
publicKey
is not set, it will be generated from theprivateKey
. Default: (none) -
tryKeyboard - < boolean > - Try keyboard-interactive user authentication if primary user authentication method fails. Default: false
-
pingInterval - < integer > - How often (in milliseconds) to send SSH-level keepalive packets to the server. Default: (60000)
-
sock - < ReadableStream > - A ReadableStream to use for communicating with the server instead of creating and using a new TCP connection (useful for connection hopping).
-
Authentication method priorities: Password -> Private Key -> Agent (-> keyboard-interactive if tryKeyboard
is true)
-
exec(< string >command[, < object >options], < function >callback) - (void) - Executes
command
on the server. Validoptions
properties are:-
env - < object > - An environment to use for the execution of the command.
-
pty - < mixed > - Set to true to allocate a pseudo-tty with defaults, or an object containing specific pseudo-tty settings (see 'Pseudo-TTY settings').
callback
has 2 parameters: < Error >err, < ChannelStream >stream. -
-
shell([< object >window,] < function >callback) - (void) - Starts an interactive shell session on the server, with optional
window
pseudo-tty settings (see 'Pseudo-TTY settings').callback
has 2 parameters: < Error >err, < ChannelStream >stream. -
forwardIn(< string >remoteAddr, < integer >remotePort, < function >callback) - (void) - Bind to
remoteAddr
onremotePort
on the server and forward incoming connections.callback
has 2 parameters: < Error >err, < integer >port (port
is the assigned port number ifremotePort
was 0). Here are some special values forremoteAddr
and their associated binding behaviors:-
'' - Connections are to be accepted on all protocol families supported by the server.
-
'0.0.0.0' - Listen on all IPv4 addresses.
-
'::' - Listen on all IPv6 addresses.
-
'localhost' - Listen on all protocol families supported by the server on loopback addresses only.
-
'127.0.0.1' and '::1' - Listen on the loopback interfaces for IPv4 and IPv6, respectively.
-
-
unforwardIn(< string >remoteAddr, < integer >remotePort, < function >callback) - (void) - Unbind
remoteAddr
onremotePort
on the server and stop forwarding incoming connections. Untilcallback
is called, more connections may still come in.callback
has 1 parameter: < Error >err. -
forwardOut(< string >srcIP, < integer >srcPort, < string >dstIP, < integer >dstPort, < function >callback) - (void) - Open a connection with
srcIP
andsrcPort
as the originating address and port anddstIP
anddstPort
as the remote destination address and port.callback
has 2 parameters: < Error >err, < ChannelStream >stream. -
sftp(< function >callback) - (void) - Starts an SFTP (protocol version 3) session.
callback
has 2 parameters: < Error >err, < SFTP >sftpConnection. -
end() - (void) - Disconnects the socket.
This is a normal duplex Stream, with the following changes:
-
A boolean property 'allowHalfOpen' exists and behaves similarly to the property of the same name for net.Socket. When the stream's end() is called, if 'allowHalfOpen' is true, only EOF will be sent (the server can still send data if they have not already sent EOF). The default value for this property is
false
. -
For shell():
- setWindow(< integer >rows, < integer >cols, < integer >height, < integer >width) - (void) - Lets the server know that the local terminal window has been resized. The meaning of these arguments are described in the 'Pseudo-TTY settings' section.
-
For exec():
- An 'exit' event will be emitted when the process finishes. If the process finished normally, the process's return value is passed to the 'exit' callback. If the process was interrupted by a signal, the following are passed to the 'exit' callback: null, < string >signalName, < boolean >didCoreDump, < string >description.
-
For shell() and exec():
-
'data' events are passed a second (string) argument to the callback, which indicates whether the data is a special type. So far the only defined type is 'stderr'.
-
signal(< string >signalName) - (void) - Sends a POSIX signal to the current process on the server. Valid signal names are: 'ABRT', 'ALRM', 'FPE', 'HUP', 'ILL', 'INT', 'KILL', 'PIPE', 'QUIT', 'SEGV', 'TERM', 'USR1', and 'USR2'. Also, from the RFC: "Some systems may not implement signals, in which case they SHOULD ignore this message."
-
- end() - The SFTP session was ended.
-
end() - (void) - Ends the SFTP session.
-
fastGet(< string >remotePath, < string >localPath[, < object >options], < function >callback) - (void) - Downloads a file at
remotePath
tolocalPath
using parallel reads for faster throughput.options
has the following defaults:-
concurrency - integer - Number of concurrent reads (default: 25)
-
chunkSize - integer - Size of each read in bytes (default: 32768)
-
step - function(< Number >total_transferred, < Number >chunk, < Number >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
toremotePath
using parallel reads for faster throughput.options
has the following defaults:-
concurrency - integer - Number of concurrent reads (default: 25)
-
chunkSize - integer - Size of each read in bytes (default: 32768)
-
step - function(< Number >total_transferred, < Number >chunk, < Number >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, mode: 0666, bufferSize: 64 * 1024 }
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'.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, autoClose: true }
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) - (void) - Opens a file
filename
formode
with optionalattributes
.mode
is any of the modes supported by fs.open (except sync mode).callback
has 2 parameters: < Error >err, < Buffer >handle. -
close(< Buffer >handle, < function >callback) - (void) - Closes the resource associated with
handle
given by open() or opendir().callback
has 1 parameter: < Error >err. -
read(< Buffer >handle, < Buffer >buffer, < integer >offset, < integer >length, < integer >position, < function >callback) - (void) - Reads
length
bytes from the resource associated withhandle
starting atposition
and stores the bytes inbuffer
starting atoffset
.callback
has 4 parameters: < Error >err, < integer >bytesRead, < Buffer >buffer (offset adjusted), < integer >position. -
write(< Buffer >handle, < Buffer >buffer, < integer >offset, < integer >length, < integer >position, < function >callback) - (void) - Writes
length
bytes frombuffer
starting atoffset
to the resource associated withhandle
starting atposition
.callback
has 1 parameter: < Error >err. -
fstat(< Buffer >handle, < function >callback) - (void) - Retrieves attributes for the resource associated with
handle
.callback
has 2 parameters: < Error >err, < Stats >stats. -
fsetstat(< Buffer >handle, < ATTRS >attributes, < function >callback) - (void) - Sets the attributes defined in
attributes
for the resource associated withhandle
.callback
has 1 parameter: < Error >err. -
futimes(< Buffer >handle, < mixed >atime, < mixed >mtime, < function >callback) - (void) - Sets the access time and modified time for the resource associated with
handle
.atime
andmtime
can be Date instances or UNIX timestamps.callback
has 1 parameter: < Error >err. -
fchown(< Buffer >handle, < integer >uid, < integer >gid, < function >callback) - (void) - Sets the owner for the resource associated with
handle
.callback
has 1 parameter: < Error >err. -
fchmod(< Buffer >handle, < mixed >mode, < function >callback) - (void) - Sets the mode for the resource associated with
handle
.mode
can be an integer or a string containing an octal number.callback
has 1 parameter: < Error >err. -
opendir(< string >path, < function >callback) - (void) - Opens a directory
path
.callback
has 2 parameters: < Error >err, < Buffer >handle. -
readdir(< Buffer >handle, < function >callback) - (void) - Retrieves directory entries from the directory associated with
handle
. This function may need to be called multiple times to receive the entire directory listing.callback
has 2 parameters: < Error >err, < mixed >list.list
is either an Array of{ filename: 'foo', longname: '....', attrs: {...} }
style objects (attrs is of type ATTR) OR boolean false to indicate no more directory entries are available for the givenhandle
. -
unlink(< string >path, < function >callback) - (void) - Removes the file/symlink at
path
.callback
has 1 parameter: < Error >err. -
rename(< string >srcPath, < string >destPath, < function >callback) - (void) - Renames/moves
srcPath
todestPath
.callback
has 1 parameter: < Error >err. -
mkdir(< string >path, [< ATTRS >attributes, ]< function >callback) - (void) - Creates a new directory
path
.callback
has 1 parameter: < Error >err. -
rmdir(< string >path, < function >callback) - (void) - Removes the directory at
path
.callback
has 1 parameter: < Error >err. -
stat(< string >path, < function >callback) - (void) - Retrieves attributes for
path
.callback
has 2 parameter: < Error >err, < Stats >stats. -
lstat(< string >path, < function >callback) - (void) - Retrieves attributes for
path
. Ifpath
is a symlink, the link itself is stat'ed instead of the resource it refers to.callback
has 2 parameters: < Error >err, < Stats >stats. -
setstat(< string >path, < ATTRS >attributes, < function >callback) - (void) - Sets the attributes defined in
attributes
forpath
.callback
has 1 parameter: < Error >err. -
utimes(< string >path, < mixed >atime, < mixed >mtime, < function >callback) - (void) - Sets the access time and modified time for
path
.atime
andmtime
can be Date instances or UNIX timestamps.callback
has 1 parameter: < Error >err. -
chown(< string >path, < integer >uid, < integer >gid, < function >callback) - (void) - Sets the owner for
path
.callback
has 1 parameter: < Error >err. -
chmod(< string >path, < mixed >mode, < function >callback) - (void) - Sets the mode for
path
.mode
can be an integer or a string containing an octal number.callback
has 1 parameter: < Error >err. -
readlink(< string >path, < function >callback) - (void) - Retrieves the target for a symlink at
path
.callback
has 2 parameters: < Error >err, < string >target. -
symlink(< string >targetPath, < string >linkPath, < function >callback) - (void) - Creates a symlink at
linkPath
totargetPath
.callback
has 1 parameter: < Error >err. -
realpath(< string >path, < function >callback) - (void) - Resolves
path
to an absolute path.callback
has 2 parameters: < Error >err, < string >absPath.
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
andmtime
can be either a Date instance or a UNIX timestamp. -
mode
can either be an integer or a string containing an octal number.
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()
-
rows - < integer > - Number of rows (defaults to 24)
-
cols - < integer > - Number of columns (defaults to 80)
-
height - < integer > - Height in pixels (defaults to 480)
-
width - < integer > - Width in pixels (defaults to 640)
-
term - < string > - The value to use for $TERM (defaults to 'vt100')
rows
and cols
override width
and height
when rows
and cols
are non-zero.
Pixel dimensions refer to the drawable area of the window.
Zero dimension parameters are ignored.