From ac4107ceea994f028ae67b43dbe6676b9ccf2b3b Mon Sep 17 00:00:00 2001 From: tmanevik Date: Thu, 19 Mar 2015 14:00:43 +0100 Subject: Editorial updates SSH application --- lib/ssh/doc/src/ssh_connection.xml | 454 +++++++++++++++++++------------------ 1 file changed, 234 insertions(+), 220 deletions(-) (limited to 'lib/ssh/doc/src/ssh_connection.xml') diff --git a/lib/ssh/doc/src/ssh_connection.xml b/lib/ssh/doc/src/ssh_connection.xml index 5e2926dfa6..2ca1060e9e 100644 --- a/lib/ssh/doc/src/ssh_connection.xml +++ b/lib/ssh/doc/src/ssh_connection.xml @@ -24,156 +24,174 @@ ssh_connection + + + ssh_connection - This module provides API functions to send SSH Connection Protocol + This module provides API functions to send + SSH Connection Protocol events to the other side of an SSH channel. -

The SSH Connection Protocol is used by clients and servers - (i.e. SSH channels) to communicate over the SSH connection. The - API functions in this module sends SSH Connection Protocol events - that are received as messages by the remote channel. - In the case that the receiving channel is an Erlang process the - message will be on the following format - . If the ssh_channel behavior is used to - implement the channel process these will be handled by - handle_ssh_msg/2 .

+

The SSH Connection Protocol is used by clients and servers, + that is, SSH channels, to communicate over the SSH connection. The + API functions in this module send SSH Connection Protocol events, + which are received as messages by the remote channel. + If the receiving channel is an Erlang process, the + messages have the format + . + If the ssh_channel behavior is used to + implement the channel process, these messages are handled by + handle_ssh_msg/2.
- DATA TYPES - -

Type definitions that are used more than once in this module and/or - abstractions to indicate the intended use of the data type:

- -

boolean() = true | false

-

string() = list of ASCII characters

-

timeout() = infinity | integer() - in milliseconds.

-

ssh_connection_ref() - opaque to the user returned by - ssh:connect/3 or sent to an SSH channel processes

-

ssh_channel_id() = integer()

-

ssh_data_type_code() = 1 ("stderr") | 0 ("normal") are - currently valid values see RFC 4254 section 5.2.

-

ssh_request_status() = success | failure

-

event() = {ssh_cm, ssh_connection_ref(), ssh_event_msg()}

-

ssh_event_msg() = data_events() | status_events() | terminal_events()

-

reason() = timeout | closed

+ DATA TYPES + +

Type definitions that are used more than once in this module, + or abstractions to indicate the intended use of the data + type, or both:

+ + + boolean() +

= true | false

+ string() +

= list of ASCII characters

 + timeout() +

= infinity | integer() in milliseconds

 + ssh_connection_ref() +

Opaque to the user, returned by + ssh:connect/3 or sent to an SSH channel processes

 + ssh_channel_id() +

= integer()

 + ssh_data_type_code() +

= 1 ("stderr") | 0 ("normal") are + valid values, see + RFC 4254 Section 5.2.

 + ssh_request_status() ssh_request_status() +

= success | failure

 + event() +

= {ssh_cm, ssh_connection_ref(), ssh_event_msg()}

 + ssh_event_msg() +

= data_events() | status_events() | terminal_events()

 + reason() +

= timeout | closed

 + - data_events() + data_events() - Data has arrived on the channel. This event is sent as - result of calling ssh_connection:send/[3,4,5] +

Data has arrived on the channel. This event is sent as a + result of calling + ssh_connection:send/[3,4,5].

 - Indicates that the other side will not send any more - data. This event is sent as result of calling ssh_connection:send_eof/2 - +

Indicates that the other side sends no more data. + This event is sent as a result of calling ssh_connection:send_eof/2. +

- status_events() + status_events() - A signal can be delivered to the remote process/service - using the following message. Some systems will not support - signals, in which case they should ignore this message. There is - currently no funtion to generate this event as the signals - refered to are on OS-level and not something generated by an - Erlang program. +

