Description
SSH2 client and server modules written in pure JavaScript for node.js.
Development/testing is done against OpenSSH (8.0 currently).
Changes (breaking or otherwise) in v1.0.0 can be found here.
Table of Contents
Requirements
- node.js -- v10.16.0 or newer
- node v12.0.0 or newer for Ed25519 key support
- (Optional)
cpu-features
is set as an optional package dependency (you do not need to install it explicitly/separately from ssh2
) that will be automatically built and used if possible. See the project's documentation for its own requirements.
- This addon is currently used to help generate an optimal default cipher list
Installation
npm install ssh2
Client Examples
Execute 'uptime' on a server
const { readFileSync } = require('fs');
const { Client } = require('ssh2');
const conn = new Client();
conn.on('ready', () => {
console.log('Client :: ready');
conn.exec('uptime', (err, stream) => {
if (err) throw err;
stream.on('close', (code, signal) => {
console.log('Stream :: close :: code: ' + code + ', signal: ' + signal);
conn.end();
}).on('data', (data) => {
console.log('STDOUT: ' + data);
}).stderr.on('data', (data) => {
console.log('STDERR: ' + data);
});
});
}).connect({
host: '192.168.100.100',
port: 22,
username: 'frylock',
privateKey: readFileSync('/path/to/my/key')
});
Start an interactive shell session
const { readFileSync } = require('fs');
const { Client } = require('ssh2');
const conn = new Client();
conn.on('ready', () => {
console.log('Client :: ready');
conn.shell((err, stream) => {
if (err) throw err;
stream.on('close', () => {
console.log('Stream :: close');
conn.end();
}).on('data', (data) => {
console.log('OUTPUT: ' + data);
});
stream.end('ls -l\nexit\n');
});
}).connect({
host: '192.168.100.100',
port: 22,
username: 'frylock',
privateKey: readFileSync('/path/to/my/key')
});
Send a raw HTTP request to port 80 on the server
const { Client } = require('ssh2');
const conn = new Client();
conn.on('ready', () => {
console.log('Client :: ready');
conn.forwardOut('192.168.100.102', 8000, '127.0.0.1', 80, (err, stream) => {
if (err) throw err;
stream.on('close', () => {
console.log('TCP :: CLOSED');
conn.end();
}).on('data', (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'
});
Forward local connections to port 8000 on the server to us
const { Client } = require('ssh2');
const conn = new Client();
conn.on('ready', () => {
console.log('Client :: ready');
conn.forwardIn('127.0.0.1', 8000, (err) => {
if (err) throw err;
console.log('Listening for connections on server on port 8000!');
});
}).on('tcp connection', (info, accept, reject) => {
console.log('TCP :: INCOMING CONNECTION:');
console.dir(info);
accept().on('close', () => {
console.log('TCP :: CLOSED');
}).on('data', (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'
});
Get a directory listing via SFTP
const { Client } = require('ssh2');
const conn = new Client();
conn.on('ready', () => {
console.log('Client :: ready');
conn.sftp((err, sftp) => {
if (err) throw err;
sftp.readdir('foo', (err, list) => {
if (err) throw err;
console.dir(list);
conn.end();
});
});
}).connect({
host: '192.168.100.100',
port: 22,
username: 'frylock',
password: 'nodejsrules'
});
Connection hopping
const { Client } = require('ssh2');
const conn1 = new Client();
const conn2 = new Client();
conn1.on('ready', () => {
console.log('FIRST :: connection ready');
conn1.forwardOut('127.0.0.1', 12345, '10.1.1.40', 22, (err, stream) => {
if (err) {
console.log('FIRST :: forwardOut 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', () => {
console.log('SECOND :: connection ready');
conn2.exec('uptime', (err, stream) => {
if (err) {
console.log('SECOND :: exec error: ' + err);
return conn1.end();
}
stream.on('close', () => {
conn1.end();
}).on('data', (data) => {
console.log(data.toString());
});
});
});
Forward remote X11 connections
const { Socket } = require('net');
const { Client } = require('ssh2');
const conn = new Client();
conn.on('x11', (info, accept, reject) => {
const xserversock = new net.Socket();
xserversock.on('connect', () => {
const xclientsock = accept();
xclientsock.pipe(xserversock).pipe(xclientsock);
});
xserversock.connect(6000, 'localhost');
});
conn.on('ready', () => {
conn.exec('xeyes', { x11: true }, (err, stream) => {
if (err) throw err;
let code = 0;
stream.on('close', () => {
if (code !== 0)
console.log('Do you have X11 forwarding enabled on your SSH server?');
conn.end();
}).on('exit', (exitcode) => {
code = exitcode;
});
});
}).connect({
host: '192.168.1.1',
username: 'foo',
password: 'bar'
});
Dynamic (1:1) port forwarding using a SOCKSv5 proxy (using socksv5)
const socks = require('socksv5');
const { Client } = require('ssh2');
const sshConfig = {
host: '192.168.100.1',
port: 22,
username: 'nodejs',
password: 'rules'
};
socks.createServer((info, accept, deny) => {
const conn = new Client();
conn.on('ready', () => {
conn.forwardOut(info.srcAddr,
info.srcPort,
info.dstAddr,
info.dstPort,
(err, stream) => {
if (err) {
conn.end();
return deny();
}
const clientSocket = accept(true);
if (clientSocket) {
stream.pipe(clientSocket).pipe(stream).on('close', () => {
conn.end();
});
} else {
conn.end();
}
});
}).on('error', (err) => {
deny();
}).connect(sshConfig);
}).listen(1080, 'localhost', () => {
console.log('SOCKSv5 proxy server started on port 1080');
}).useAuth(socks.auth.None());
Make HTTP(S) connections easily using a custom http(s).Agent
const http = require('http');
const { Client, HTTPAgent, HTTPSAgent } = require('ssh2');
const sshConfig = {
host: '192.168.100.1',
port: 22,
username: 'nodejs',
password: 'rules'
};
const agent = new HTTPAgent(sshConfig);
http.get({
host: '192.168.200.1',
agent,
headers: { Connection: 'close' }
}, (res) => {
console.log(res.statusCode);
console.dir(res.headers);
res.resume();
});
Invoke an arbitrary subsystem
const { Client } = require('ssh2');
const 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>]]>]]>`;
const conn = new Client();
conn.on('ready', () => {
console.log('Client :: ready');
conn.subsys('netconf', (err, stream) => {
if (err) throw err;
stream.on('data', (data) => {
console.log(data);
}).write(xmlhello);
});
}).connect({
host: '1.2.3.4',
port: 22,
username: 'blargh',
password: 'honk'
});
Server Examples
Password and public key authentication and non-interactive (exec) command execution
const { timingSafeEqual } = require('crypto');
const { readFileSync } = require('fs');
const { inspect } = require('util');
const { parseKey, Server } = require('ssh2');
const allowedUser = Buffer.from('foo');
const allowedPassword = Buffer.from('bar');
const allowedPubKey = parseKey(readFileSync('foo.pub'));
function checkValue(input, allowed) {
const autoReject = (input.length !== allowed.length);
if (autoReject) {
allowed = input;
}
const isMatch = timingSafeEqual(input, allowed);
return (!autoReject && isMatch);
}
new Server({
hostKeys: [readFileSync('host.key')]
}, (client) => {
console.log('Client connected!');
client.on('authentication', (ctx) => {
let allowed = true;
if (!checkValue(Buffer.from(ctx.username), allowedUser))
allowed = false;
switch (ctx.method) {
case 'password':
if (!checkValue(Buffer.from(ctx.password), allowedPassword))
return ctx.reject();
break;
case 'publickey':
if (ctx.key.algo !== allowedPubKey.type
|| !checkValue(ctx.key.data, allowedPubKey.getPublicSSH())
|| (ctx.signature && allowedPubKey.verify(ctx.blob, ctx.signature) !== true)) {
return ctx.reject();
}
break;
default:
return ctx.reject();
}
if (allowed)
ctx.accept();
else
ctx.reject();
}).on('ready', () => {
console.log('Client authenticated!');
client.on('session', (accept, reject) => {
const session = accept();
session.once('exec', (accept, reject, info) => {
console.log('Client wants to execute: ' + inspect(info.command));
const stream = accept();
stream.stderr.write('Oh no, the dreaded errors!\n');
stream.write('Just kidding about the errors!\n');
stream.exit(0);
stream.end();
});
});
}).on('close', () => {
console.log('Client disconnected');
});
}).listen(0, '127.0.0.1', function() {
console.log('Listening on port ' + this.address().port);
});
SFTP-only server
const { timingSafeEqual } = require('crypto');
const { readFileSync } = require('fs');
const { inspect } = require('util');
const {
Server,
sftp: {
OPEN_MODE,
STATUS_CODE,
},
} = require('ssh2');
const allowedUser = Buffer.from('foo');
const allowedPassword = Buffer.from('bar');
function checkValue(input, allowed) {
const autoReject = (input.length !== allowed.length);
if (autoReject) {
allowed = input;
}
const isMatch = timingSafeEqual(input, allowed);
return (!autoReject && isMatch);
}
new ssh2.Server({
hostKeys: [readFileSync('host.key')]
}, (client) => {
console.log('Client connected!');
client.on('authentication', (ctx) => {
let allowed = true;
if (!checkValue(Buffer.from(ctx.username), allowedUser))
allowed = false;
switch (ctx.method) {
case 'password':
if (!checkValue(Buffer.from(ctx.password), allowedPassword))
return ctx.reject();
break;
default:
return ctx.reject();
}
if (allowed)
ctx.accept();
else
ctx.reject();
}).on('ready', () => {
console.log('Client authenticated!');
client.on('session', (accept, reject) => {
const session = accept();
session.on('sftp', (accept, reject) => {
console.log('Client SFTP session');
const openFiles = new Map();
let handleCount = 0;
const sftp = accept();
sftp.on('OPEN', (reqid, filename, flags, attrs) => {
if (filename !== '/tmp/foo.txt' || !(flags & OPEN_MODE.WRITE))
return sftp.status(reqid, STATUS_CODE.FAILURE);
const handle = Buffer.alloc(4);
openFiles.set(handleCount, true);
handle.writeUInt32BE(handleCount++, 0);
console.log('Opening file for write')
sftp.handle(reqid, handle);
}).on('WRITE', (reqid, handle, offset, data) => {
if (handle.length !== 4
|| !openFiles.has(handle.readUInt32BE(0))) {
return sftp.status(reqid, STATUS_CODE.FAILURE);
}
sftp.status(reqid, STATUS_CODE.OK);
console.log('Write to file at offset ${offset}: ${inspect(data)}');
}).on('CLOSE', (reqid, handle) => {
let fnum;
if (handle.length !== 4
|| !openFiles.has(fnum = handle.readUInt32BE(0))) {
return sftp.status(reqid, STATUS_CODE.FAILURE);
}
console.log('Closing file');
openFiles.delete(fnum);
sftp.status(reqid, STATUS_CODE.OK);
});
});
});
}).on('close', () => {
console.log('Client disconnected');
});
}).listen(0, '127.0.0.1', function() {
console.log('Listening on port ' + this.address().port);
});
You can find more examples in the examples
directory of this repository.
API
require('ssh2').Client
is the Client constructor.
require('ssh2').Server
is the Server constructor.
require('ssh2').utils
is an object containing some useful utilities.
require('ssh2').HTTPAgent
is an http.Agent
constructor.
require('ssh2').HTTPSAgent
is an https.Agent
constructor. Its API is the same as HTTPAgent
except it's for HTTPS connections.
Agent-related
require('ssh2').AgentProtocol
is a Duplex stream class that aids in communicating over the OpenSSH agent protocol.
require('ssh2').BaseAgent
is a base class for creating custom authentication agents.
require('ssh2').createAgent
is a helper function that creates a new agent instance using the same logic as the agent
configuration option: if the platform is Windows and it's the value "pageant", it creates a PageantAgent
, otherwise if it's not a path to a Windows pipe it creates a CygwinAgent
. In all other cases, it creates an OpenSSHAgent
.
require('ssh2').CygwinAgent
is an agent class implementation that communicates with agents in a Cygwin environment.
require('ssh2').OpenSSHAgent
is an agent class implementation that communicates with OpenSSH agents over a UNIX socket.
require('ssh2').PageantAgent
is an agent class implementation that communicates with Pageant agent processes.
Client
Client 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 Channel
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.
-
destIP - string - The remote IP the connection was received on (given in earlier call to forwardIn()
).
-
destPort - 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 Channel
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.
-
unix connection(< object >details, < function >accept, < function >reject) - An incoming forwarded UNIX socket connection is being requested. Calling accept
accepts the connection and returns a Channel
object. Calling reject
rejects the connection and no further action is needed. details
contains:
- socketPath - string - The originating UNIX socket path of the connection.
-
change password(< string >prompt, < 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.
-
handshake(< object >negotiated) - Emitted when a handshake has completed (either initial or rekey). negotiated
contains the negotiated details of the handshake and is of the form:
{ kex: 'ecdh-sha2-nistp256',
srvHostKey: 'rsa-sha2-512',
cs: {
cipher: 'aes128-gcm',
mac: '',
compress: 'none',
lang: ''
},
sc: {
cipher: 'aes128-gcm',
mac: '',
compress: 'none',
lang: ''
}
}
-
rekey() - Emitted when a rekeying operation has completed (either client or server-initiated).
-
hostkeys(< array >keys) - Emitted when the server announces its available host keys. keys
is the list of parsed (using parseKey()
) host public keys.
-
error(< Error >err) - An error occurred. A 'level' property indicates 'client-socket' for socket-level errors and 'client-ssh' for SSH disconnection messages. In the case of 'client-ssh' messages, there may be a 'description' property that provides more detail.
-
end() - The socket was disconnected.
-
close() - The socket was closed.
Client methods
-
(constructor)() - Creates and returns a new Client 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
-
localAddress - string - IP address of the network interface to use to connect to the server. Default: (none -- determined by OS)
-
localPort - string - The local port number to connect from. Default: (none -- determined by OS)
-
forceIPv4 - boolean - Only connect via resolved IPv4 address for host
. Default: false
-
forceIPv6 - boolean - Only connect via resolved IPv6 address for host
. Default: false
-
hostHash - string - Any valid hash algorithm supported by node. The host's key is hashed using this algorithm and passed to the hostVerifier function as a hex string. Default: (none)
-
hostVerifier - function - Function with parameters (hashedKey[, callback])
where hashedKey
is a string hex hash of the host's key for verification purposes. Return true
to continue with the handshake or false
to reject and disconnect, or call callback()
with true
or false
if you need to perform asynchronous verification. Default: (auto-accept if hostVerifier
is not set)
-
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 or (actual) path to a cygwin "UNIX socket." Default: (none)
-
agentForward - boolean - Set to true
to use OpenSSH agent forwarding (auth-agent@openssh.com
) for the life of the connection. agent
must also be set to use this feature. Default: false
-
privateKey - mixed - Buffer or string that contains a private key for either key-based or hostbased user authentication (OpenSSH format). Default: (none)
-
passphrase - string - For an encrypted private key, this is the passphrase used to decrypt it. Default: (none)
-
localHostname - string - Along with localUsername and privateKey, set this to a non-empty string for hostbased user authentication. Default: (none)
-
localUsername - string - Along with localHostname and privateKey, set this to a non-empty string for hostbased user authentication. Default: (none)
-
tryKeyboard - boolean - Try keyboard-interactive user authentication if primary user authentication method fails. If you set this to true
, you need to handle the keyboard-interactive
event. Default: false
-
authHandler - mixed - Either an array of objects as described below or a function with parameters (methodsLeft, partialSuccess, callback)
where methodsLeft
and partialSuccess
are null
on the first authentication attempt, otherwise are an array and boolean respectively. Return or call callback()
with either the name of the authentication method or an object containing the method name along with method-specific details to try next (return/pass false
to signal no more methods to try). Valid method names are: 'none', 'password', 'publickey', 'agent', 'keyboard-interactive', 'hostbased'
. Default: function that follows a set method order: None -> Password -> Private Key -> Agent (-> keyboard-interactive if tryKeyboard
is true
) -> Hostbased
-
When returning or calling callback()
with an object, it can take one of the following forms:
{
type: 'none',
username: 'foo',
}
{
type: 'password'
username: 'foo',
password: 'bar',
}
{
type: 'publickey'
username: 'foo',
key: ...,
passphrase: ...,
}
{
type: 'hostbased'
username: 'foo',
localHostname: 'baz',
localUsername: 'quux',
key: ...,
passphrase: ...,
}
{
type: 'agent'
username: 'foo',
agent: ...,
}
{
type: 'keyboard-interactive'
username: 'foo',
prompt: (name, instructions, instructionsLang, prompts, finish) => {
},
}
-
keepaliveInterval - integer - How often (in milliseconds) to send SSH-level keepalive packets to the server (in a similar way as OpenSSH's ServerAliveInterval config option). Set to 0 to disable. Default: 0
-
keepaliveCountMax - integer - How many consecutive, unanswered SSH-level keepalive packets that can be sent to the server before disconnection (similar to OpenSSH's ServerAliveCountMax config option). Default: 3
-
readyTimeout - integer - How long (in milliseconds) to wait for the SSH handshake to complete. Default: 20000
-
sock - ReadableStream - A ReadableStream to use for communicating with the server instead of creating and using a new TCP connection (useful for connection hopping).
-
strictVendor - boolean - Performs a strict server vendor check before sending vendor-specific requests, etc. (e.g. check for OpenSSH server when using openssh_noMoreSessions()
) Default: true
-
algorithms - object - This option allows you to explicitly override the default transport layer algorithms used for the connection. The value for each category must either be an array of valid algorithm names to set an exact list (with the most preferrable first) or an object containing append
, prepend
, and/or remove
properties that each contain an array of algorithm names or RegExps to match to adjust default lists for each category. Valid keys:
-
kex - mixed - Key exchange algorithms.
- Default list (in order from most to least preferrable):
curve25519-sha256 (node v14.0.0+)
curve25519-sha256@libssh.org (node v14.0.0+)
ecdh-sha2-nistp256
ecdh-sha2-nistp384
ecdh-sha2-nistp521
diffie-hellman-group-exchange-sha256
diffie-hellman-group14-sha256
diffie-hellman-group15-sha512
diffie-hellman-group16-sha512
diffie-hellman-group17-sha512
diffie-hellman-group18-sha512
- Other supported names:
diffie-hellman-group-exchange-sha1
diffie-hellman-group14-sha1
diffie-hellman-group1-sha1
-
serverHostKey - mixed - Server host key formats.
- Default list (in order from most to least preferrable):
ssh-ed25519
(node v12.0.0+)ecdsa-sha2-nistp256
ecdsa-sha2-nistp384
ecdsa-sha2-nistp521
rsa-sha2-512
rsa-sha2-256
ssh-rsa
- Other supported names:
-
cipher - mixed - Ciphers.
- Default list (in order from most to least preferrable):
chacha20-poly1305@openssh.com
(priority of chacha20-poly1305 may vary depending upon CPU and/or optional binding availability)aes128-gcm
aes128-gcm@openssh.com
aes256-gcm
aes256-gcm@openssh.com
aes128-ctr
aes192-ctr
aes256-ctr
- Other supported names:
3des-cbc
aes256-cbc
aes192-cbc
aes128-cbc
arcfour256
arcfour128
arcfour
blowfish-cbc
cast128-cbc
-
hmac - mixed - (H)MAC algorithms.
- Default list (in order from most to least preferrable):
hmac-sha2-256-etm@openssh.com
hmac-sha2-512-etm@openssh.com
hmac-sha1-etm@openssh.com
hmac-sha2-256
hmac-sha2-512
hmac-sha1
- Other supported names:
hmac-md5
hmac-sha2-256-96
hmac-sha2-512-96
hmac-ripemd160
hmac-sha1-96
hmac-md5-96
-
compress - mixed - Compression algorithms.
- Default list (in order from most to least preferrable):
- Other supported names:
-
debug - function - Set this to a function that receives a single string argument to get detailed (local) debug information. Default: (none)
-
exec(< string >command[, < object >options], < function >callback) - (void) - Executes command
on the server. callback
has 2 parameters: < Error >err, < Channel >stream. 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, set to a number to specify a specific screen number, or an object with the following valid properties:
-
single - boolean - Allow just a single connection? Default: false
-
screen - number - Screen number to use Default: 0
-
protocol - string - The authentication protocol name. Default: 'MIT-MAGIC-COOKIE-1'
-
cookie - mixed - The authentication cookie. Can be a hex string or a Buffer containing the raw cookie value (which will be converted to a hex string). Default: (random 16 byte value)
-
shell([[< mixed >window,] < object >options]< function >callback) - (void) - Starts an interactive shell session on the server, with an optional window
object containing pseudo-tty settings (see 'Pseudo-TTY settings'). If window === false
, then no pseudo-tty is allocated. options
supports the x11
and env
options as described in exec()
. callback
has 2 parameters: < Error >err, < Channel >stream.
-
forwardIn(< string >remoteAddr, < integer >remotePort, < function >callback) - (void) - Bind to remoteAddr
on remotePort
on the server and forward incoming TCP 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 from remoteAddr
on remotePort
on the server and stop forwarding incoming TCP 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, < Channel >stream.
-
sftp(< function >callback) - (void) - Starts an SFTP session. callback
has 2 parameters: < Error >err, < SFTP >sftp. For methods available on sftp
, see the SFTP
client documentation.
-
subsys(< string >subsystem, < function >callback) - (void) - Invokes subsystem
on the server. callback
has 2 parameters: < Error >err, < Channel >stream.
-
rekey([< function >callback]) - (void) - Initiates a rekey with the server. If callback
is supplied, it is added as a one-time handler for the rekey
event.
-
end() - (void) - Disconnects the socket.
-
openssh_noMoreSessions(< function >callback) - (void) - OpenSSH extension that sends a request to reject any new sessions (e.g. exec, shell, sftp, subsys) for this connection. callback
has 1 parameter: < Error >err.
-
openssh_forwardInStreamLocal(< string >socketPath, < function >callback) - (void) - OpenSSH extension that binds to a UNIX domain socket at socketPath
on the server and forwards incoming connections. callback
has 1 parameter: < Error >err.
-
openssh_unforwardInStreamLocal(< string >socketPath, < function >callback) - (void) - OpenSSH extension that unbinds from a UNIX domain socket at socketPath
on the server and stops forwarding incoming connections. callback
has 1 parameter: < Error >err.
-
openssh_forwardOutStreamLocal(< string >socketPath, < function >callback) - (void) - OpenSSH extension that opens a connection to a UNIX domain socket at socketPath
on the server. callback
has 2 parameters: < Error >err, < Channel >stream.
Server
Server events
-
connection(< Connection >client, < object >info) - A new client has connected. info
contains the following properties:
-
ip - string - The remoteAddress
of the connection.
-
family - string - The remoteFamily
of the connection.
-
port - integer - The remotePort
of the connection.
-
header - object - Information about the client's header:
-
identRaw - string - The raw client identification string.
-
versions - object - Various version information:
-
comments - string - Any text that comes after the software name/version.
Example: the identification string SSH-2.0-OpenSSH_6.6.1p1 Ubuntu-2ubuntu2
would be parsed as:
{ identRaw: 'SSH-2.0-OpenSSH_6.6.1p1 Ubuntu-2ubuntu2',
version: {
protocol: '2.0',
software: 'OpenSSH_6.6.1p1'
},
comments: 'Ubuntu-2ubuntu2' }
Server methods
-
(constructor)(< object >config[, < function >connectionListener]) - Creates and returns a new Server instance. Server instances also have the same methods/properties/events as net.Server
. connectionListener
if supplied, is added as a connection
listener. Valid config
properties:
-
hostKeys - array - An array of either Buffers/strings that contain host private keys or objects in the format of { key: <Buffer/string>, passphrase: <string> }
for encrypted private keys. (Required) Default: (none)
-
algorithms - object - This option allows you to explicitly override the default transport layer algorithms used for incoming client connections. Each value must be an array of valid algorithms for that category. The order of the algorithms in the arrays are important, with the most favorable being first. For a list of valid and default algorithm names, please review the documentation for the version of ssh2
used by this module. Valid keys:
-
kex - array - Key exchange algorithms.
-
cipher - array - Ciphers.
-
serverHostKey - array - Server host key formats.
-
hmac - array - (H)MAC algorithms.
-
compress - array - Compression algorithms.
-
greeting - string - A message that is sent to clients immediately upon connection, before handshaking begins. Note: Most clients usually ignore this. Default: (none)
-
banner - string - A message that is sent to clients once, right before authentication begins. Default: (none)
-
ident - string - A custom server software name/version identifier. Default: 'ssh2js' + moduleVersion + 'srv'
-
highWaterMark - integer - This is the highWaterMark
to use for the parser 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)
Connection events
-
authentication(< AuthContext >ctx) - The client has requested authentication. ctx.username
contains the client username, ctx.method
contains the requested authentication method, and ctx.accept()
and ctx.reject([< Array >authMethodsLeft[, < Boolean >isPartialSuccess]])
are used to accept or reject the authentication request respectively. abort
is emitted if the client aborts the authentication request. Other properties/methods available on ctx
depends on the ctx.method
of authentication the client has requested:
-
password
:
-
password - string - This is the password sent by the client.
-
requestChange(< string >prompt, < function >callback) - (void) - Sends a password change request to the client. callback
is called with (newPassword)
, where newPassword
is the new password supplied by the client. You may accept, reject, or prompt for another password change after callback
is called.
-
keyboard-interactive
:
-
submethods - array - A list of preferred authentication "sub-methods" sent by the client. This may be used to determine what (if any) prompts to send to the client.
-
prompt(< array >prompts[, < string >title[, < string >instructions]], < function >callback) - (void) - Send prompts to the client. 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). callback
is called with (responses)
, where responses
is an array of string responses matching up to the prompts
.
-
publickey
:
-
key - object - Contains information about the public key sent by the client:
-
blob - mixed - If the value is undefined
, the client is only checking the validity of the key
. If the value is a Buffer, then this contains the data to be verified that is passed to (along with the signature) key.verify()
where key
is a public key parsed with parseKey()
.
-
signature - mixed - If the value is undefined
, the client is only checking the validity of the key
. If the value is a Buffer, then this contains a signature to be verified that is passed to (along with the blob) key.verify()
where key
is a public key parsed with parseKey()
.
-
hostbased
:
-
key - object - Contains information about the public key sent by the client:
-
blob - Buffer - This contains the data to be verified that is passed to (along with the signature) key.verify()
where key
is a public key parsed with parseKey()
.
-
signature - Buffer - This contains a signature to be verified that is passed to (along with the blob) key.verify()
where key
is a public key parsed with parseKey()
.
-
localHostname - string - The local hostname provided by the client.
-
localUsername - string - The local username provided by the client.
-
ready() - Emitted when the client has been successfully authenticated.
-
session(< function >accept, < function >reject) - Emitted when the client has requested a new session. Sessions are used to start interactive shells, execute commands, request X11 forwarding, etc. accept()
returns a new Session instance.
-
tcpip(< function >accept, < function >reject, < object >info) - Emitted when the client has requested an outbound (TCP) connection. accept()
returns a new Channel instance representing the connection. info
contains:
-
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.
-
openssh.streamlocal(< function >accept, < function >reject, < object >info) - Emitted when the client has requested a connection to a UNIX domain socket. accept()
returns a new Channel instance representing the connection. info
contains:
- socketPath - string - Destination socket path of outgoing connection.
-
request(< mixed >accept, < mixed >reject, < string >name, < object >info) - Emitted when the client has sent a global request for name
(e.g. tcpip-forward
or cancel-tcpip-forward
). accept
and reject
are functions if the client requested a response. If bindPort === 0
, you should pass the chosen port to accept()
so that the client will know what port was bound. info
contains additional details about the request:
-
handshake(< object >negotiated) - Emitted when a handshake has completed (either initial or rekey). negotiated
contains the negotiated details of the handshake and is of the form:
{ kex: 'ecdh-sha2-nistp256',
srvHostKey: 'rsa-sha2-512',
cs: {
cipher: 'aes128-gcm',
mac: '',
compress: 'none',
lang: ''
},
sc: {
cipher: 'aes128-gcm',
mac: '',
compress: 'none',
lang: ''
}
}
-
rekey() - Emitted when a rekeying operation has completed (either client or server-initiated).
-
error(< Error >err) - An error occurred.
-
end() - The client socket disconnected.
-
close() - The client socket was closed.
Connection methods
-
end() - (void) - Closes the client connection.
-
x11(< string >originAddr, < integer >originPort, < function >callback) - (void) - Alert the client of an incoming X11 client connection from originAddr
on port originPort
. callback
has 2 parameters: < Error >err, < Channel >stream.
-
forwardOut(< string >boundAddr, < integer >boundPort, < string >remoteAddr, < integer >remotePort, < function >callback) - (void) - Alert the client of an incoming TCP connection on boundAddr
on port boundPort
from remoteAddr
on port remotePort
. callback
has 2 parameters: < Error >err, < Channel >stream.
-
openssh_forwardOutStreamLocal(< string >socketPath, < function >callback) - (void) - Alert the client of an incoming UNIX domain socket connection on socketPath
. callback
has 2 parameters: < Error >err, < Channel >stream.
-
rekey([< function >callback]) - (void) - Initiates a rekey with the client. If callback
is supplied, it is added as a one-time handler for the rekey
event.
Session events
-
pty(< mixed >accept, < mixed >reject, < object >info) - The client requested allocation of a pseudo-TTY for this session. accept
and reject
are functions if the client requested a response. info
has these properties:
-
cols - integer - The number of columns for the pseudo-TTY.
-
rows - integer - The number of rows for the pseudo-TTY.
-
width - integer - The width of the pseudo-TTY in pixels.
-
height - integer - The height of the pseudo-TTY in pixels.
-
modes - object - Contains the requested terminal modes of the pseudo-TTY keyed on the mode name with the value being the mode argument. (See the table at the end for valid names).
-
window-change(< mixed >accept, < mixed >reject, < object >info) - The client reported a change in window dimensions during this session. accept
and reject
are functions if the client requested a response. info
has these properties:
-
cols - integer - The new number of columns for the client window.
-
rows - integer - The new number of rows for the client window.
-
width - integer - The new width of the client window in pixels.
-
height - integer - The new height of the client window in pixels.
-
x11(< mixed >accept, < mixed >reject, < object >info) - The client requested X11 forwarding. accept
and reject
are functions if the client requested a response. info
has these properties:
-
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.
-
env(< mixed >accept, < mixed >reject, < object >info) - The client requested an environment variable to be set for this session. accept
and reject
are functions if the client requested a response. info
has these properties:
-
signal(< mixed >accept, < mixed >reject, < object >info) - The client has sent a signal. accept
and reject
are functions if the client requested a response. info
has these properties:
- name - string - The signal name (e.g.
SIGUSR1
).
-
auth-agent(< mixed >accept, < mixed >reject) - The client has requested incoming ssh-agent requests be forwarded to them. accept
and reject
are functions if the client requested a response.
-
shell(< mixed >accept, < mixed >reject) - The client has requested an interactive shell. accept
and reject
are functions if the client requested a response. accept()
returns a Channel for the interactive shell.
-
exec(< mixed >accept, < mixed >reject, < object >info) - The client has requested execution of a command string. accept
and reject
are functions if the client requested a response. accept()
returns a Channel for the command execution. info
has these properties:
- command - string - The command line to be executed.
-
sftp(< mixed >accept, < mixed >reject) - The client has requested the SFTP subsystem. accept
and reject
are functions if the client requested a response. accept()
returns an SFTP instance in server mode (see the SFTP
documentation for details). info
has these properties:
-
subsystem(< mixed >accept, < mixed >reject, < object >info) - The client has requested an arbitrary subsystem. accept
and reject
are functions if the client requested a response. accept()
returns a Channel for the subsystem. info
has these properties:
- name - string - The name of the subsystem.
-
close() - The session was closed.
Channel
This is a normal streams2 Duplex Stream (used both by clients and servers), 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
.
-
A close
event is emitted once the channel is completely closed on both the client and server.
-
Client-specific:
-
For exec():
-
An exit
event may (the SSH2 spec says it is optional) 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.
-
If there was an exit
event, the close
event will be passed the same arguments for convenience.
-
A stderr
property contains a Readable stream that represents output from stderr.
-
For shell() and exec():
-
The readable side represents stdout and the writable side represents stdin.
-
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'. Some server implementations may ignore this request if they do not support signals. Note: If you are trying to send SIGINT and you find signal()
doesn't work, try writing '\x03'
to the Channel stream instead.
-
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.
-
Server-specific:
-
For exec-enabled channel instances there is an additional method available that may be called right before you close the channel. It has two different signatures:
-
exit(< integer >exitCode) - (void) - Sends an exit status code to the client.
-
exit(< string >signalName[, < boolean >coreDumped[, < string >errorMsg]]) - (void) - Sends an exit status code to the client.
-
For exec and shell-enabled channel instances, channel.stderr
is a writable stream.
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'
-
modes - < object > - An object containing Terminal Modes as keys, with each value set to each mode argument. Default: null
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.
Terminal modes
Name | Description |
---|
VINTR | Interrupt character; 255 if none. Similarly for the other characters. Not all of these characters are supported on all systems. |
VQUIT | The quit character (sends SIGQUIT signal on POSIX systems). |
VERASE | Erase the character to left of the cursor. |
VKILL | Kill the current input line. |
VEOF | End-of-file character (sends EOF from the terminal). |
VEOL | End-of-line character in addition to carriage return and/or linefeed. |
VEOL2 | Additional end-of-line character. |
VSTART | Continues paused output (normally control-Q). |
VSTOP | Pauses output (normally control-S). |
VSUSP | Suspends the current program. |
VDSUSP | Another suspend character. |
VREPRINT | Reprints the current input line. |
VWERASE | Erases a word left of cursor. |
VLNEXT | Enter the next character typed literally, even if it is a special character |
VFLUSH | Character to flush output. |
VSWTCH | Switch to a different shell layer. |
VSTATUS | Prints system status line (load, command, pid, etc). |
VDISCARD | Toggles the flushing of terminal output. |
IGNPAR | The ignore parity flag. The parameter SHOULD be 0 if this flag is FALSE, and 1 if it is TRUE. |
PARMRK | Mark parity and framing errors. |
INPCK | Enable checking of parity errors. |
ISTRIP | Strip 8th bit off characters. |
INLCR | Map NL into CR on input. |
IGNCR | Ignore CR on input. |
ICRNL | Map CR to NL on input. |
IUCLC | Translate uppercase characters to lowercase. |
IXON | Enable output flow control. |
IXANY | Any char will restart after stop. |
IXOFF | Enable input flow control. |
IMAXBEL | Ring bell on input queue full. |
ISIG | Enable signals INTR, QUIT, [D]SUSP. |
ICANON | Canonicalize input lines. |
XCASE | Enable input and output of uppercase characters by preceding their lowercase equivalents with "". |
ECHO | Enable echoing. |
ECHOE | Visually erase chars. |
ECHOK | Kill character discards current line. |
ECHONL | Echo NL even if ECHO is off. |
NOFLSH | Don't flush after interrupt. |
TOSTOP | Stop background jobs from output. |
IEXTEN | Enable extensions. |
ECHOCTL | Echo control characters as ^(Char). |
ECHOKE | Visual erase for line kill. |
PENDIN | Retype pending input. |
OPOST | Enable output processing. |
OLCUC | Convert lowercase to uppercase. |
ONLCR | Map NL to CR-NL. |
OCRNL | Translate carriage return to newline (output). |
ONOCR | Translate newline to carriage return-newline (output). |
ONLRET | Newline performs a carriage return (output). |
CS7 | 7 bit mode. |
CS8 | 8 bit mode. |
PARENB | Parity enable. |
PARODD | Odd parity, else even. |
TTY_OP_ISPEED | Specifies the input baud rate in bits per second. |
TTY_OP_OSPEED | Specifies the output baud rate in bits per second. |
HTTPAgent
HTTPAgent methods
- (constructor)(< object >sshConfig[, < object >agentConfig]) - Creates and returns a new
http.Agent
instance used to tunnel an HTTP connection over SSH. sshConfig
is what is passed to client.connect()
and agentOptions
is passed to the http.Agent
constructor.
HTTPSAgent
HTTPSAgent methods
- (constructor)(< object >sshConfig[, < object >agentConfig]) - Creates and returns a new
https.Agent
instance used to tunnel an HTTP connection over SSH. sshConfig
is what is passed to client.connect()
and agentOptions
is passed to the https.Agent
constructor.
Utilities
-
parseKey(< mixed >keyData[, < string >passphrase]) - mixed - Parses a private/public key in OpenSSH, RFC4716, or PPK format. For encrypted private keys, the key will be decrypted with the given passphrase
. keyData
can be a Buffer or string value containing the key contents. The returned value will be an array of objects (currently in the case of modern OpenSSH keys) or an object with these properties and methods:
-
type - string - The full key type (e.g. 'ssh-rsa'
)
-
comment - string - The comment for the key
-
getPrivatePEM() - string - This returns the PEM version of a private key
-
getPublicPEM() - string - This returns the PEM version of a public key (for either public key or derived from a private key)
-
getPublicSSH() - string - This returns the SSH version of a public key (for either public key or derived from a private key)
-
isPrivateKey() - boolean - This returns true
if the key is a private key or not
-
equals(< mixed >otherKey) - boolean - This returns true
if otherKey
(a parsed or parseable key) is the same as this key. This method does not compare the keys' comments
-
sign(< mixed >data) - mixed - This signs the given data
using this key and returns a Buffer containing the signature on success. On failure, an Error will be returned. data
can be anything accepted by node's sign.update()
.
-
verify(< mixed >data, < Buffer >signature) - mixed - This verifies a signature
of the given data
using this key and returns true
if the signature could be verified. On failure, either false
will be returned or an Error will be returned upon a more critical failure. data
can be anything accepted by node's verify.update()
.
-
sftp.OPEN_MODE - OPEN_MODE
-
sftp.STATUS_CODE - STATUS_CODE
-
sftp.flagsToString - flagsToString()
-
sftp.stringToFlags - stringToFlags()
AgentProtocol
AgentProtocol events
-
identities(< opaque >request) - (Server mode only) The client has requested a list of public keys stored in the agent. Use failureReply()
or getIdentitiesReply()
to reply appropriately.
-
sign(< opaque >request, < mixed >pubKey, < Buffer >data, < object >options) - (Server mode only) The client has requested data
to be signed using the key identified by pubKey
. Use failureReply()
or signReply()
to reply appropriately. options
may contain any of:
- hash - string - The explicitly desired hash to use when computing the signature. Currently if set, this may be either
'sha256'
or 'sha512'
for RSA keys.
AgentProtocol methods
-
(constructor)(< boolean >isClient) - Creates and returns a new AgentProtocol instance. isClient
determines whether the instance operates in client or server mode.
-
getIdentities(< function >callback) - (void) - (Client mode only) Requests a list of public keys from the agent. callback
is passed (err, keys)
where keys
is a possible array of public keys for authentication.
-
sign(< mixed >pubKey, < Buffer >data, < object >options, < function >callback) - (void) - (Client mode only) Requests that the agent sign data
using the key identified by pubKey
. pubKey
can be any parsed (using utils.parseKey()
) or parseable key value. callback
is passed (err, signature)
where signature
is a possible Buffer containing the signature for the data
. options
may contain any of:
- hash - string - The explicitly desired hash to use when computing the signature. Currently if set, this may be either
'sha256'
or 'sha512'
for RSA keys.
-
failureReply(< opaque >request) - (void) - (Server mode only) Replies to the given request
with a failure response.
-
getIdentitiesReply(< opaque >request, < array >keys) - (void) - (Server mode only) Responds to a identities list request
with the given array of keys in keys
.
-
signReply(< opaque >request, < Buffer >signature) - (void) - (Server mode only) Responds to a sign request
with the given signature in signature
.
BaseAgent
In order to create a custom agent, your class must:
-
Extend BaseAgent
-
Call super()
in its constructor
-
Implement at least the following methods:
-
getIdentities(< function >callback) - (void) - Passes (err, keys)
to callback
where keys
is a possible array of public keys for authentication.
-
sign(< mixed >pubKey, < Buffer >data, < object >options, < function >callback) - (void) - Signs data
using the key identified by pubKey
. pubKey
can be any parsed (using utils.parseKey()
) or parseable key value. callback
should be passed (err, signature)
where signature
is a possible Buffer containing the signature for the data
. options
may contain any of:
- hash - string - The explicitly desired hash to use when computing the signature. Currently if set, this may be either
'sha256'
or 'sha512'
for RSA keys.
Additionally your class may implement the following method in order to support agent forwarding on the client:
- getStream(< function >callback) - (void) - Passes
(err, stream)
to callback
where stream
is a possible Duplex stream to be used to communicate with your agent. You will probably want to utilize AgentProtocol
as agent forwarding is an OpenSSH feature, so the stream
needs to be able to transmit/receive OpenSSH agent protocol packets.
createAgent
- createAgent(< string >agentValue) - (Agent) - Creates and returns a new agent instance using the same logic as the
Client
's agent
configuration option: if the platform is Windows and it's the value "pageant", it creates a PageantAgent
, otherwise if it's not a path to a Windows pipe it creates a CygwinAgent
. In all other cases, it creates an OpenSSHAgent
.
CygwinAgent
CygwinAgent methods
- (constructor)(< string >socketPath) - Communicates with an agent listening at
socketPath
in a Cygwin environment.
OpenSSHAgent
OpenSSHAgent methods
- (constructor)(< string >socketPath) - Communicates with an OpenSSH agent listening on the UNIX socket at
socketPath
.
PageantAgent
PageantAgent methods
- (constructor)() - Creates a new agent instance for communicating with a running Pageant agent process.