ssh_connection

This module provides API functions to send SSH Connection Protocol events to the other side of an SSH channel.

The SSH Connection Protocol is used by clients and servers (i.e. SSH channels) to communicate over the SSH connection. The API functions in this module sends SSH Connection Protocol events that are received as messages by the remote channel. In the case that the receiving channel is an Erlang process the message will be on the following format {ssh_cm, ssh_connection_ref(), ssh_event_msg()}. If the ssh_channel behavior is used to implement the channel process these will be handled by handle_ssh_msg/2 .

DATA TYPES

Type definitions that are used more than once in this module and/or abstractions to indicate the intended use of the data type:

boolean() = true | false

string() = list of ASCII characters

timeout() = infinity | integer() - in milliseconds.

ssh_connection_ref() - opaque to the user returned by ssh:connect/3 or sent to an SSH channel processes

ssh_channel_id() = integer()

ssh_data_type_code() = 1 ("stderr") | 0 ("normal") are currently valid values see RFC 4254 section 5.2.

ssh_request_status() = success | failure

event() = {ssh_cm, ssh_connection_ref(), ssh_event_msg()}

ssh_event_msg() = data_events() | status_events() | terminal_events()

data_events()

{data, ssh_channel_id(), ssh_data_type_code(), binary() = Data}

Data has arrived on the channel. This event is sent as result of calling ssh_connection:send/[3,4,5]

{eof, ssh_channel_id()}

Indicates that the other side will not send any more data. This event is sent as result of calling ssh_connection:send_eof/2

status_events()

{signal, ssh_channel_id(), ssh_signal()}

A signal can be delivered to the remote process/service using the following message. Some systems will not support signals, in which case they should ignore this message. There is currently no funtion to generate this event as the signals refered to are on OS-level and not something generated by an Erlang program.

{exit_signal, ssh_channel_id(), string() = ExitSignal, string() = ErrorMsg,
	string() = LanguageString}

A remote execution may terminate violently due to a signal then this message may be received. For details on valid string values see RFC 4254 section 6.10. Special case of the signals mentioned above.

{exit_status, ssh_channel_id(), integer() = ExitStatus}

When the command running at the other end terminates, the following message can be sent to return the exit status of the command. A zero 'exit_status' usually means that the command terminated successfully. This event is sent as result of calling ssh_connection:exit_status/3

{closed, ssh_channel_id()}

This event is sent as result of calling ssh_connection:close/2 Both the handling of this event and sending of it will be taken care of by the ssh_channel behavior.

terminal_events()

Channels implementing a shell and command execution on the server side should handle the following messages that may be sent by client channel processes.

Note!

Events that includes a WantReply expects the event handling process to call ssh_connection:reply_request/4 with the boolean value of WantReply as the second argument.

{env, ssh_channel_id(), boolean() = WantReply,
	 string() = Var, string() = Value}

Environment variables may be passed to the shell/command to be started later. This event is sent as result of calling ssh_connection:setenv/5

{pty, ssh_channel_id(),
	 boolean() = WantReply, {string() = Terminal, integer() = CharWidth,
	 integer() = RowHeight, integer() = PixelWidth, integer() = PixelHeight,
	 [{atom() | integer() = Opcode,
	 integer() = Value}] = TerminalModes}}

A pseudo-terminal has been requested for the session. Terminal is the value of the TERM environment variable value (e.g., vt100). Zero dimension parameters must be ignored. The character/row dimensions override the pixel dimensions (when nonzero). Pixel dimensions refer to the drawable area of the window. The Opcode in the TerminalModes list is the mnemonic name, represented as an lowercase erlang atom, defined in RFC 4254 section 8. It may also be an opcode if the mnemonic name is not listed in the RFC. Example

OP code: 53, mnemonic name ECHO erlang atom:
	 echo

.This event is sent as result of calling ssh_connection:ptty_alloc/4

{shell, boolean() = WantReply}

This message will request that the user's default shell be started at the other end. This event is sent as result of calling ssh_connection:shell/2

{window_change, ssh_channel_id(), integer() = CharWidth,
	 integer() = RowHeight, integer() = PixWidth, integer() = PixHeight}

When the window (terminal) size changes on the client side, it MAY send a message to the server side to inform it of the new dimensions. There is currently no API function to generate this event.

{exec, ssh_channel_id(),
	 boolean() = WantReply, string() = Cmd}

This message will request that the server starts execution of the given command. This event is sent as result of calling ssh_connection:exec/4

Functions

adjust_window(ConnectionRef, ChannelId, NumOfBytes) -> ok

ConnectionRef = ssh_connection_ref()
ChannelId = ssh_channel_id()
NumOfBytes = integer()

Adjusts the SSH flowcontrol window. This shall be done by both client and server side channel processes.

Note!

Channels implemented with the ssh_channel behavior will normaly not need to call this function as flow control will be handled by the behavior. The behavior will adjust the window every time the callback handle_ssh_msg/2 has returned after processing channel data

close(ConnectionRef, ChannelId) -> ok

ConnectionRef = ssh_connection_ref()
ChannelId = ssh_channel_id()

A server or client channel process can choose to close their session by sending a close event.

Note!

