Description
An SSH2 client module written in pure JavaScript for node.js.
Development/testing is done against OpenSSH (6.6 currently).
Upgrading from v0.2.x? See the list of changes (including backwards incompatibilities).
Requirements
Install
npm install ssh2
Examples
- Authenticate using keys and execute
uptime
on a server:
var Connection = require('ssh2');
var conn = new Connection();
conn.on('ready', function() {
console.log('Connection :: ready');
conn.exec('uptime', function(err, stream) {
if (err) throw err;
stream.on('exit', function(code, signal) {
console.log('Stream :: exit :: code: ' + code + ', signal: ' + signal);
}).on('close', function() {
console.log('Stream :: close');
conn.end();
}).on('data', function(data) {
console.log('STDOUT: ' + data);
}).stderr.on('data', function(data) {
console.log('STDERR: ' + data);
});
});
}).connect({
host: '192.168.100.100',
port: 22,
username: 'frylock',
privateKey: require('fs').readFileSync('/here/is/my/key')
});
- Authenticate using keys and start an interactive shell session:
var Connection = require('ssh2');
var conn = new Connection();
conn.on('ready', function() {
console.log('Connection :: ready');
conn.shell('uptime', function(err, stream) {
if (err) throw err;
stream.on('close', function() {
console.log('Stream :: close');
conn.end();
}).on('data', function(data) {
console.log('STDOUT: ' + data);
}).stderr.on('data', function(data) {
console.log('STDERR: ' + data);
});
stream.end('ls -l\nexit\n');
});
}).connect({
host: '192.168.100.100',
port: 22,
username: 'frylock',
privateKey: require('fs').readFileSync('/here/is/my/key')
});
- Authenticate using password and send an HTTP request to port 80 on the server:
var Connection = require('ssh2');
var conn = new Connection();
conn.on('ready', function() {
console.log('Connection :: ready');
conn.forwardOut('192.168.100.102', 8000, '127.0.0.1', 80, function(err, stream) {
if (err) throw err;
stream.on('close', function() {
console.log('TCP :: CLOSED');
conn.end();
}).on('data', function(data) {
console.log('TCP :: DATA: ' + data);
}).end([
'HEAD / HTTP/1.1',
'User-Agent: curl/7.27.0',
'Host: 127.0.0.1',
'Accept: */*',
'Connection: close',
'',
''
].join('\r\n'));
});
}).connect({
host: '192.168.100.100',
port: 22,
username: 'frylock',
password: 'nodejsrules'
});
- Authenticate using password and forward remote connections on port 8000 to us:
var Connection = require('ssh2');
var conn = new Connection();
conn.on('ready', function() {
console.log('Connection :: ready');
conn.forwardIn('127.0.0.1', 8000, function(err) {
if (err) throw err;
console.log('Listening for connections on server on port 8000!');
});
}).on('tcp connection', function(info, accept, reject) {
console.log('TCP :: INCOMING CONNECTION:');
console.dir(info);
accept().on('close', function() {
console.log('TCP :: CLOSED');
}).on('data', function(data) {
console.log('TCP :: DATA: ' + data);
}).end([
'HTTP/1.1 404 Not Found',
'Date: Thu, 15 Nov 2012 02:07:58 GMT',
'Server: ForwardedConnection',
'Content-Length: 0',
'Connection: close',
'',
''
].join('\r\n'));
}).connect({
host: '192.168.100.100',
port: 22,
username: 'frylock',
password: 'nodejsrules'
});
- Authenticate using password and get a directory listing via SFTP:
var Connection = require('ssh2');
var conn = new Connection();
conn.on('ready', function() {
console.log('Connection :: ready');
conn.sftp(function(err, sftp) {
if (err) throw err;
sftp.readdir('foo', function(err, list) {
if (err) throw err;
console.dir(list);
conn.end();
});
});
}).connect({
host: '192.168.100.100',
port: 22,
username: 'frylock',
password: 'nodejsrules'
});
var Connection = require('ssh2');
var conn1 = new Connection(),
conn2 = new Connection();
conn1.on('ready', function() {
console.log('FIRST :: connection ready');
conn1.exec('nc 192.168.1.2 22', function(err, stream) {
if (err) {
console.log('FIRST :: exec error: ' + err);
return conn1.end();
}
conn2.connect({
sock: stream,
username: 'user2',
password: 'password2',
});
});
}).connect({
host: '192.168.1.1',
username: 'user1',
password: 'password1',
});
conn2.on('ready', function() {
console.log('SECOND :: connection ready');
conn2.exec('uptime', function(err, stream) {
if (err) {
console.log('SECOND :: exec error: ' + err);
return conn1.end();
}
stream.on('end', function() {
conn1.end();
}).on('data', function(data) {
console.log(data.toString());
});
});
});
- Forward X11 connections (xeyes):
var net = require('net'),
Connection = require('ssh2');
var conn = new Connection();
conn.on('x11', function(info, accept, reject) {
var xserversock = new net.Socket();
xserversock.on('connect', function() {
var xclientsock = accept();
xclientsock.pipe(xserversock).pipe(xclientsock);
});
xserversock.connect(6000, 'localhost');
});
conn.on('ready', function() {
conn.exec('xeyes', { x11: true }, function(err, stream) {
if (err) throw err;
var code = 0;
stream.on('end', function() {
if (code !== 0)
console.log('Do you have X11 forwarding enabled on your SSH server?');
conn.end();
}).on('exit', function(exitcode) {
code = exitcode;
});
});
}).connect({
host: '192.168.1.1',
username: 'foo',
password: 'bar'
});
- Dynamic (1:1) port forwarding using a SOCKSv5 proxy (using socksv5):
var socks = require('socksv5'),
Connection = require('ssh2');
var ssh_config = {
host: '192.168.100.1',
port: 22,
username: 'nodejs',
password: 'rules'
};
socks.createServer(function(info, accept, deny) {
var conn = new Connection();
conn.on('ready', function() {
conn.forwardOut(info.srcAddr,
info.srcPort,
info.dstAddr,
info.dstPort,
function(err, stream) {
if (err)
return deny();
var clientSocket;
if (clientSocket = accept(true)) {
stream.pipe(clientSocket).pipe(stream).on('close', function() {
conn.end();
});
} else
conn.end();
});
}).on('error', function(err) {
deny();
}).connect(ssh_config);
}).listen(1080, 'localhost', function() {
console.log('SOCKSv5 proxy server started on port 1080');
}).useAuth(socks.auth.None());
- Invoke an arbitrary subsystem (netconf in this example):
var Connection = require('ssh2'),
xmlhello = '<?xml version="1.0" encoding="UTF-8"?>'+
'<hello xmlns="urn:ietf:params:xml:ns:netconf:base:1.0">'+
' <capabilities>'+
' <capability>urn:ietf:params:netconf:base:1.0</capability>'+
' </capabilities>'+
'</hello>]]>]]>';
var conn = new Connection();
conn.on('ready', function() {
console.log('Connection :: ready');
conn.subsys('netconf', function(err, stream) {
if (err) throw err;
stream.on('data', function(data) {
console.log(data);
}).write(xmlhello);
});
}).connect({
host: '1.2.3.4',
port: 22,
username: 'blargh',
password: 'honk'
});
API
require('ssh2')
returns a Connection constructor
Connection events
-
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 a ChannelStream
object. Calling reject
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()
).
-
x11(< object >details, < function >accept, < function >reject) - An incoming X11 connection is being requested. Calling accept
accepts the connection and returns a ChannelStream
object. Calling reject
rejects the connection and no further action is needed. details
contains:
-
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 (here echo
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 to finish
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
.
Connection methods
Authentication method priorities: Password -> Private Key -> Agent (-> keyboard-interactive if tryKeyboard
is true) -> None
-
exec(< string >command[, < object >options], < function >callback) - (void) - Executes command
on the server. Valid options
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'). Setting up a pseudo-tty can be useful when working with remote processes that expect input from an actual terminal (e.g. sudo's password prompt).
-
x11 - < mixed > - Set to true to use defaults below, a number to specify a specific screen number, or an object with the following valid properties:
callback
has 2 parameters: < Error >err, < ChannelStream >stream.
-
shell([[< object >window,] < object >options]< function >callback) - (void) - Starts an interactive shell session on the server, with optional window
pseudo-tty settings (see 'Pseudo-TTY settings'). options
supports the 'x11' option as described in exec(). callback
has 2 parameters: < Error >err, < ChannelStream >stream.
-
forwardIn(< string >remoteAddr, < integer >remotePort, < function >callback) - (void) - Bind to remoteAddr
on remotePort
on the server and forward incoming connections. callback
has 2 parameters: < Error >err, < integer >port (port
is the assigned port number if remotePort
was 0). Here are some special values for remoteAddr
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
on remotePort
on the server and stop forwarding incoming connections. Until callback
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
and srcPort
as the originating address and port and dstIP
and dstPort
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.
-
subsys(< string >subsystem, < function >callback) - (void) - Invokes subsystem
on the server. callback
has 2 parameters: < Error >err, < ChannelStream >stream.
-
end() - (void) - Disconnects the socket.
ChannelStream
This is a normal streams2 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 true
.
-
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():
-
The readable side represents stdout and the writable side represents stdin.
-
A stderr
property that represents the stream of output from 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." Note: If you are trying to send SIGINT and you find signal() doesn't work, try writing '\x03' to the exec/shell stream instead.
SFTP events
- end() - The SFTP session was ended.
SFTP methods
-
end() - (void) - Ends the SFTP session.
-
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) - (void) - Opens a file filename
for mode
with optional attributes
. 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 with handle
starting at position
and stores the bytes in buffer
starting at offset
. 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 from buffer
starting at offset
to the resource associated with handle
starting at position
. 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 with handle
. 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
and mtime
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(< mixed >location, < function >callback) - (void) - 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. 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) - (void) - Removes the file/symlink at path
. callback
has 1 parameter: < Error >err.
-
rename(< string >srcPath, < string >destPath, < function >callback) - (void) - Renames/moves srcPath
to destPath
. 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
. If path
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
for path
. 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
and mtime
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
to targetPath
. 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.
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:
Stats
An object with the same attributes as an ATTRS object with the addition of the following methods:
Pseudo-TTY settings
-
rows - < integer > - Number of rows Default: 24
-
cols - < integer > - Number of columns Default: 80
-
height - < integer > - Height in pixels Default: 480
-
width - < integer > - Width in pixels Default: 640
-
term - < string > - The value to use for $TERM Default: '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.