A signal can be delivered to the remote process/service + using the following message. Some systems do not support + signals, in which case they are to ignore this message. There is + currently no function to generate this event as the signals + referred to are on OS-level and not something generated by an + Erlang program.

 - A remote execution may terminate violently due to a signal - then this message may be received. For details on valid string - values see RFC 4254 section 6.10. Special case of the signals - mentioned above. +

A remote execution can terminate violently because of a signal. + Then this message can be received. For details on valid string + values, see RFC 4254 + Section 6.10, which shows a special case of these signals.

 - When the command running at the other end terminates, the +

When the command running at the other end terminates, the following message can be sent to return the exit status of the - command. A zero 'exit_status' usually means that the command - terminated successfully. This event is sent as result of calling + command. A zero exit_status usually means that the command + terminated successfully. This event is sent as a result of calling - ssh_connection:exit_status/3 + ssh_connection:exit_status/3.

 - This event is sent as result of calling - ssh_connection:close/2 Both the handling of this - event and sending of it will be taken care of by the - ssh_channel behavior. +

This event is sent as a result of calling + ssh_connection:close/2. + Both the handling of this event and sending it are taken care of by the + ssh_channel behavior.

 - terminal_events() + terminal_events() -

Channels implementing a shell and command execution on the - server side should handle the following messages that may be sent by client channel processes.

+

Channels implementing a shell and command execution on the + server side are to handle the following messages that can be sent by client- + channel processes.

-

Events that includes a WantReply expects the event handling - process to call ssh_connection:reply_request/4 - with the boolean value of WantReply as the second - argument.

+

Events that include a WantReply expect the event handling + process to call + ssh_connection:reply_request/4 + with the boolean value of WantReply as the second argument.

- Environment variables may be passed to the shell/command - to be started later. This event is sent as result of calling ssh_connection:setenv/5 - +

Environment variables can be passed to the shell/command + to be started later. This event is sent as a result of calling ssh_connection:setenv/5. +

- A pseudo-terminal has been requested for the - session. Terminal is the value of the TERM environment - variable value (e.g., vt100). Zero dimension parameters must - be ignored. The character/row dimensions override the pixel - dimensions (when nonzero). Pixel dimensions refer to the - drawable area of the window. The Opcode in the +

A pseudo-terminal has been requested for the + session. Terminal is the value of the TERM environment + variable value, that is, vt100. Zero dimension parameters must + be ignored. The character/row dimensions override the pixel + dimensions (when non-zero). Pixel dimensions refer to the + drawable area of the window. Opcode in the TerminalModes list is the mnemonic name, represented - as an lowercase erlang atom, defined in - RFC 4254 section 8. - It may also be an opcode if the mnemonic name is not listed in the - RFC. Example OP code: 53, mnemonic name ECHO erlang atom: - echo.This event is sent as result of calling ssh_connection:ptty_alloc/4 + as a lowercase Erlang atom, defined in + RFC 4254, Section 8. + It can also be an Opcode if the mnemonic name is not listed in the + RFC. Example: OP code: 53, mnemonic name ECHO erlang atom: + echo. This event is sent as a result of calling ssh_connection:ptty_alloc/4.

 - This message will request that the user's default shell - be started at the other end. This event is sent as result of calling ssh_connection:shell/2 - +

This message requests that the user default shell + is started at the other end. This event is sent as a result of calling + ssh_connection:shell/2. +

- When the window (terminal) size changes on the client - side, it MAY send a message to the server side to inform it of - the new dimensions. There is currently no API function to generate this - event. +

When the window (terminal) size changes on the client + side, it can send a message to the server side to inform it of + the new dimensions. No API function generates this event.

 - This message will request that the server starts - execution of the given command. This event is sent as result of calling ssh_connection:exec/4 - +

This message requests that the server starts + execution of the given command. This event is sent as a result of calling ssh_connection:exec/4 . +

