Description
SSH2 client and server modules written in pure JavaScript for node.js.
Development/testing is done against OpenSSH (7.1 currently).
Requirements
- node.js -- v0.10 or newer
Install
npm install ssh2
Client Examples
- Execute
uptime
on a server:
var Client = Client; var conn = ;conn; // example output:// Client :: 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// Stream :: close
- Start an interactive shell session:
var Client = Client; var conn = ;conn; // example output:// Client :: ready// STDOUT: Last login: Sun Jun 15 09:37:21 2014 from 192.168.100.100//// STDOUT: ls -l// exit//// STDOUT: frylock@athf:~$ ls -l//// STDOUT: total 8//// STDOUT: drwxr-xr-x 2 frylock frylock 4096 Nov 18 2012 mydir//// STDOUT: -rw-r--r-- 1 frylock frylock 25 Apr 11 2013 test.txt//// STDOUT: frylock@athf:~$ exit//// STDOUT: logout//// Stream :: close
- Send a raw HTTP request to port 80 on the server:
var Client = Client; var conn = ;conn; // example output:// Client :: 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 :: CLOSED
- Forward connections to 127.0.0.1:8000 on the server to us:
var Client = Client; var conn = ;conn; // example output:// Client :: 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
- Get a directory listing via SFTP:
var Client = Client; var conn = ;conn; // example output:// Client :: ready// [ { filename: 'test.txt',// longname: '-rw-r--r-- 1 frylock frylock 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 frylock frylock 4096 Nov 18 15:03 mydir',// attrs:// { size: 1048576,// uid: 1000,// gid: 1000,// mode: 16877,// atime: 1353269007,// mtime: 1353269007 } } ]
- Connection hopping:
var Client = Client; var conn1 = ;var conn2 = ; conn1; conn2;
- Forward X11 connections (xeyes in this case):
var net = ; var Client = Client; var conn = ; conn; conn;
- Dynamic (1:1) port forwarding using a SOCKSv5 proxy (using socksv5):
var socks = ;var Client = Client; var ssh_config = host: '192.168.100.1' port: 22 username: 'nodejs' password: 'rules'; socks; // test with cURL:// curl -i --socks5 localhost:1080 google.com
- Invoke an arbitrary subsystem (netconf in this case):
var Client = Client;var 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 = ; conn;
Server Examples
- Only allow password and public key authentication and non-interactive (exec) command execution:
var fs = ;var crypto = ;var inspect = inspect; var buffersEqual = ;var ssh2 = ;var utils = ssh2utils; var pubKey = utils; hostKeys: fs { console; client;};
- SFTP only server:
var fs = ; var ssh2 = ;var OPEN_MODE = ssh2SFTP_OPEN_MODE;var STATUS_CODE = ssh2SFTP_STATUS_CODE; hostKeys: fs { console; client;};
- You can find more examples in the
examples
directory of this repository.
API
require('ssh2').Client
returns a Client constructor.
require('ssh2').Server
returns a Server constructor.
require('ssh2').utils
returns the utility methods from ssh2-streams
.
require('ssh2').SFTP_STATUS_CODE
returns the SFTPStream.STATUS_CODE
from ssh2-streams
.
require('ssh2').SFTP_OPEN_MODE
returns the SFTPStream.OPEN_MODE
from ssh2-streams
.
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 aChannel
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.
-
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 aChannel
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.
-
-
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. -
continue() - Emitted when more requests/data can be sent to the server (after a
Client
method returnedfalse
). -
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(< boolean >hadError) - The socket was closed.
hadError
is set totrue
if this was due to error.
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
-
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 - 'md5' or 'sha1'. The host's key is hashed using this method and passed to the hostVerifier function. Default: (none)
-
hostVerifier - function - Function with parameters
(hashedKey[, callback])
wherehashedKey
is a string hex hash of the host's key for verification purposes. Returntrue
to continue with the handshake orfalse
to reject and disconnect, or callcallback()
withtrue
orfalse
if you need to perform asynchronous verification. Default: (auto-accept ifhostVerifier
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 thekeyboard-interactive
event. Default:false
-
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. 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-streams
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.
-
-
compress - mixed - Set to
true
to enable compression if server supports it,'force'
to force compression (disconnecting if server does not support it), orfalse
to explicitly opt out of compression all of the time. Note: this setting is overridden when explicitly setting a compression algorithm in thealgorithms
configuration option. Default: (only use compression if that is only what the server supports) -
debug - function - Set this to a function that receives a single string argument to get detailed (local) debug information. Default: (none)
-
Authentication method priorities: Password -> Private Key -> Agent (-> keyboard-interactive if tryKeyboard
is true
) -> Hostbased -> None
-
exec(< string >command[, < object >options], < function >callback) - boolean - Executes
command
on the server. Returnsfalse
if you should wait for thecontinue
event before sending any more traffic.callback
has 2 parameters: < Error >err, < Channel >stream. 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'). 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
-
-
-
shell([[< mixed >window,] < object >options]< function >callback) - boolean - Starts an interactive shell session on the server, with an optional
window
object containing pseudo-tty settings (see 'Pseudo-TTY settings'). Ifwindow === false
, then no pseudo-tty is allocated.options
supports thex11
option as described in exec().callback
has 2 parameters: < Error >err, < Channel >stream. Returnsfalse
if you should wait for thecontinue
event before sending any more traffic. -
forwardIn(< string >remoteAddr, < integer >remotePort, < function >callback) - boolean - Bind to
remoteAddr
onremotePort
on the server and forward incoming TCP connections.callback
has 2 parameters: < Error >err, < integer >port (port
is the assigned port number ifremotePort
was 0). Returnsfalse
if you should wait for thecontinue
event before sending any more traffic. 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) - boolean - Unbind from
remoteAddr
onremotePort
on the server and stop forwarding incoming TCP connections. Untilcallback
is called, more connections may still come in.callback
has 1 parameter: < Error >err. Returnsfalse
if you should wait for thecontinue
event before sending any more traffic. -
forwardOut(< string >srcIP, < integer >srcPort, < string >dstIP, < integer >dstPort, < function >callback) - boolean - 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, < Channel >stream. Returnsfalse
if you should wait for thecontinue
event before sending any more traffic. -
sftp(< function >callback) - boolean - Starts an SFTP session.
callback
has 2 parameters: < Error >err, < SFTPStream >sftp. For methods available onsftp
, see theSFTPStream
client documentation (exceptread()
andwrite()
are used instead ofreadData()
andwriteData()
respectively, for convenience). Returnsfalse
if you should wait for thecontinue
event before sending any more traffic. -
subsys(< string >subsystem, < function >callback) - boolean - Invokes
subsystem
on the server.callback
has 2 parameters: < Error >err, < Channel >stream. Returnsfalse
if you should wait for thecontinue
event before sending any more traffic. -
end() - (void) - Disconnects the socket.
-
openssh_noMoreSessions(< function >callback) - boolean - 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. Returnsfalse
if you should wait for thecontinue
event before sending any more traffic. -
openssh_forwardInStreamLocal(< string >socketPath, < function >callback) - boolean - OpenSSH extension that binds to a UNIX domain socket at
socketPath
on the server and forwards incoming connections.callback
has 1 parameter: < Error >err. Returnsfalse
if you should wait for thecontinue
event before sending any more traffic. -
openssh_unforwardInStreamLocal(< string >socketPath, < function >callback) - boolean - 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. Returnsfalse
if you should wait for thecontinue
event before sending any more traffic. -
openssh_forwardOutStreamLocal(< string >socketPath, < function >callback) - boolean - OpenSSH extension that opens a connection to a UNIX domain socket at
socketPath
on the server.callback
has 2 parameters: < Error >err, < Channel >stream. Returnsfalse
if you should wait for thecontinue
event before sending any more traffic.
Server events
-
connection(< Connection >client, < object >info) - A new client has connected.
info
contains the following properties:-
ip - string - The remoteAddress of the connection.
-
header - object - Information about the client's header:
-
identRaw - string - The raw client identification string.
-
versions - object - Various version information:
-
protocol - string - The SSH protocol version (always
1.99
or2.0
). -
software - string - The software name and version of the client.
-
-
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 aconnection
listener. Validconfig
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-streams
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.
-
-
banner - string - A message that is sent to clients immediately upon connection, before handshaking 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, andctx.accept()
andctx.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 onctx
depends on thectx.method
of authentication the client has requested:-
password
:- password - string - This is the password sent by the client.
-
publickey
:-
key - object - Contains information about the public key sent by the client:
-
algo - string - The name of the key algorithm (e.g.
ssh-rsa
). -
data - Buffer - The actual key data.
-
-
sigAlgo - mixed - If the value is
undefined
, the client is only checking the validity of thekey
. If the value is a string, then this contains the signature algorithm that is passed tocrypto.createVerify()
. -
blob - mixed - If the value is
undefined
, the client is only checking the validity of thekey
. If the value is a Buffer, then this contains the data that is passed toverifier.update()
. -
signature - mixed - If the value is
undefined
, the client is only checking the validity of thekey
. If the value is a Buffer, then this contains a signature that is passed toverifier.verify()
.
-
-
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) - boolean - Send prompts to the client.
prompts
is an array of{ prompt: 'Prompt text', echo: true }
objects (prompt
being the prompt text andecho
indicating whether the client's response to the prompt should be echoed to their display).callback
is called with(err, responses)
, whereresponses
is an array of string responses matching up to theprompts
.
-
-
-
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.reject()
Returnsfalse
if you should wait for thecontinue
event before sending any more traffic. -
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.reject()
Returnsfalse
if you should wait for thecontinue
event before sending any more traffic.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.reject()
Returnsfalse
if you should wait for thecontinue
event before sending any more traffic.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
orcancel-tcpip-forward
).accept
andreject
are functions if the client requested a response. IfbindPort === 0
, you should pass the chosen port toaccept()
so that the client will know what port was bound.info
contains additional details about the request:-
tcpip-forward
andcancel-tcpip-forward
:-
bindAddr - string - The IP address to start/stop binding to.
-
bindPort - integer - The port to start/stop binding to.
-
-
streamlocal-forward@openssh.com
andcancel-streamlocal-forward@openssh.com
:- socketPath - string - The socket path to start/stop binding to.
-
-
rekey() - Emitted when the client has finished rekeying (either client or server initiated).
-
continue() - Emitted when more requests/data can be sent to the client (after a
Connection
method returnedfalse
). -
error(< Error >err) - An error occurred.
-
end() - The client socket disconnected.
-
close(< boolean >hadError) - The client socket was closed.
hadError
is set totrue
if this was due to error.
Connection methods
-
end() - boolean - Closes the client connection. Returns
false
if you should wait for thecontinue
event before sending any more traffic. -
x11(< string >originAddr, < integer >originPort, < function >callback) - boolean - Alert the client of an incoming X11 client connection from
originAddr
on portoriginPort
.callback
has 2 parameters: < Error >err, < Channel >stream. Returnsfalse
if you should wait for thecontinue
event before sending any more traffic. -
forwardOut(< string >boundAddr, < integer >boundPort, < string >remoteAddr, < integer >remotePort, < function >callback) - boolean - Alert the client of an incoming TCP connection on
boundAddr
on portboundPort
fromremoteAddr
on portremotePort
.callback
has 2 parameters: < Error >err, < Channel >stream. Returnsfalse
if you should wait for thecontinue
event before sending any more traffic. -
openssh_forwardOutStreamLocal(< string >socketPath, < function >callback) - boolean - Alert the client of an incoming UNIX domain socket connection on
socketPath
.callback
has 2 parameters: < Error >err, < Channel >stream. Returnsfalse
if you should wait for thecontinue
event before sending any more traffic. -
rekey([< function >callback]) - boolean - Initiates a rekeying with the client. If
callback
is supplied, it is added as a one-time handler for therekey
event. Returnsfalse
if you should wait for thecontinue
event before sending any more traffic.
Session events
-
pty(< mixed >accept, < mixed >reject, < object >info) - The client requested allocation of a pseudo-TTY for this session.
accept
andreject
are functions if the client requested a response and returnfalse
if you should wait for thecontinue
event before sending any more traffic.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
andreject
are functions if the client requested a response and returnfalse
if you should wait for thecontinue
event before sending any more traffic.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
andreject
are functions if the client requested a response and returnfalse
if you should wait for thecontinue
event before sending any more traffic.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
andreject
are functions if the client requested a response and returnfalse
if you should wait for thecontinue
event before sending any more traffic.info
has these properties:-
key - string - The environment variable's name.
-
value - string - The environment variable's value.
-
-
signal(< mixed >accept, < mixed >reject, < object >info) - The client has sent a signal.
accept
andreject
are functions if the client requested a response and returnfalse
if you should wait for thecontinue
event before sending any more traffic.info
has these properties:- name - string - The signal name (e.g.
SIGUSR1
).
- name - string - The signal name (e.g.
-
auth-agent(< mixed >accept, < mixed >reject) - The client has requested incoming ssh-agent requests be forwarded to them.
accept
andreject
are functions if the client requested a response and returnfalse
if you should wait for thecontinue
event before sending any more traffic. -
shell(< mixed >accept, < mixed >reject) - The client has requested an interactive shell.
accept
andreject
are functions if the client requested a response.accept()
returns a Channel for the interactive shell.reject()
Returnsfalse
if you should wait for thecontinue
event before sending any more traffic. -
exec(< mixed >accept, < mixed >reject, < object >info) - The client has requested execution of a command string.
accept
andreject
are functions if the client requested a response.accept()
returns a Channel for the command execution.reject()
Returnsfalse
if you should wait for thecontinue
event before sending any more traffic.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
andreject
are functions if the client requested a response.accept()
returns an SFTPStream in server mode (see theSFTPStream
documentation for details).reject()
Returnsfalse
if you should wait for thecontinue
event before sending any more traffic.info
has these properties: -
subsystem(< mixed >accept, < mixed >reject, < object >info) - The client has requested an arbitrary subsystem.
accept
andreject
are functions if the client requested a response.accept()
returns a Channel for the subsystem.reject()
Returnsfalse
if you should wait for thecontinue
event before sending any more traffic.info
has these properties:- name - string - The name of the subsystem.
-
close() - The session was closed.
Channel
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 fornet.Socket
. When the stream's end() is called, ifallowHalfOpen
istrue
, only EOF will be sent (the server can still send data if they have not already sent EOF). The default value for this property istrue
. -
A
close
event is emitted once the channel is completely closed on both the client and server. -
Client-only:
-
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 theexit
callback. If the process was interrupted by a signal, the following are passed to theexit
callback: null, < string >signalName, < boolean >didCoreDump, < string >description. -
If there was an
exit
event, theclose
event will be passed the same arguments for convenience.
-
-
For shell() and exec():
-
The readable side represents stdout and the writable side represents stdin.
-
A
stderr
property contains a Readable stream that represents output from stderr. -
signal(< string >signalName) - boolean - 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. Returnsfalse
if you should wait for thecontinue
event before sending any more traffic. -
setWindow(< integer >rows, < integer >cols, < integer >height, < integer >width) - boolean - 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. Returns
false
if you should wait for thecontinue
event before sending any more traffic.
-
-
-
Server-only:
-
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) - boolean - Sends an exit status code to the client. Returns
false
if you should wait for thecontinue
event before sending any more traffic. -
exit(< string >signalName[, < boolean >coreDumped[, < string >errorMsg]]) - boolean - Sends an exit status code to the client. Returns
false
if you should wait for thecontinue
event before sending any more traffic.
-
-
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'
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.