.TH ssh_connection 3erl "ssh 2.1" "Ericsson AB" "Erlang Module Definition"
.SH NAME
ssh_connection \- This module provides an API to the ssh connection protocol.
  
.SH DESCRIPTION
.LP
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\&.
.SH "COMMON DATA TYPES "

.LP
Type definitions that are used more than once in this module and/or abstractions to indicate the intended use of the data type:
.LP
\fIboolean() = true | false \fR\&
.LP
\fIstring() = list of ASCII characters\fR\&
.LP
\fItimeout() = infinity | integer() - in milliseconds\&.\fR\&
.LP
\fIssh_connection_ref() - opaque to the user returned by ssh:connect/3 or sent to a ssh channel processes\fR\&
.LP
\fIssh_channel_id() = integer() \fR\&
.LP
\fIssh_data_type_code() = 1 ("stderr") | 0 ("normal") are currently valid values see RFC 4254 section 5\&.2\&.\fR\&
.LP
\fIssh_request_status() = success | failure\fR\&
.SH "MESSAGES SENT TO CHANNEL PROCESSES"

.LP
As a result of the ssh connection protocol messages on the form \fI{ssh_cm, ssh_connection_ref(), term()}\fR\& 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 \fBhandle_ssh_msg/2 \fR\& 
.SH EXPORTS
.LP
.B
adjust_window(ConnectionRef, ChannelId, NumOfBytes) -> ok
.br
.RS
.LP
Types:

.RS 3
 ConnectionRef = ssh_connection_ref() 
.br
 ChannelId = ssh_channel_id() 
.br
 NumOfBytes = integer()
.br
.RE
.RE
.RS
.LP
Adjusts the ssh flowcontrol window\&.
.LP

.RS -4
.B
Note:
.RE
This will be taken care of by the ssh_channel behavior when the callback \fB handle_ssh_msg/2 \fR\& 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\&.

.RE

.LP
.B
close(ConnectionRef, ChannelId) -> ok
.br
.RS
.LP
Types:

.RS 3
 ConnectionRef = ssh_connection_ref() 
.br
 ChannelId = ssh_channel_id()
.br
.RE
.RE
.RS
.LP
Sends a close message on the channel \fIChannelId\fR\& 
.LP

.RS -4
.B
Note:
.RE
This function will be called by the ssh channel behavior when the channel is terminated see \fB ssh_channel(3erl) \fR\& and should normally not be called explicitly\&.

.RE

.LP
.B
exec(ConnectionRef, ChannelId, Command, TimeOut) -> ssh_request_status() 
.br
.RS
.LP
Types:

.RS 3
 ConnectionRef = ssh_connection_ref() 
.br
 ChannelId = ssh_channel_id()
.br
 Command = string()
.br
Timeout = timeout() 
.br
.RE
.RE
.RS
.LP
Will request that the server start the execution of the given command, the result will be received as:
.RS 2
.TP 2
.B
\fI N X {ssh_cm, ssh_connection_ref(), {data, ssh_channel_id(), ssh_data_type_code(), binary() = Data}} \fR\&:
The result of executing the command may be only one line or thousands of lines depending on the command\&.
.TP 2
.B
\fI 1 X {ssh_cm, ssh_connection_ref(), {eof, ssh_channel_id()}}\fR\&:
Indicates that no more data will be sent\&.
.TP 2
.B
\fI0 or 1 X {ssh_cm, ssh_connection_ref(), {exit_signal, ssh_channel_id(), string() = ExitSignal, string() = ErrorMsg, string() = LanguageString}}\fR\&:
Not all systems send signals\&. For details on valid string values see RFC 4254 section 6\&.10 
.TP 2
.B
\fI0 or 1 X {ssh_cm, ssh_connection_ref(), {exit_status, ssh_channel_id(), integer() = ExitStatus}}\fR\&:
It is recommended by the \fIssh connection protocol\fR\& that this message shall be sent, but that may not always be the case\&.
.TP 2
.B
\fI 1 X {ssh_cm, ssh_connection_ref(), {closed, ssh_channel_id()}}\fR\&:
Indicates that the ssh channel started for the execution of the command has now been shutdown\&.
.RE
.LP
These message should be handled by the client\&. The \fBssh channel behavior\fR\& can be used when writing a client\&.
.RE