@@ -183,80 +201,83 @@ adjust_window(ConnectionRef, ChannelId, NumOfBytes) -> ok - Adjusts the SSH flowcontrol window. + Adjusts the SSH flow control window. - ConnectionRef = ssh_connection_ref() - ChannelId = ssh_channel_id() - NumOfBytes = integer() + ConnectionRef = ssh_connection_ref() + ChannelId = ssh_channel_id() + NumOfBytes = integer() -

Adjusts the SSH flowcontrol window. This shall be done by both client and server side channel processes.

+

Adjusts the SSH flow control window. This is to be done by both the + client- and server-side channel processes.

-

Channels implemented with the ssh_channel - behavior will normaly not need to call this function as flow control - will be handled by the behavior. The behavior will adjust the window every time +

Channels implemented with the ssh_channel + behavior do not normally need to call this function as flow control + is handled by the behavior. The behavior adjusts the window every time the callback - handle_ssh_msg/2 has returned after processing channel data

 + handle_ssh_msg/2 returns after processing channel data.

 close(ConnectionRef, ChannelId) -> ok - Sends a close message on the channel ChannelId. + Sends a close message on the channel ChannelId. - ConnectionRef = ssh_connection_ref() - ChannelId = ssh_channel_id() + ConnectionRef = ssh_connection_ref() + ChannelId = ssh_channel_id() -

A server or client channel process can choose to close their session by sending a close event. +

A server- or client-channel process can choose to close their session by + sending a close event.

-

This function will be called by the ssh_channel - behavior when the channel is terminated see ssh_channel(3) so channels implemented with the - behavior should not call this function explicitly.

 +

This function is called by the ssh_channel + behavior when the channel is terminated, see ssh_channel(3) . Thus, channels implemented + with the behavior are not to call this function explicitly.

 - exec(ConnectionRef, ChannelId, Command, TimeOut) -> ssh_request_status() | {error, reason()} - Request that the server start the execution of the given command. + exec(ConnectionRef, ChannelId, Command, TimeOut) -> ssh_request_status() | + {error, reason()} + Requests that the server starts the execution of the given command. - ConnectionRef = ssh_connection_ref() - ChannelId = ssh_channel_id() - Command = string() - Timeout = timeout() + ConnectionRef = ssh_connection_ref() + ChannelId = ssh_channel_id() + Command = string() + Timeout = timeout() -

Should be called by a client channel process to request that the server starts execution of the - given command, the result will be several messages according to the following pattern. Note - that the last message will be a channel close message, as the exec request is a one time - execution that closes the channel when it is done.

+

Is to be called by a client-channel process to request that the server starts + executing the given command. The result is several messages according to the + following pattern. The last message is a channel close message, as the exec + request is a one-time execution that closes the channel when it is done.

- N x {ssh_cm, ssh_connection_ref(), - {data, ssh_channel_id(), ssh_data_type_code(), binary() = Data}} - The result of executing the command may be only one line - or thousands of lines depending on the command. + N x {ssh_cm, ssh_connection_ref(), + {data, ssh_channel_id(), ssh_data_type_code(), binary() = Data}} +

The result of executing the command can be only one line + or thousands of lines depending on the command.

 0 or 1 x {ssh_cm, ssh_connection_ref(), {eof, ssh_channel_id()}} - Indicates that no more data will be sent. +

Indicates that no more data is to be sent.

 0 or 1 x {ssh_cm, ssh_connection_ref(), {exit_signal, ssh_channel_id(), string() = ExitSignal, string() = ErrorMsg, string() = LanguageString}} - Not all systems send signals. For details on valid string - values see RFC 4254 section 6.10 +

Not all systems send signals. For details on valid string + values, see RFC 4254, Section 6.10

 0 or 1 x {ssh_cm, ssh_connection_ref(), {exit_status, ssh_channel_id(), integer() = ExitStatus}} - It is recommended by the ssh connection protocol that this - message shall be sent, but that may not always be the case. +

