1
<?xml version="1.0" encoding="latin1" ?>
2
<!DOCTYPE erlref SYSTEM "erlref.dtd">
9
<holder>Ericsson AB, All Rights Reserved</holder>
12
The contents of this file are subject to the Erlang Public License,
13
Version 1.1, (the "License"); you may not use this file except in
14
compliance with the License. You should have received a copy of the
15
Erlang Public License along with this software. If not, it can be
16
retrieved online at http://www.erlang.org/.
18
Software distributed under the License is distributed on an "AS IS"
19
basis, WITHOUT WARRANTY OF ANY KIND, either express or implied. See
20
the License for the specific language governing rights and limitations
23
The Initial Developer of the Original Code is Ericsson AB.
26
<title>ssh_connection</title>
27
<prepared>Ingela Anderton Andin</prepared>
28
<responsible></responsible>
35
<module>ssh_connection</module>
36
<modulesummary>This module provides an API to the ssh connection protocol.
39
<p>This module provides an API to the ssh connection protocol.
40
Not all features of the connection protocol are officially supported yet.
41
Only the ones supported are documented here.</p>
45
<title>COMMON DATA TYPES </title>
46
<p>Type definitions that are used more than once in this module and/or
47
abstractions to indicate the intended use of the data type:</p>
49
<p><c>boolean() = true | false </c></p>
50
<p><c>string() = list of ASCII characters</c></p>
51
<p><c>timeout() = infinity | integer() - in milliseconds.</c></p>
52
<p><c>ssh_connection_ref() - opaque to the user returned by
53
ssh:connect/[1,2,3] or sent to a ssh channel processes</c></p>
54
<p><c>ssh_channel_id() = integer() </c></p>
55
<p><c>ssh_data_type_code() = 1 ("stderr") | 0 ("normal") are
56
currently valid values see RFC 4254 section 5.2.</c></p>
57
<p><c>ssh_request_status() = success | failure</c></p>
61
<title>MESSAGES SENT TO CHANNEL PROCESSES</title>
63
<p>As a result of the ssh connection protocol messages on the form
64
<c><![CDATA[{ssh_cm, ssh_connection_ref(), term()}]]></c>
65
will be sent to a channel process. The term will contain
66
information regarding the ssh connection protocol event,
67
for details see the ssh channel behavior callback <seealso
68
marker="ssh_channel">handle_ssh_msg/2 </seealso> </p>
74
<name>adjust_window(ConnectionRef, ChannelId, NumOfBytes) -> ok</name>
75
<fsummary>Adjusts the ssh flowcontrol window. </fsummary>
77
<v> ConnectionRef = ssh_connection_ref() </v>
78
<v> ChannelId = ssh_channel_id() </v>
79
<v> NumOfBytes = integer()</v>
82
<p>Adjusts the ssh flowcontrol window. </p>
84
<note><p>This will be taken care of by the ssh_channel
85
behavior when the callback <seealso marker="ssh_channel">
86
handle_ssh_msg/2 </seealso> has returned after processing a
87
{ssh_cm, ssh_connection_ref(), {data, ssh_channel_id(),
88
ssh_data_type_code(), binary()}}
89
message, and should normally not be called explicitly.</p></note>
94
<name> close(ConnectionRef, ChannelId) -> ok</name>
95
<fsummary>Sends a close message on the channel <c>ChannelId</c>. </fsummary>
97
<v> ConnectionRef = ssh_connection_ref() </v>
98
<v> ChannelId = ssh_channel_id()</v>
101
<p>Sends a close message on the channel <c>ChannelId</c>
104
<note><p>This function will be called by the ssh channel
105
behavior when the channel is terminated see <seealso
106
marker="ssh_channel"> ssh_channel(3) </seealso> and should
107
normally not be called explicitly.</p></note>
112
<name>exec(ConnectionRef, ChannelId, Command, TimeOut) -> ssh_request_status() </name>
113
<fsummary>Will request that the server start the
114
execution of the given command. </fsummary>
116
<v> ConnectionRef = ssh_connection_ref() </v>
117
<v> ChannelId = ssh_channel_id()</v>
118
<v> Command = string()</v>
119
<v>Timeout = timeout() </v>
122
<p>Will request that the server start the execution of the
123
given command, the result will be received as:</p>
126
<tag><c> N X {ssh_cm,
127
ssh_connection_ref(), {data, ssh_channel_id(), ssh_data_type_code(),
128
binary() = Data}} </c></tag>
129
<item>The result of executing the command may be only one line
130
or thousands of lines depending on the command.</item>
132
<tag><c> 1 X {ssh_cm, ssh_connection_ref(), {eof, ssh_channel_id()}}</c></tag>
133
<item>Indicates that no more data will be sent.</item>
135
<tag><c>0 or 1 X {ssh_cm,
136
ssh_connection_ref(), {exit_signal,
137
ssh_channel_id(), string() = ExitSignal, string() = ErrorMsg, string() = LanguageString}}</c></tag>
138
<item>Not all systems send signals. For details on valid string
139
values see RFC 4254 section 6.10 </item>
141
<tag><c>0 or 1 X {ssh_cm, ssh_connection_ref(), {exit_status,
142
ssh_channel_id(), integer() = ExitStatus}}</c></tag>
143
<item>It is recommended by the <c>ssh connection protocol</c> that this
144
message shall be sent, but that may not always be the case.</item>
146
<tag><c> 1 X {ssh_cm, ssh_connection_ref(),
147
{closed, ssh_channel_id()}}</c></tag>
148
<item>Indicates that the ssh channel started for the
149
execution of the command has now been shutdown.</item>
152
<p> These message should be handled by the
153
client. The <seealso marker="ssh_channel">ssh channel
154
behavior</seealso> can be used when writing a client.
161
<name>exit_status(ConnectionRef, ChannelId, Status) -> ok</name>
162
<fsummary>Sends the exit status of a command to the client.</fsummary>
164
<v> ConnectionRef = ssh_connection_ref() </v>
165
<v> ChannelId = ssh_channel_id()</v>
166
<v> Status = integer()</v>
169
<p>Sends the exit status of a command to the client.</p>
174
<name>reply_request(ConnectionRef, WantReply, Status, CannelId) -> ok</name>
175
<fsummary>Send status replies to requests that want such replies. </fsummary>
177
<v> ConnectionRef = ssh_connection_ref() </v>
178
<v> WantReply = boolean()</v>
179
<v> Status = ssh_request_status() </v>
180
<v> ChannelId = ssh_channel_id()</v>
183
<p>Sends status replies to requests where the requester has
184
stated that they want a status report e.i .<c> WantReply = true</c>,
185
if <c> WantReply</c> is false calling this function will be a
186
"noop". Should be called after handling an ssh connection
187
protocol message containing a <c>WantReply</c> boolean
188
value. See the ssh_channel behavior callback <seealso
189
marker="ssh_channel"> handle_ssh_msg/2 </seealso>
195
<name>send(ConnectionRef, ChannelId, Data) -></name>
196
<name>send(ConnectionRef, ChannelId, Data, Timeout) -></name>
197
<name>send(ConnectionRef, ChannelId, Type, Data) -></name>
198
<name>send(ConnectionRef, ChannelId, Type, Data, TimeOut) ->
199
ok | {error, timeout}</name>
200
<fsummary>Sends channel data </fsummary>
202
<v> ConnectionRef = ssh_connection_ref() </v>
203
<v> ChannelId = ssh_channel_id()</v>
204
<v> Data = binary()</v>
205
<v> Type = ssh_data_type_code()</v>
206
<v> Timeout = timeout()</v>
209
<p>Sends channel data.
215
<name>send_eof(ConnectionRef, ChannelId) -> ok </name>
216
<fsummary>Sends eof on the channel <c>ChannelId</c>. </fsummary>
218
<v> ConnectionRef = ssh_connection_ref() </v>
219
<v> ChannelId = ssh_channel_id()</v>
222
<p>Sends eof on the channel <c>ChannelId</c>.
228
<name>session_channel(ConnectionRef, Timeout) -> </name>
229
<name>session_channel(ConnectionRef, InitialWindowSize,
230
MaxPacketSize, Timeout) -> {ok, ssh_channel_id()} | {error, Reason}</name>
231
<fsummary>Opens a channel for a ssh session. A session is a
232
remote execution of a program. The program may be a shell, an
233
application, a system command, or some built-in subsystem. </fsummary>
235
<v> ConnectionRef = ssh_connection_ref()</v>
236
<v> InitialWindowSize = integer() </v>
237
<v> MaxPacketSize = integer() </v>
238
<v> Timeout = timeout()</v>
239
<v> Reason = term() </v>
242
<p>Opens a channel for a ssh session. A session is a
243
remote execution of a program. The program may be a shell, an
244
application, a system command, or some built-in subsystem.
250
<name>setenv(ConnectionRef, ChannelId, Var, Value, TimeOut) -> ssh_request_status()</name>
251
<fsummary> Environment variables may be passed to the
252
shell/command to be started later.</fsummary>
254
<v> ConnectionRef = ssh_connection_ref() </v>
255
<v> ChannelId = ssh_channel_id()</v>
256
<v> Var = string()</v>
257
<v> Value = string()</v>
258
<v> Timeout = timeout()</v>
261
<p> Environment variables may be passed to the shell/command to be
268
<name>shell(ConnectionRef, ChannelId) -> ssh_request_status()
270
<fsummary> Will request that the user's default shell (typically
271
defined in /etc/passwd in UNIX systems) be started at the other
274
<v> ConnectionRef = ssh_connection_ref() </v>
275
<v> ChannelId = ssh_channel_id()</v>
278
<p> Will request that the user's default shell (typically
279
defined in /etc/passwd in UNIX systems) be started at the
286
<name>subsystem(ConnectionRef, ChannelId, Subsystem, Timeout) -> ssh_request_status()</name>
287
<fsummary> </fsummary>
289
<v> ConnectionRef = ssh_connection_ref() </v>
290
<v> ChannelId = ssh_channel_id()</v>
291
<v> Subsystem = string()</v>
292
<v> Timeout = timeout()</v>
295
<p> Sends a request to execute a predefined subsystem.
added
removed
lib/ssh/doc/src/ssh_connection.xml
