ssh_connection
MODULE
ssh_connection
MODULE SUMMARY
This module provides an API to the ssh connection protocol.
DESCRIPTION
This module provides an API to the ssh connection protocol.
Not all features of the connection protocol are officially supported yet.
Only the ones supported are documented here.
COMMON 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/[1,2,3] or sent to a 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
MESSAGES SENT TO CHANNEL PROCESSES
As a result of the ssh connection protocol messages on the form
{ssh_cm, ssh_connection_ref(), term()}
will be sent to a channel process. The term will contain
information regarding the ssh connection protocol event,
for details see the ssh channel behavior callback handle_ssh_msg/2
EXPORTS
adjust_window(ConnectionRef, ChannelId, NumOfBytes) -> ok
Types:
ConnectionRef = ssh_connection_ref()
ChannelId = ssh_channel_id()
NumOfBytes = integer()
Adjusts the ssh flowcontrol window.
Note
This will be taken care of by the ssh_channel
behavior when the callback
handle_ssh_msg/2 has returned after processing a
{ssh_cm, ssh_connection_ref(), {data, ssh_channel_id(),
ssh_data_type_code(), binary()}}
message, and should normally not be called explicitly.
close(ConnectionRef, ChannelId) -> ok
Types:
ConnectionRef = ssh_connection_ref()
ChannelId = ssh_channel_id()
Sends a close message on the channel ChannelId
Note
This function will be called by the ssh channel
behavior when the channel is terminated see ssh_channel(3) and should
normally not be called explicitly.
exec(ConnectionRef, ChannelId, Command, TimeOut) -> ssh_request_status()
Types:
ConnectionRef = ssh_connection_ref()
ChannelId = ssh_channel_id()
Command = string()
Timeout = timeout()
Will request that the server start the execution of the
given command, the result will be received as:
-
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.
-
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.
These message should be handled by the
client. The ssh channel
behavior can be used when writing a client.
exit_status(ConnectionRef, ChannelId, Status) -> ok
Types:
ConnectionRef = ssh_connection_ref()
ChannelId = ssh_channel_id()
Status = integer()
Sends the exit status of a command to the client.
reply_request(ConnectionRef, WantReply, Status, CannelId) -> ok
Types:
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 after handling an ssh connection
protocol message containing a WantReply boolean
value. See the ssh_channel behavior callback handle_ssh_msg/2
send(ConnectionRef, ChannelId, Data) ->
send(ConnectionRef, ChannelId, Data, Timeout) ->
send(ConnectionRef, ChannelId, Type, Data) ->
send(ConnectionRef, ChannelId, Type, Data, TimeOut) ->
ok | {error, timeout}
Types:
ConnectionRef = ssh_connection_ref()
ChannelId = ssh_channel_id()
Data = binary()
Type = ssh_data_type_code()
Timeout = timeout()
send_eof(ConnectionRef, ChannelId) -> ok
Types:
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}
Types:
ConnectionRef = ssh_connection_ref()
InitialWindowSize = integer()
MaxPacketSize = integer()
Timeout = timeout()
Reason = term()
Opens a channel for a ssh session. A session is a
remote execution of a program. The program may be a shell, an
application, a system command, or some built-in subsystem.
setenv(ConnectionRef, ChannelId, Var, Value, TimeOut) -> ssh_request_status()
Types:
ConnectionRef = ssh_connection_ref()
ChannelId = ssh_channel_id()
Var = string()
Value = string()
Timeout = timeout()
Environment variables may be passed to the shell/command to be
started later.
shell(ConnectionRef, ChannelId) -> ssh_request_status()
Types:
ConnectionRef = ssh_connection_ref()
ChannelId = ssh_channel_id()
Will request that the user's default shell (typically
defined in /etc/passwd in UNIX systems) be started at the
other end.
subsystem(ConnectionRef, ChannelId, Subsystem, Timeout) -> ssh_request_status()
Types:
ConnectionRef = ssh_connection_ref()
ChannelId = ssh_channel_id()
Subsystem = string()
Timeout = timeout()
Sends a request to execute a predefined subsystem.
ssh 1.1.2
Copyright © 1991-2009
Ericsson AB