It is recommended by the SSH Connection Protocol to send this + message, but that is not always the case.

 - 1 x {ssh_cm, ssh_connection_ref(), + 1 x {ssh_cm, ssh_connection_ref(), {closed, ssh_channel_id()}} - Indicates that the ssh channel started for the - execution of the command has now been shutdown. +

Indicates that the ssh_channel started for the + execution of the command has now been shut down.

 @@ -265,78 +286,72 @@ exit_status(ConnectionRef, ChannelId, Status) -> ok Sends the exit status of a command to the client. - ConnectionRef = ssh_connection_ref() - ChannelId = ssh_channel_id() - Status = integer() + ConnectionRef = ssh_connection_ref() + ChannelId = ssh_channel_id() + Status = integer() -

Should be called by a server channel process to sends the exit status of a command to the client.

+

Is to be called by a server-channel process to send the exit status of a command + to the client.

 - ptty_alloc(ConnectionRef, ChannelId, Options) -> - ptty_alloc(ConnectionRef, ChannelId, Options, Timeout) -> > ssh_request_status() | {error, reason()} - Send status replies to requests that want such replies. + ptty_alloc(ConnectionRef, ChannelId, Options) -> + ptty_alloc(ConnectionRef, ChannelId, Options, Timeout) -> > ssh_request_status() | + {error, reason()} + Sends an SSH Connection Protocol pty_req, + to allocate a pseudo-terminal. - ConnectionRef = ssh_connection_ref() - ChannelId = ssh_channel_id() - Options = proplists:proplist() + ConnectionRef = ssh_connection_ref() + ChannelId = ssh_channel_id() + Options = proplists:proplist() -

Sends a SSH Connection Protocol pty_req, to allocate a pseudo tty. - Should be called by a SSH client process. - Options are: -

+

Sends an SSH Connection Protocol pty_req, to allocate a pseudo-terminal. + Is to be called by an SSH client process.

+

Options:

{term, string()} - - Defaults to os:getenv("TERM") or "vt100" if it is undefined. - +

Defaults to os:getenv("TERM") or vt100 + if it is undefined.

 + {width, integer()} - - Defaults to 80 if pixel_width is not defined. - +

Defaults to 80 if pixel_width is not defined.

 + {height, integer()} - - Defaults to 24 if pixel_height is not defined. - +

Defaults to 24 if pixel_height is not defined.

 + {pixel_width, integer()} - - Is disregarded if width is defined. - +

Is disregarded if width is defined.

 + {pixel_height, integer()} - - Is disregarded if height is defined. - +

Is disregarded if height is defined.

 + {pty_opts, [{posix_atom(), integer()}]} - - Option may be an empty list, otherwise - see possible POSIX names in section 8 in RFC 4254. +

Option can be an empty list. Otherwise, see possible POSIX names + in Section 8 in RFC 4254.

 - - + reply_request(ConnectionRef, WantReply, Status, ChannelId) -> ok - Send status replies to requests that want such replies. + Sends status replies to requests that want such replies. - ConnectionRef = ssh_connection_ref() - WantReply = boolean() - Status = ssh_request_status() - ChannelId = ssh_channel_id() + ConnectionRef = ssh_connection_ref() + WantReply = boolean() + Status = ssh_request_status() + ChannelId = ssh_channel_id()

Sends status replies to requests where the requester has - stated that they want a status report e.i . WantReply = true, - if WantReply is false calling this function will be a - "noop". Should be called while handling an ssh connection - protocol message containing a WantReply boolean - value. -

+ stated that it wants a status report, that is, WantReply = true. + If WantReply is false, calling this function becomes a + "noop". Is to be called while handling an SSH Connection + Protocol message containing a WantReply boolean value.

 @@ -346,98 +361,97 @@ send(ConnectionRef, ChannelId, Type, Data) -> send(ConnectionRef, ChannelId, Type, Data, TimeOut) -> ok | {error, timeout} | {error, closed} - Sends channel data + Sends channel data. - ConnectionRef = ssh_connection_ref() - ChannelId = ssh_channel_id() - Data = binary() - Type = ssh_data_type_code() - Timeout = timeout() + ConnectionRef = ssh_connection_ref() + ChannelId = ssh_channel_id() + Data = binary() + Type = ssh_data_type_code() + Timeout = timeout() -

Should be called by client- and server channel processes to send data to each other. +

Is to be called by client- and server-channel processes to send data to each other.

send_eof(ConnectionRef, ChannelId) -> ok | {error, closed} - Sends eof on the channel ChannelId. + Sends EOF on channel ChannelId. - ConnectionRef = ssh_connection_ref() - ChannelId = ssh_channel_id() + ConnectionRef = ssh_connection_ref() + ChannelId = ssh_channel_id() -

Sends eof on the channel ChannelId. -

+

Sends EOF on channel ChannelId.

 - session_channel(ConnectionRef, Timeout) -> + session_channel(ConnectionRef, Timeout) -> session_channel(ConnectionRef, InitialWindowSize, MaxPacketSize, Timeout) -> {ok, ssh_channel_id()} | {error, reason()} - Opens a channel for a ssh session. + Opens a channel for an SSH session. - ConnectionRef = ssh_connection_ref() - InitialWindowSize = integer() - MaxPacketSize = integer() - Timeout = timeout() - Reason = term() + ConnectionRef = ssh_connection_ref() + InitialWindowSize = integer() + MaxPacketSize = integer() + Timeout = timeout() + Reason = term()

Opens a channel for an SSH session. The channel id returned from this function - is the id used as input to the other funtions in this module. -

+ is the id used as input to the other functions in this module.

 - setenv(ConnectionRef, ChannelId, Var, Value, TimeOut) -> ssh_request_status() | {error, reason()} - Environment variables may be passed to the + setenv(ConnectionRef, ChannelId, Var, Value, TimeOut) -> ssh_request_status() | + {error, reason()} + Environment variables can be passed to the shell/command to be started later. - ConnectionRef = ssh_connection_ref() - ChannelId = ssh_channel_id() - Var = string() - Value = string() - Timeout = timeout() + ConnectionRef = ssh_connection_ref() + ChannelId = ssh_channel_id() + Var = string() + Value = string() + Timeout = timeout() -

Environment variables may be passed before starting the - shell/command. Should be called by a client channel processes. -

+

Environment variables can be passed before starting the + shell/command. Is to be called by a client channel processes.

 shell(ConnectionRef, ChannelId) -> ssh_request_status() | {error, closed} - Requests that the user's default shell (typically - defined in /etc/passwd in UNIX systems) shall be executed at the server - end. + Requests that the user default shell (typically defined in + /etc/passwd in Unix systems) is to be executed at the server end. - ConnectionRef = ssh_connection_ref() - ChannelId = ssh_channel_id() + ConnectionRef = ssh_connection_ref() + ChannelId = ssh_channel_id() -

Should be called by a client channel process to request that the user's default shell (typically - defined in /etc/passwd in UNIX systems) shall be executed at the server end. -

+

Is to be called by a client channel process to request that the user default + shell (typically defined in /etc/passwd in Unix systems) is executed + at the server end.

 - subsystem(ConnectionRef, ChannelId, Subsystem, Timeout) -> ssh_request_status() | {error, reason()} - + subsystem(ConnectionRef, ChannelId, Subsystem, Timeout) -> ssh_request_status() | + {error, reason()} + Requests to execute a predefined subsystem on the server. - ConnectionRef = ssh_connection_ref() - ChannelId = ssh_channel_id() - Subsystem = string() - Timeout = timeout() + ConnectionRef = ssh_connection_ref() + ChannelId = ssh_channel_id() + Subsystem = string() + Timeout = timeout() -

Should be called by a client channel process for requesting to execute a predefined subsystem on the server. +

Is to be called by a client-channel process for requesting to execute a predefined + subsystem on the server.

-- cgit v1.2.3