1ssh_connection(3)          Erlang Module Definition          ssh_connection(3)
2
3
4

NAME

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
10

DESCRIPTION

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
18       {ssh_cm, ssh:connection_ref(), channel_msg()}
19
20       If  the  ssh_client_channel  behavior  is used to implement the channel
21       process, these messages are handled by handle_ssh_msg/2.
22

DATA TYPES

24       ssh_data_type_code() = integer() >= 0
25
26              The valid values are 0 ("normal")  and  1  ("stderr"),  see  RFC
27              4254, Section 5.2.
28
29       result() = req_status() | {error, reason()}
30
31       reason() = closed | timeout
32
33              The result of a call.
34
35              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
39              If not, the reason() indicates what went wrong:
40
41                closed:
42                  indicates  that  the  channel  or connection was closed when
43                  trying to send the request
44
45                timeout:
46                  indicates that the operation exceeded a time limit
47
48       req_status() = success | failure
49
50              The status of a request. Corresponds to the SSH_MSG_CHANNEL_SUC‐
51              CESS  and  SSH_MSG_CHANNEL_FAILURE  values  in RFC 4254, Section
52              5.4.
53
54   SSH Connection Protocol: General
55       event() = {ssh_cm, ssh:connection_ref(), channel_msg()}
56
57       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
70              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
75       want_reply() = boolean()
76
77              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
81   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
88              Data  has arrived on the channel. This event is sent as a result
89              of calling  ssh_connection:send/[3,4,5].
90
91   Closing a Channel (RFC 4254, section 5.3)
92       eof_ch_msg() = {eof, ssh:channel_id()}
93
94              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
97       closed_ch_msg() = {closed, ssh:channel_id()}
98
99              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
103   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
115       term_mode() =
116           {Opcode :: atom() | byte(), Value :: integer() >= 0}
117
118              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
130   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
138              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
142   Starting a Shell or Command (RFC 4254, section 6.5)
143       shell_ch_msg() = {shell, ssh:channel_id(), want_reply()}
144
145              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
149       exec_ch_msg() =
150           {exec, ssh:channel_id(), want_reply(), Command :: string()}
151
152              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
156   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
165              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
169   Signals (RFC 4254, section 6.9)
170       signal_ch_msg() =
171           {signal, ssh:channel_id(), SignalName :: string()}
172
173              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
180   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
186              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
192       exit_signal_ch_msg() =
193           {exit_signal,
194            ssh:channel_id(),
195            ExitSignal :: string(),
196            ErrorMsg :: string(),
197            LanguageString :: string()}
198
199              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

EXPORTS

205       adjust_window(ConnectionRef, ChannelId, NumOfBytes) -> ok
206
207              Types:
208
209                 ConnectionRef = ssh:connection_ref()
210                 ChannelId = ssh:channel_id()
211                 NumOfBytes = integer()
212
213              Adjusts  the SSH flow control window. This is to be done by both
214              the client- and server-side channel processes.
215
216          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
223
224       close(ConnectionRef, ChannelId) -> ok
225
226              Types:
227
228                 ConnectionRef = ssh:connection_ref()
229                 ChannelId = ssh:channel_id()
230
231              A server- or client-channel process can choose  to  close  their
232              session by sending a close event.
233
234          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
240
241       exec(ConnectionRef, ChannelId, Command, Timeout) -> result()
242
243              Types:
244
245                 ConnectionRef = ssh:connection_ref()
246                 ChannelId = ssh:channel_id()
247                 Command = string()
248                 Timeout = timeout()
249
250              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
256                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
260                0 or 1 x eof message:
261                  Indicates that no more data is to be sent.
262
263                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
267                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
271                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
275              See the User's Guide section on One-Time Execution for examples.
276
277       exit_status(ConnectionRef, ChannelId, Status) -> ok
278
279              Types:
280
281                 ConnectionRef = ssh:connection_ref()
282                 ChannelId = ssh:channel_id()
283                 Status = integer()
284
285              Is to be called by a server-channel process  to  send  the  exit
286              status of a command to the client.
287
288       ptty_alloc(ConnectionRef, ChannelId, Options) -> result()
289
290       ptty_alloc(ConnectionRef, ChannelId, Options, Timeout) -> result()
291
292              Types:
293
294                 ConnectionRef = ssh:connection_ref()
295                 ChannelId = ssh:channel_id()
296                 Options = proplists:proplist()
297                 Timeout = timeout()
298
299              Sends  an SSH Connection Protocol pty_req, to allocate a pseudo-
300              terminal. Is to be called by an SSH client process.
301
302              Options:
303
304                {term, string()}:
305                  Defaults to os:getenv("TERM") or vt100 if it is undefined.
306
307                {width, integer()}:
308                  Defaults to 80 if pixel_width is not defined.
309
310                {height, integer()}:
311                  Defaults to 24 if pixel_height is not defined.
312
313                {pixel_width, integer()}:
314                  Is disregarded if width is defined.
315
316                {pixel_height, integer()}:
317                  Is disregarded if height is defined.
318
319                {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
323       reply_request(ConnectionRef, WantReply, Status, ChannelId) -> ok
324
325              Types:
326
327                 ConnectionRef = ssh:connection_ref()
328                 WantReply = boolean()
329                 Status = req_status()
330                 ChannelId = ssh:channel_id()
331
332              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
338       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
343              Types:
344
345                 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
352              Is  to be called by client- and server-channel processes to send
353              data to each other.
354
355              The function subsystem/4 and subsequent calls of send/3,4,5 must
356              be executed in the same process.
357
358       send_eof(ConnectionRef, ChannelId) -> ok | {error, closed}
359
360              Types:
361
362                 ConnectionRef = ssh:connection_ref()
363                 ChannelId = ssh:channel_id()
364
365              Sends EOF on channel ChannelId.
366
367       session_channel(ConnectionRef, Timeout) -> Result
368
369       session_channel(ConnectionRef, InitialWindowSize, MaxPacketSize,
370                       Timeout) ->
371                          Result
372
373              Types:
374
375                 ConnectionRef = ssh:connection_ref()
376                 InitialWindowSize  =  MaxPacketSize  = integer() >= 1 | unde‐
377                 fined
378                 Timeout = timeout()
379                 Result = {ok, ssh:channel_id()} | {error, reason()}
380
381              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
385       setenv(ConnectionRef, ChannelId, Var, Value, Timeout) -> success
386
387              Types:
388
389                 ConnectionRef = ssh:connection_ref()
390                 ChannelId = ssh:channel_id()
391                 Var = Value = string()
392                 Timeout = timeout()
393
394              Environment  variables  can  be  passed  before   starting   the
395              shell/command. Is to be called by a client channel processes.
396
397       shell(ConnectionRef, ChannelId) -> Result
398
399              Types:
400
401                 ConnectionRef = ssh:connection_ref()
402                 ChannelId = ssh:channel_id()
403                 Result = ok | success | failure | {error, timeout}
404
405              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
409              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
414       subsystem(ConnectionRef, ChannelId, Subsystem, Timeout) ->
415                    result()
416
417              Types:
418
419                 ConnectionRef = ssh:connection_ref()
420                 ChannelId = ssh:channel_id()
421                 Subsystem = string()
422                 Timeout = timeout()
423
424              Is to be called by a client-channel process  for  requesting  to
425              execute a predefined subsystem on the server.
426
427              The function subsystem/4 and subsequent calls of send/3,4,5 must
428              be executed in the same process.
429
430
431
432Ericsson AB                       ssh 4.15.1                 ssh_connection(3)
Impressum