1ssh_connection(3) Erlang Module Definition ssh_connection(3)
2
6 ssh_connection -
7 This module provides API functions to send SSH Connection Protocol
8 events to the other side of an SSH channel.
9
12 The SSH Connection Protocol is used by clients and servers, that is,
13 SSH channels, to communicate over the SSH connection. The API functions
14 in this module send SSH Connection Protocol events, which are received
15 as messages by the remote channel. If the receiving channel is an
16 Erlang process, the messages have the format {ssh_cm, connection_ref(),
17 ssh_event_msg()}. If the ssh_client_channel behavior is used to imple‐
18 ment the channel process, these messages are handled by han‐
19 dle_ssh_msg/2.
20
22 Type definitions that are used more than once in this module, or
23 abstractions to indicate the intended use of the data type, or both:
24 boolean() =:
26 true | false
27 string() =:
29 list of ASCII characters
30 timeout() =:
32 infinity | integer() in milliseconds
33 connection_ref() =:
35 opaque() -as returned by ssh:connect/3 or sent to an SSH channel
36 processes
37 channel_id() =:
39 integer()
40 ssh_data_type_code() =:
42 1 ("stderr") | 0 ("normal") are valid values, see RFC 4254 Section
43 5.2.
44 ssh_request_status() =:
46 success | failure
47 event() =:
49 {ssh_cm, connection_ref(), ssh_event_msg()}
50 ssh_event_msg() =:
52 data_events() | status_events() | terminal_events()
53 reason() =:
55 timeout | closed
56 data_events():
58 {data, channel_id(), ssh_data_type_code(), Data :: binary()}:
61 Data has arrived on the channel. This event is sent as a result
62 of calling ssh_connection:send/[3,4,5].
63 {eof, channel_id()}:
65 Indicates that the other side sends no more data. This event is
66 sent as a result of calling ssh_connection:send_eof/2.
67 status_events():
69 {signal, channel_id(), ssh_signal()}:
72 A signal can be delivered to the remote process/service using the
73 following message. Some systems do not support signals, in which
74 case they are to ignore this message. There is currently no func‐
75 tion to generate this event as the signals referred to are on OS-
76 level and not something generated by an Erlang program.
77 {exit_signal, channel_id(), ExitSignal :: string(), ErrorMsg
79 ::string(), LanguageString :: string()}:
80 A remote execution can terminate violently because of a signal.
81 Then this message can be received. For details on valid string
82 values, see RFC 4254 Section 6.10, which shows a special case of
83 these signals.
84 {exit_status, channel_id(), ExitStatus :: integer()}:
86 When the command running at the other end terminates, the follow‐
87 ing message can be sent to return the exit status of the command.
88 A zero exit_status usually means that the command terminated suc‐
89 cessfully. This event is sent as a result of calling ssh_connec‐
90 tion:exit_status/3.
91 {closed, channel_id()}:
93 This event is sent as a result of calling ssh_connection:close/2.
94 Both the handling of this event and sending it are taken care of
95 by the ssh_client_channel behavior.
96 terminal_events():
98 Channels implementing a shell and command execution on the server
99 side are to handle the following messages that can be sent by
100 client- channel processes.
101 Events that include a WantReply expect the event handling process
103 to call ssh_connection:reply_request/4 with the boolean value of
104 WantReply as the second argument.
105 {env, channel_id(), WantReply :: boolean(), Var ::string(), Value
107 :: string()}:
108 Environment variables can be passed to the shell/command to be
109 started later. This event is sent as a result of calling
110 ssh_connection:setenv/5.
111 {pty, channel_id(), WantReply :: boolean(), {Terminal :: string(),
113 CharWidth :: integer(), RowHeight :: integer(), PixelWidth :: inte‐
114 ger(), PixelHeight :: integer(), TerminalModes :: [{Opcode ::
115 atom() | integer(), Value :: integer()}]}}:
116 A pseudo-terminal has been requested for the session. Terminal is
117 the value of the TERM environment variable value, that is, vt100.
118 Zero dimension parameters must be ignored. The character/row
119 dimensions override the pixel dimensions (when non-zero). Pixel
120 dimensions refer to the drawable area of the window. Opcode in
121 the TerminalModes list is the mnemonic name, represented as a
122 lowercase Erlang atom, defined in RFC 4254, Section 8. It can
123 also be an Opcode if the mnemonic name is not listed in the RFC.
124 Example: OP code: 53, mnemonic name ECHO erlang atom: echo. This
125 event is sent as a result of calling ssh_connection:ptty_alloc/4.
126 {shell, WantReply :: boolean()}:
128 This message requests that the user default shell is started at
129 the other end. This event is sent as a result of calling
130 ssh_connection:shell/2.
131 {window_change, channel_id(), CharWidth() :: integer(), RowHeight
133 :: integer(), PixWidth :: integer(), PixHeight :: integer()}:
134 When the window (terminal) size changes on the client side, it
135 can send a message to the server side to inform it of the new
136 dimensions. No API function generates this event.
137 {exec, channel_id(), WantReply :: boolean(), Cmd :: string()}:
139 This message requests that the server starts execution of the
140 given command. This event is sent as a result of calling ssh_con‐
141 nection:exec/4 .
142
144 adjust_window(ConnectionRef, ChannelId, NumOfBytes) -> ok
145 Types:
147 ConnectionRef = connection_ref()
149 ChannelId = channel_id()
150 NumOfBytes = integer()
151 Adjusts the SSH flow control window. This is to be done by both
153 the client- and server-side channel processes.
154 Note:
156 Channels implemented with the ssh_client_channel behavior do
157 not normally need to call this function as flow control is han‐
158 dled by the behavior. The behavior adjusts the window every time
159 the callback handle_ssh_msg/2 returns after processing channel
160 data.
161 close(ConnectionRef, ChannelId) -> ok
164 Types:
166 ConnectionRef = connection_ref()
168 ChannelId = channel_id()
169 A server- or client-channel process can choose to close their
171 session by sending a close event.
172 Note:
174 This function is called by the ssh_client_channel behavior when
175 the channel is terminated, see ssh_client_channel(3). Thus,
176 channels implemented with the behavior are not to call this
177 function explicitly.
178 exec(ConnectionRef, ChannelId, Command, TimeOut) -> ssh_request_sta‐
181 tus() | {error, reason()}
182 Types:
184 ConnectionRef = connection_ref()
186 ChannelId = channel_id()
187 Command = string()
188 Timeout = timeout()
189 Is to be called by a client-channel process to request that the
191 server starts executing the given command. The result is several
192 messages according to the following pattern. The last message is
193 a channel close message, as the exec request is a one-time exe‐
194 cution that closes the channel when it is done.
195 N x {ssh_cm, connection_ref(), {data, channel_id(),
197 ssh_data_type_code(), Data :: binary()}}:
198 The result of executing the command can be only one line or
199 thousands of lines depending on the command.
200 0 or 1 x {ssh_cm, connection_ref(), {eof, channel_id()}}:
202 Indicates that no more data is to be sent.
203 0 or 1 x {ssh_cm, connection_ref(), {exit_signal, chan‐
205 nel_id(), ExitSignal :: string(), ErrorMsg :: string(), Lan‐
206 guageString :: string()}}:
207 Not all systems send signals. For details on valid string
208 values, see RFC 4254, Section 6.10
209 0 or 1 x {ssh_cm, connection_ref(), {exit_status, chan‐
211 nel_id(), ExitStatus :: integer()}}:
212 It is recommended by the SSH Connection Protocol to send
213 this message, but that is not always the case.
214 1 x {ssh_cm, connection_ref(), {closed, channel_id()}}:
216 Indicates that the ssh_client_channel started for the execu‐
217 tion of the command has now been shut down.
218 exit_status(ConnectionRef, ChannelId, Status) -> ok
220 Types:
222 ConnectionRef = connection_ref()
224 ChannelId = channel_id()
225 Status = integer()
226 Is to be called by a server-channel process to send the exit
228 status of a command to the client.
229 ptty_alloc(ConnectionRef, ChannelId, Options) ->
231 ptty_alloc(ConnectionRef, ChannelId, Options, Timeout) -> >
232 ssh_request_status() | {error, reason()}
233 Types:
235 ConnectionRef = connection_ref()
237 ChannelId = channel_id()
238 Options = proplists:proplist()
239 Sends an SSH Connection Protocol pty_req, to allocate a pseudo-
241 terminal. Is to be called by an SSH client process.
242 Options:
244 {term, string()}:
246 Defaults to os:getenv("TERM") or vt100 if it is undefined.
247 {width, integer()}:
249 Defaults to 80 if pixel_width is not defined.
250 {height, integer()}:
252 Defaults to 24 if pixel_height is not defined.
253 {pixel_width, integer()}:
255 Is disregarded if width is defined.
256 {pixel_height, integer()}:
258 Is disregarded if height is defined.
259 {pty_opts, [{posix_atom(), integer()}]}:
261 Option can be an empty list. Otherwise, see possible POSIX
262 names in Section 8 in RFC 4254.
263 reply_request(ConnectionRef, WantReply, Status, ChannelId) -> ok
265 Types:
267 ConnectionRef = connection_ref()
269 WantReply = boolean()
270 Status = ssh_request_status()
271 ChannelId = channel_id()
272 Sends status replies to requests where the requester has stated
274 that it wants a status report, that is, WantReply = true. If
275 WantReply is false, calling this function becomes a "noop". Is
276 to be called while handling an SSH Connection Protocol message
277 containing a WantReply boolean value.
278 send(ConnectionRef, ChannelId, Data) ->
280 send(ConnectionRef, ChannelId, Data, Timeout) ->
281 send(ConnectionRef, ChannelId, Type, Data) ->
282 send(ConnectionRef, ChannelId, Type, Data, TimeOut) -> ok | {error,
283 timeout} | {error, closed}
284 Types:
286 ConnectionRef = connection_ref()
288 ChannelId = channel_id()
289 Data = binary()
290 Type = ssh_data_type_code()
291 Timeout = timeout()
292 Is to be called by client- and server-channel processes to send
294 data to each other.
295 The function subsystem/4 and subsequent calls of send/3,4,5 must
297 be executed in the same process.
298 send_eof(ConnectionRef, ChannelId) -> ok | {error, closed}
300 Types:
302 ConnectionRef = connection_ref()
304 ChannelId = channel_id()
305 Sends EOF on channel ChannelId.
307 session_channel(ConnectionRef, Timeout) ->
309 session_channel(ConnectionRef, InitialWindowSize, MaxPacketSize, Time‐
310 out) -> {ok, channel_id()} | {error, reason()}
311 Types:
313 ConnectionRef = connection_ref()
315 InitialWindowSize = integer()
316 MaxPacketSize = integer()
317 Timeout = timeout()
318 Reason = term()
319 Opens a channel for an SSH session. The channel id returned from
321 this function is the id used as input to the other functions in
322 this module.
323 setenv(ConnectionRef, ChannelId, Var, Value, TimeOut) ->
325 ssh_request_status() | {error, reason()}
326 Types:
328 ConnectionRef = connection_ref()
330 ChannelId = channel_id()
331 Var = string()
332 Value = string()
333 Timeout = timeout()
334 Environment variables can be passed before starting the
336 shell/command. Is to be called by a client channel processes.
337 shell(ConnectionRef, ChannelId) -> ok | failure | {error, closed}
339 Types:
341 ConnectionRef = connection_ref()
343 ChannelId = channel_id()
344 Is to be called by a client channel process to request that the
346 user default shell (typically defined in /etc/passwd in Unix
347 systems) is executed at the server end.
348 Note: the return value is ok instead of success unlike in other
350 functions in this module. This is a fault that was introduced so
351 long ago that any change would break a large number of existing
352 software.
353 subsystem(ConnectionRef, ChannelId, Subsystem, Timeout) ->
355 ssh_request_status() | {error, reason()}
356 Types:
358 ConnectionRef = connection_ref()
360 ChannelId = channel_id()
361 Subsystem = string()
362 Timeout = timeout()
363 Is to be called by a client-channel process for requesting to
365 execute a predefined subsystem on the server.
366 The function subsystem/4 and subsequent calls of send/3,4,5 must
368 be executed in the same process.
369Ericsson AB ssh 4.7.6 ssh_connection(3)