.LP
.B
exit_status(ConnectionRef, ChannelId, Status) -> ok
.br
.RS
.LP
Types:

.RS 3
 ConnectionRef = ssh_connection_ref() 
.br
 ChannelId = ssh_channel_id()
.br
 Status = integer()
.br
.RE
.RE
.RS
.LP
Sends the exit status of a command to the client\&.
.RE

.LP
.B
reply_request(ConnectionRef, WantReply, Status, CannelId) -> ok
.br
.RS
.LP
Types:

.RS 3
 ConnectionRef = ssh_connection_ref() 
.br
 WantReply = boolean()
.br
 Status = ssh_request_status() 
.br
 ChannelId = ssh_channel_id()
.br
.RE
.RE
.RS
.LP
Sends status replies to requests where the requester has stated that they want a status report e\&.i \&.\fI WantReply = true\fR\&, if \fI WantReply\fR\& is false calling this function will be a "noop"\&. Should be called after handling an ssh connection protocol message containing a \fIWantReply\fR\& boolean value\&. See the ssh_channel behavior callback \fB handle_ssh_msg/2 \fR\& 
.RE

.LP
.B
send(ConnectionRef, ChannelId, Data) ->
.br
.B
send(ConnectionRef, ChannelId, Data, Timeout) ->
.br
.B
send(ConnectionRef, ChannelId, Type, Data) ->
.br
.B
send(ConnectionRef, ChannelId, Type, Data, TimeOut) -> ok | {error, timeout}
.br
.RS
.LP
Types:

.RS 3
 ConnectionRef = ssh_connection_ref() 
.br
 ChannelId = ssh_channel_id()
.br
 Data = binary()
.br
 Type = ssh_data_type_code()
.br
 Timeout = timeout()
.br
.RE
.RE
.RS
.LP
Sends channel data\&.
.RE

.LP
.B
send_eof(ConnectionRef, ChannelId) -> ok 
.br
.RS
.LP
Types:

.RS 3
 ConnectionRef = ssh_connection_ref() 
.br
 ChannelId = ssh_channel_id()
.br
.RE
.RE
.RS
.LP
Sends eof on the channel \fIChannelId\fR\&\&.
.RE

.LP
.B
session_channel(ConnectionRef, Timeout) -> 
.br
.B
session_channel(ConnectionRef, InitialWindowSize, MaxPacketSize, Timeout) -> {ok, ssh_channel_id()} | {error, Reason}
.br
.RS
.LP
Types:

.RS 3
 ConnectionRef = ssh_connection_ref()
.br
 InitialWindowSize = integer() 
.br
 MaxPacketSize = integer() 
.br
 Timeout = timeout()
.br
 Reason = term() 
.br
.RE
.RE
.RS
.LP
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\&.
.RE

.LP
.B
setenv(ConnectionRef, ChannelId, Var, Value, TimeOut) -> ssh_request_status()
.br
.RS
.LP
Types:

.RS 3
 ConnectionRef = ssh_connection_ref() 
.br
 ChannelId = ssh_channel_id()
.br
 Var = string()
.br
 Value = string()
.br
 Timeout = timeout()
.br
.RE
.RE
.RS
.LP
Environment variables may be passed to the shell/command to be started later\&.
.RE

.LP
.B
shell(ConnectionRef, ChannelId) -> ssh_request_status() 
.br
.RS
.LP
Types:

.RS 3
 ConnectionRef = ssh_connection_ref() 
.br
 ChannelId = ssh_channel_id()
.br
.RE
.RE
.RS
.LP
Will request that the user\&'s default shell (typically defined in /etc/passwd in UNIX systems) be started at the other end\&.
.RE

.LP
.B
subsystem(ConnectionRef, ChannelId, Subsystem, Timeout) -> ssh_request_status()
.br
.RS
.LP
Types:

.RS 3
 ConnectionRef = ssh_connection_ref() 
.br
 ChannelId = ssh_channel_id()
.br
 Subsystem = string()
.br
 Timeout = timeout()
.br
.RE
.RE
.RS
.LP
Sends a request to execute a predefined subsystem\&.
.RE