This function will be called by the ssh_channel behavior when the channel is terminated see ssh_channel(3) so channels implemented with the behavior should not call this function explicitly.

exec(ConnectionRef, ChannelId, Command, TimeOut) -> ssh_request_status()

ConnectionRef = ssh_connection_ref()
ChannelId = ssh_channel_id()
Command = string()
Timeout = timeout()

Should be called by a client channel process to request that the server starts execution of the given command, the result will be several messages according to the following pattern. Note that the last message will be a channel close message, as the exec request is a one time execution that closes the channel when it is done.

 N x {ssh_cm, ssh_connection_ref(),
	 {data, ssh_channel_id(), ssh_data_type_code(), binary() = Data}}

The result of executing the command may be only one line or thousands of lines depending on the command.

0 or 1 x {ssh_cm, ssh_connection_ref(), {eof, ssh_channel_id()}}

Indicates that no more data will be sent.

0 or 1 x {ssh_cm,
	 ssh_connection_ref(), {exit_signal,
	 ssh_channel_id(), string() = ExitSignal, string() = ErrorMsg, string() = LanguageString}}

Not all systems send signals. For details on valid string values see RFC 4254 section 6.10

0 or 1 x {ssh_cm, ssh_connection_ref(), {exit_status,
	  ssh_channel_id(), integer() = ExitStatus}}

It is recommended by the ssh connection protocol that this message shall be sent, but that may not always be the case.

 1 x {ssh_cm, ssh_connection_ref(),
	  {closed, ssh_channel_id()}}

Indicates that the ssh channel started for the execution of the command has now been shutdown.

exit_status(ConnectionRef, ChannelId, Status) -> ok

ConnectionRef = ssh_connection_ref()
ChannelId = ssh_channel_id()
Status = integer()

Should be called by a server channel process to sends the exit status of a command to the client.

ptty_alloc(ConnectionRef, ChannelId, Options, Timeout) -> success | failure

ConnectionRef = ssh_connection_ref()
ChannelId = ssh_channel_id()
Options = proplists:proplist()

Sends a SSH Connection Protocol pty_req, to allocate a pseudo tty. Should be called by a SSH client process. Options are:

{term, string()}

Defaults to os:getenv("TERM") or "vt100" if it is undefined.

{width, integer()}

Defaults to 80 if pixel_width is not defined.

{height, integer()}

Defaults to 24 if pixel_height is not defined.

{pixel_width, integer()}

Is disregarded if width is defined.

{pixel_height, integer()}

Is disregarded if height is defined.

{pty_opts, [{posix_atom(), integer()}]}

Option may be an empty list, otherwise see possible POSIX names in section 8 in RFC 4254.

reply_request(ConnectionRef, WantReply, Status, ChannelId) -> ok

ConnectionRef = ssh_connection_ref()
WantReply = boolean()
Status = ssh_request_status()
ChannelId = ssh_channel_id()

Sends status replies to requests where the requester has stated that they want a status report e.i . WantReply = true, if WantReply is false calling this function will be a "noop". Should be called while handling an ssh connection protocol message containing a WantReply boolean value.

send(ConnectionRef, ChannelId, Data) ->

send(ConnectionRef, ChannelId, Data, Timeout) ->

send(ConnectionRef, ChannelId, Type, Data) ->

send(ConnectionRef, ChannelId, Type, Data, TimeOut) -> ok | {error, timeout} | {error, closed}

ConnectionRef = ssh_connection_ref()
ChannelId = ssh_channel_id()
Data = binary()
Type = ssh_data_type_code()
Timeout = timeout()

Should be called by client- and server channel processes to send data to each other.

send_eof(ConnectionRef, ChannelId) -> ok | {error, closed}

ConnectionRef = ssh_connection_ref()
ChannelId = ssh_channel_id()

Sends eof on the channel ChannelId.

session_channel(ConnectionRef, Timeout) ->

session_channel(ConnectionRef, InitialWindowSize, MaxPacketSize, Timeout) -> {ok, ssh_channel_id()} | {error, Reason}

ConnectionRef = ssh_connection_ref()
InitialWindowSize = integer()
MaxPacketSize = integer()
Timeout = timeout()
Reason = term()

Opens a channel for an SSH session. The channel id returned from this function is the id used as input to the other funtions in this module.

setenv(ConnectionRef, ChannelId, Var, Value, TimeOut) -> ssh_request_status()

ConnectionRef = ssh_connection_ref()
ChannelId = ssh_channel_id()
Var = string()
Value = string()
Timeout = timeout()

Environment variables may be passed before starting the shell/command. Should be called by a client channel processes.

shell(ConnectionRef, ChannelId) -> ssh_request_status()

ConnectionRef = ssh_connection_ref()
ChannelId = ssh_channel_id()

Should be called by a client channel process to request that the user's default shell (typically defined in /etc/passwd in UNIX systems) shall be executed at the server end.

subsystem(ConnectionRef, ChannelId, Subsystem, Timeout) -> ssh_request_status()

ConnectionRef = ssh_connection_ref()
ChannelId = ssh_channel_id()
Subsystem = string()
Timeout = timeout()

Should be called by a client channel process for requesting to execute a predefined subsystem on the server.