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, ssh_connec‐
17 tion_ref(), ssh_event_msg()}. If the ssh_channel behavior is used to
18 implement 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 ssh_connection_ref() =:
35 opaque() -as returned by ssh:connect/3 or sent to an SSH channel
36 processes
37 ssh_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, ssh_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, ssh_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, ssh_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, ssh_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, ssh_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, ssh_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, ssh_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_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, ssh_channel_id(), WantReply :: boolean(), Var ::string(),
107 Value :: 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, ssh_channel_id(), WantReply :: boolean(), {Terminal ::
113 string(), CharWidth :: integer(), RowHeight :: integer(), Pixel‐
114 Width :: integer(), PixelHeight :: integer(), TerminalModes ::
115 [{Opcode :: 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, ssh_channel_id(), CharWidth() :: integer(),
133 RowHeight :: integer(), PixWidth :: integer(), PixHeight :: inte‐
134 ger()}:
135 When the window (terminal) size changes on the client side, it
136 can send a message to the server side to inform it of the new
137 dimensions. No API function generates this event.
138 {exec, ssh_channel_id(), WantReply :: boolean(), Cmd :: string()}:
140 This message requests that the server starts execution of the
141 given command. This event is sent as a result of calling ssh_con‐
142 nection:exec/4 .
143
145 adjust_window(ConnectionRef, ChannelId, NumOfBytes) -> ok
146 Types:
148 ConnectionRef = ssh_connection_ref()
150 ChannelId = ssh_channel_id()
151 NumOfBytes = integer()
152 Adjusts the SSH flow control window. This is to be done by both
154 the client- and server-side channel processes.
155 Note:
157 Channels implemented with the ssh_channel behavior do not nor‐
158 mally need to call this function as flow control is handled by
159 the behavior. The behavior adjusts the window every time the
160 callback handle_ssh_msg/2 returns after processing channel
161 data.
162 close(ConnectionRef, ChannelId) -> ok
165 Types:
167 ConnectionRef = ssh_connection_ref()
169 ChannelId = ssh_channel_id()
170 A server- or client-channel process can choose to close their
172 session by sending a close event.
173 Note:
175 This function is called by the ssh_channel behavior when the
176 channel is terminated, see ssh_channel(3). Thus, channels
177 implemented with the behavior are not to call this function
178 explicitly.
179 exec(ConnectionRef, ChannelId, Command, TimeOut) -> ssh_request_sta‐
182 tus() | {error, reason()}
183 Types:
185 ConnectionRef = ssh_connection_ref()
187 ChannelId = ssh_channel_id()
188 Command = string()
189 Timeout = timeout()
190 Is to be called by a client-channel process to request that the
192 server starts executing the given command. The result is several
193 messages according to the following pattern. The last message is
194 a channel close message, as the exec request is a one-time exe‐
195 cution that closes the channel when it is done.
196 N x {ssh_cm, ssh_connection_ref(), {data, ssh_channel_id(),
198 ssh_data_type_code(), Data :: binary()}}:
199 The result of executing the command can be only one line or
200 thousands of lines depending on the command.
201 0 or 1 x {ssh_cm, ssh_connection_ref(), {eof, ssh_chan‐
203 nel_id()}}:
204 Indicates that no more data is to be sent.
205 0 or 1 x {ssh_cm, ssh_connection_ref(), {exit_signal,
207 ssh_channel_id(), ExitSignal :: string(), ErrorMsg ::
208 string(), LanguageString :: string()}}:
209 Not all systems send signals. For details on valid string
210 values, see RFC 4254, Section 6.10
211 0 or 1 x {ssh_cm, ssh_connection_ref(), {exit_status,
213 ssh_channel_id(), ExitStatus :: integer()}}:
214 It is recommended by the SSH Connection Protocol to send
215 this message, but that is not always the case.
216 1 x {ssh_cm, ssh_connection_ref(), {closed, ssh_chan‐
218 nel_id()}}:
219 Indicates that the ssh_channel started for the execution of
220 the command has now been shut down.
221 exit_status(ConnectionRef, ChannelId, Status) -> ok
223 Types:
225 ConnectionRef = ssh_connection_ref()
227 ChannelId = ssh_channel_id()
228 Status = integer()
229 Is to be called by a server-channel process to send the exit
231 status of a command to the client.
232 ptty_alloc(ConnectionRef, ChannelId, Options) ->
234 ptty_alloc(ConnectionRef, ChannelId, Options, Timeout) -> >
235 ssh_request_status() | {error, reason()}
236 Types:
238 ConnectionRef = ssh_connection_ref()
240 ChannelId = ssh_channel_id()
241 Options = proplists:proplist()
242 Sends an SSH Connection Protocol pty_req, to allocate a pseudo-
244 terminal. Is to be called by an SSH client process.
245 Options:
247 {term, string()}:
249 Defaults to os:getenv("TERM") or vt100 if it is undefined.
250 {width, integer()}:
252 Defaults to 80 if pixel_width is not defined.
253 {height, integer()}:
255 Defaults to 24 if pixel_height is not defined.
256 {pixel_width, integer()}:
258 Is disregarded if width is defined.
259 {pixel_height, integer()}:
261 Is disregarded if height is defined.
262 {pty_opts, [{posix_atom(), integer()}]}:
264 Option can be an empty list. Otherwise, see possible POSIX
265 names in Section 8 in RFC 4254.
266 reply_request(ConnectionRef, WantReply, Status, ChannelId) -> ok
268 Types:
270 ConnectionRef = ssh_connection_ref()
272 WantReply = boolean()
273 Status = ssh_request_status()
274 ChannelId = ssh_channel_id()
275 Sends status replies to requests where the requester has stated
277 that it wants a status report, that is, WantReply = true. If
278 WantReply is false, calling this function becomes a "noop". Is
279 to be called while handling an SSH Connection Protocol message
280 containing a WantReply boolean value.
281 send(ConnectionRef, ChannelId, Data) ->
283 send(ConnectionRef, ChannelId, Data, Timeout) ->
284 send(ConnectionRef, ChannelId, Type, Data) ->
285 send(ConnectionRef, ChannelId, Type, Data, TimeOut) -> ok | {error,
286 timeout} | {error, closed}
287 Types:
289 ConnectionRef = ssh_connection_ref()
291 ChannelId = ssh_channel_id()
292 Data = binary()
293 Type = ssh_data_type_code()
294 Timeout = timeout()
295 Is to be called by client- and server-channel processes to send
297 data to each other.
298 The function subsystem/4 and subsequent calls of send/3,4,5 must
300 be executed in the same process.
301 send_eof(ConnectionRef, ChannelId) -> ok | {error, closed}
303 Types:
305 ConnectionRef = ssh_connection_ref()
307 ChannelId = ssh_channel_id()
308 Sends EOF on channel ChannelId.
310 session_channel(ConnectionRef, Timeout) ->
312 session_channel(ConnectionRef, InitialWindowSize, MaxPacketSize, Time‐
313 out) -> {ok, ssh_channel_id()} | {error, reason()}
314 Types:
316 ConnectionRef = ssh_connection_ref()
318 InitialWindowSize = integer()
319 MaxPacketSize = integer()
320 Timeout = timeout()
321 Reason = term()
322 Opens a channel for an SSH session. The channel id returned from
324 this function is the id used as input to the other functions in
325 this module.
326 setenv(ConnectionRef, ChannelId, Var, Value, TimeOut) ->
328 ssh_request_status() | {error, reason()}
329 Types:
331 ConnectionRef = ssh_connection_ref()
333 ChannelId = ssh_channel_id()
334 Var = string()
335 Value = string()
336 Timeout = timeout()
337 Environment variables can be passed before starting the
339 shell/command. Is to be called by a client channel processes.
340 shell(ConnectionRef, ChannelId) -> ssh_request_status() | {error,
342 closed}
343 Types:
345 ConnectionRef = ssh_connection_ref()
347 ChannelId = ssh_channel_id()
348 Is to be called by a client channel process to request that the
350 user default shell (typically defined in /etc/passwd in Unix
351 systems) is executed at the server end.
352 subsystem(ConnectionRef, ChannelId, Subsystem, Timeout) ->
354 ssh_request_status() | {error, reason()}
355 Types:
357 ConnectionRef = ssh_connection_ref()
359 ChannelId = ssh_channel_id()
360 Subsystem = string()
361 Timeout = timeout()
362 Is to be called by a client-channel process for requesting to
364 execute a predefined subsystem on the server.
365 The function subsystem/4 and subsequent calls of send/3,4,5 must
367 be executed in the same process.
368Ericsson AB ssh 4.6.9.4 ssh_connection(3)