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 handling the remote channel. The Er‐
16 lang format of thoose messages is (see also below):
17 {ssh_cm, ssh:connection_ref(), channel_msg()}
19 If the ssh_client_channel behavior is used to implement the channel
21 process, these messages are handled by handle_ssh_msg/2.
22
24 ssh_data_type_code() = integer() >= 0
25 The valid values are 0 ("normal") and 1 ("stderr"), see RFC
27 4254, Section 5.2.
28 result() = req_status() | {error, reason()}
30 reason() = closed | timeout
32 The result of a call.
34 If the request reached the peer, was handled and the response
36 reached the requesting node the req_status() is the status re‐
37 ported from the peer.
38 If not, the reason() indicates what went wrong:
40 closed:
42 indicates that the channel or connection was closed when
43 trying to send the request
44 timeout:
46 indicates that the operation exceeded a time limit
47 req_status() = success | failure
49 The status of a request. Coresponds to the SSH_MSG_CHANNEL_SUC‐
51 CESS and SSH_MSG_CHANNEL_FAILURE values in RFC 4254, Section
52 5.4.
53 SSH Connection Protocol: General
55 event() = {ssh_cm, ssh:connection_ref(), channel_msg()}
56 channel_msg() =
58 data_ch_msg() |
59 eof_ch_msg() |
60 closed_ch_msg() |
61 pty_ch_msg() |
62 env_ch_msg() |
63 shell_ch_msg() |
64 exec_ch_msg() |
65 signal_ch_msg() |
66 window_change_ch_msg() |
67 exit_status_ch_msg() |
68 exit_signal_ch_msg()
69 As mentioned in the introduction, the SSH Connection Protocol
71 events are handled as messages. When writing a channel handling
72 process without using the support by the ssh_client_channel be‐
73 havior the process must handle thoose messages.
74 want_reply() = boolean()
76 Messages that include a WantReply expect the channel handling
78 process to call ssh_connection:reply_request/4 with the boolean
79 value of WantReply as the second argument.
80 Data Transfer (RFC 4254, section 5.2)
82 data_ch_msg() =
83 {data,
84 ssh:channel_id(),
85 ssh_data_type_code(),
86 Data :: binary()}
87 Data has arrived on the channel. This event is sent as a result
89 of calling ssh_connection:send/[3,4,5].
90 Closing a Channel (RFC 4254, section 5.3)
92 eof_ch_msg() = {eof, ssh:channel_id()}
93 Indicates that the other side sends no more data. This event is
95 sent as a result of calling ssh_connection:send_eof/2.
96 closed_ch_msg() = {closed, ssh:channel_id()}
98 This event is sent as a result of calling ssh_connec‐
100 tion:close/2. Both the handling of this event and sending it are
101 taken care of by the ssh_client_channel behavior.
102 Requesting a Pseudo-Terminal (RFC 4254, section 6.2)
104 pty_ch_msg() =
105 {pty,
106 ssh:channel_id(),
107 want_reply(),
108 {Terminal :: string(),
109 CharWidth :: integer() >= 0,
110 RowHeight :: integer() >= 0,
111 PixelWidth :: integer() >= 0,
112 PixelHeight :: integer() >= 0,
113 TerminalModes :: [term_mode()]}}
114 term_mode() =
116 {Opcode :: atom() | byte(), Value :: integer() >= 0}
117 A pseudo-terminal has been requested for the session. Terminal
119 is the value of the TERM environment variable value, that is,
120 vt100. Zero dimension parameters must be ignored. The charac‐
121 ter/row dimensions override the pixel dimensions (when non-
122 zero). Pixel dimensions refer to the drawable area of the win‐
123 dow. Opcode in the TerminalModes list is the mnemonic name, rep‐
124 resented as a lowercase Erlang atom, defined in RFC 4254, Sec‐
125 tion 8. It can also be an Opcode if the mnemonic name is not
126 listed in the RFC. Example: OP code: 53, mnemonic name ECHO er‐
127 lang atom: echo. This event is sent as a result of calling
128 ssh_connection:ptty_alloc/4.
129 Environment Variable Passing (RFC 4254, section 6.4)
131 env_ch_msg() =
132 {env,
133 ssh:channel_id(),
134 want_reply(),
135 Var :: string(),
136 Value :: string()}
137 Environment variables can be passed to the shell/command to be
139 started later. This event is sent as a result of calling
140 ssh_connection:setenv/5.
141 Starting a Shell or Command (RFC 4254, section 6.5)
143 shell_ch_msg() = {shell, ssh:channel_id(), want_reply()}
144 This message requests that the user default shell is started at
146 the other end. This event is sent as a result of calling
147 ssh_connection:shell/2.
148 exec_ch_msg() =
150 {exec, ssh:channel_id(), want_reply(), Command :: string()}
151 This message requests that the server starts execution of the
153 given command. This event is sent as a result of calling
154 ssh_connection:exec/4 .
155 Window Dimension Change Message (RFC 4254, section 6.7)
157 window_change_ch_msg() =
158 {window_change,
159 ssh:channel_id(),
160 CharWidth :: integer() >= 0,
161 RowHeight :: integer() >= 0,
162 PixelWidth :: integer() >= 0,
163 PixelHeight :: integer() >= 0}
164 When the window (terminal) size changes on the client side, it
166 can send a message to the server side to inform it of the new
167 dimensions. No API function generates this event.
168 Signals (RFC 4254, section 6.9)
170 signal_ch_msg() =
171 {signal, ssh:channel_id(), SignalName :: string()}
172 A signal can be delivered to the remote process/service using
174 the following message. Some systems do not support signals, in
175 which case they are to ignore this message. There is currently
176 no function to generate this event as the signals referred to
177 are on OS-level and not something generated by an Erlang pro‐
178 gram.
179 Returning Exit Status (RFC 4254, section 6.10)
181 exit_status_ch_msg() =
182 {exit_status,
183 ssh:channel_id(),
184 ExitStatus :: integer() >= 0}
185 When the command running at the other end terminates, the fol‐
187 lowing message can be sent to return the exit status of the com‐
188 mand. A zero exit_status usually means that the command termi‐
189 nated successfully. This event is sent as a result of calling
190 ssh_connection:exit_status/3.
191 exit_signal_ch_msg() =
193 {exit_signal,
194 ssh:channel_id(),
195 ExitSignal :: string(),
196 ErrorMsg :: string(),
197 LanguageString :: string()}
198 A remote execution can terminate violently because of a signal.
200 Then this message can be received. For details on valid string
201 values, see RFC 4254 Section 6.10, which shows a special case of
202 these signals.
203
205 adjust_window(ConnectionRef, ChannelId, NumOfBytes) -> ok
206 Types:
208 ConnectionRef = ssh:connection_ref()
210 ChannelId = ssh:channel_id()
211 NumOfBytes = integer()
212 Adjusts the SSH flow control window. This is to be done by both
214 the client- and server-side channel processes.
215 Note:
217 Channels implemented with the ssh_client_channel behavior do
218 not normally need to call this function as flow control is han‐
219 dled by the behavior. The behavior adjusts the window every time
220 the callback handle_ssh_msg/2 returns after processing channel
221 data.
222 close(ConnectionRef, ChannelId) -> ok
225 Types:
227 ConnectionRef = ssh:connection_ref()
229 ChannelId = ssh:channel_id()
230 A server- or client-channel process can choose to close their
232 session by sending a close event.
233 Note:
235 This function is called by the ssh_client_channel behavior when
236 the channel is terminated, see ssh_client_channel(3). Thus,
237 channels implemented with the behavior are not to call this
238 function explicitly.
239 exec(ConnectionRef, ChannelId, Command, Timeout) -> result()
242 Types:
244 ConnectionRef = ssh:connection_ref()
246 ChannelId = ssh:channel_id()
247 Command = string()
248 Timeout = timeout()
249 Is to be called by a client-channel process to request that the
251 server starts executing the given command. The result is several
252 messages according to the following pattern. The last message is
253 a channel close message, as the exec request is a one-time exe‐
254 cution that closes the channel when it is done.
255 N x data message(s):
257 The result of executing the command can be only one line or
258 thousands of lines depending on the command.
259 0 or 1 x eof message:
261 Indicates that no more data is to be sent.
262 0 or 1 x exit signal message:
264 Not all systems send signals. For details on valid string
265 values, see RFC 4254, Section 6.10
266 0 or 1 x exit status message:
268 It is recommended by the SSH Connection Protocol to send
269 this message, but that is not always the case.
270 1 x closed status message:
272 Indicates that the ssh_client_channel started for the execu‐
273 tion of the command has now been shut down.
274 See the User's Guide section on One-Time Execution for examples.
276 exit_status(ConnectionRef, ChannelId, Status) -> ok
278 Types:
280 ConnectionRef = ssh:connection_ref()
282 ChannelId = ssh:channel_id()
283 Status = integer()
284 Is to be called by a server-channel process to send the exit
286 status of a command to the client.
287 ptty_alloc(ConnectionRef, ChannelId, Options) -> result()
289 ptty_alloc(ConnectionRef, ChannelId, Options, Timeout) -> result()
291 Types:
293 ConnectionRef = ssh:connection_ref()
295 ChannelId = ssh:channel_id()
296 Options = proplists:proplist()
297 Timeout = timeout()
298 Sends an SSH Connection Protocol pty_req, to allocate a pseudo-
300 terminal. Is to be called by an SSH client process.
301 Options:
303 {term, string()}:
305 Defaults to os:getenv("TERM") or vt100 if it is undefined.
306 {width, integer()}:
308 Defaults to 80 if pixel_width is not defined.
309 {height, integer()}:
311 Defaults to 24 if pixel_height is not defined.
312 {pixel_width, integer()}:
314 Is disregarded if width is defined.
315 {pixel_height, integer()}:
317 Is disregarded if height is defined.
318 {pty_opts, [{posix_atom(), integer()}]}:
320 Option can be an empty list. Otherwise, see possible POSIX
321 names in Section 8 in RFC 4254.
322 reply_request(ConnectionRef, WantReply, Status, ChannelId) -> ok
324 Types:
326 ConnectionRef = ssh:connection_ref()
328 WantReply = boolean()
329 Status = req_status()
330 ChannelId = ssh:channel_id()
331 Sends status replies to requests where the requester has stated
333 that it wants a status report, that is, WantReply = true. If
334 WantReply is false, calling this function becomes a "noop". Is
335 to be called while handling an SSH Connection Protocol message
336 containing a WantReply boolean value.
337 send(ConnectionRef, ChannelId, Data) ->
339 send(ConnectionRef, ChannelId, Data, Timeout) ->
340 send(ConnectionRef, ChannelId, Type, Data) ->
341 send(ConnectionRef, ChannelId, Type, Data, TimeOut) -> ok | Error
342 Types:
344 ConnectionRef = ssh:connection_ref()
346 ChannelId = ssh:channel_id()
347 Data = iodata()
348 Type = ssh_data_type_code()
349 Timeout = timeout()
350 Error = {error, reason()}
351 Is to be called by client- and server-channel processes to send
353 data to each other.
354 The function subsystem/4 and subsequent calls of send/3,4,5 must
356 be executed in the same process.
357 send_eof(ConnectionRef, ChannelId) -> ok | {error, closed}
359 Types:
361 ConnectionRef = ssh:connection_ref()
363 ChannelId = ssh:channel_id()
364 Sends EOF on channel ChannelId.
366 session_channel(ConnectionRef, Timeout) -> Result
368 session_channel(ConnectionRef, InitialWindowSize, MaxPacketSize,
370 Timeout) ->
371 Result
372 Types:
374 ConnectionRef = ssh:connection_ref()
376 InitialWindowSize = MaxPacketSize = integer() >= 1 | unde‐
377 fined
378 Timeout = timeout()
379 Result = {ok, ssh:channel_id()} | {error, reason()}
380 Opens a channel for an SSH session. The channel id returned from
382 this function is the id used as input to the other functions in
383 this module.
384 setenv(ConnectionRef, ChannelId, Var, Value, Timeout) -> success
386 Types:
388 ConnectionRef = ssh:connection_ref()
390 ChannelId = ssh:channel_id()
391 Var = Value = string()
392 Timeout = timeout()
393 Environment variables can be passed before starting the
395 shell/command. Is to be called by a client channel processes.
396 shell(ConnectionRef, ChannelId) -> Result
398 Types:
400 ConnectionRef = ssh:connection_ref()
402 ChannelId = ssh:channel_id()
403 Result = ok | success | failure | {error, timeout}
404 Is to be called by a client channel process to request that the
406 user default shell (typically defined in /etc/passwd in Unix
407 systems) is executed at the server end.
408 Note: the return value is ok instead of success unlike in other
410 functions in this module. This is a fault that was introduced so
411 long ago that any change would break a large number of existing
412 software.
413 subsystem(ConnectionRef, ChannelId, Subsystem, Timeout) ->
415 result()
416 Types:
418 ConnectionRef = ssh:connection_ref()
420 ChannelId = ssh:channel_id()
421 Subsystem = string()
422 Timeout = timeout()
423 Is to be called by a client-channel process for requesting to
425 execute a predefined subsystem on the server.
426 The function subsystem/4 and subsequent calls of send/3,4,5 must
428 be executed in the same process.
429Ericsson AB ssh 4.13.2.1 ssh_connection(3)