From 2084f7e079c951fdadebe23dcff5ec247c6e0158 Mon Sep 17 00:00:00 2001 From: Ingela Anderton Andin Date: Wed, 10 Oct 2012 15:27:10 +0200 Subject: ssh: Add Users Guide and enhance man pages --- lib/ssh/doc/src/ssh_connection.xml | 254 +++++++++++++++++++++++++------------ 1 file changed, 176 insertions(+), 78 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 a9ae13d556..4480f0a093 100644 --- a/lib/ssh/doc/src/ssh_connection.xml +++ b/lib/ssh/doc/src/ssh_connection.xml @@ -1,11 +1,11 @@ - +
2008 - 2011 + 2012 Ericsson AB, All Rights Reserved @@ -24,69 +24,178 @@ ssh_connection - Ingela Anderton Andin - - - - -
ssh_connection - This module provides an API to the ssh connection protocol. + This module provides API functions to send SSH Connection Protocol + events to the other side of an SSH channel. + -

This module provides an API to the ssh connection protocol. - Not all features of the connection protocol are officially supported yet. - Only the ones supported are documented here.

+

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 .

 -
- COMMON DATA TYPES +
+ 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 a ssh channel processes

+ 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.

+ 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()

+ + + data_events() + + + + Data has arrived on the channel. This event is sent as + 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 + + + + + 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 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. + + + 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 + + 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. + + + -
- MESSAGES SENT TO CHANNEL PROCESSES + 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.

+ +

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.

+ + + + 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 + + + + 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 + TerminalModes list is the mnemonic name, represented + as an lowercase erlang atom, defined in + RFC 4254 section 8, + or the opcode if the mnemonic name is not listed in the + RFC. Example OP code: 53, mnemonic name ECHO erlang atom: + echo. There is currently no API function to generate this + event. + + + 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 + + + + 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. -

As a result of the ssh connection protocol messages on the form - - will be sent to a channel process. The term will contain - information regarding the ssh connection protocol event, - for details see the ssh channel behavior callback handle_ssh_msg/2

-
- - + + 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 + + + + +
+ + adjust_window(ConnectionRef, ChannelId, NumOfBytes) -> ok - Adjusts the ssh flowcontrol window. + Adjusts the SSH flowcontrol window. ConnectionRef = ssh_connection_ref() ChannelId = ssh_channel_id() NumOfBytes = integer() -

Adjusts the ssh flowcontrol window.

+

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

-

This will be taken care of by the ssh_channel - behavior when the callback - handle_ssh_msg/2 has returned after processing a - {ssh_cm, ssh_connection_ref(), {data, ssh_channel_id(), - ssh_data_type_code(), binary()}} - message, and should normally not be called explicitly.

 +

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 + the callback + handle_ssh_msg/2 has returned after processing channel data

 @@ -98,20 +207,19 @@ ChannelId = ssh_channel_id() -

Sends a close message on the channel ChannelId +

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 +

This function will be called by the ssh_channel behavior when the channel is terminated see ssh_channel(3) and should - normally not be called explicitly.

 + marker="ssh_channel"> ssh_channel(3) so channels implemented with the + behavior should not call this function explicitly.

 exec(ConnectionRef, ChannelId, Command, TimeOut) -> ssh_request_status() - Will request that the server start the - execution of the given command. + Request that the server start the execution of the given command. ConnectionRef = ssh_connection_ref() ChannelId = ssh_channel_id() @@ -119,44 +227,39 @@ Timeout = timeout() -

Will request that the server start the execution of the - given command, the result will be received as:

+

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.

- N X {ssh_cm, - ssh_connection_ref(), {data, ssh_channel_id(), ssh_data_type_code(), - binary() = Data}} + 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. - 1 X {ssh_cm, ssh_connection_ref(), {eof, ssh_channel_id()}} + 0 or 1 x {ssh_cm, ssh_connection_ref(), {eof, ssh_channel_id()}} Indicates that no more data will be sent. - 0 or 1 X {ssh_cm, + 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 - 0 or 1 X {ssh_cm, ssh_connection_ref(), {exit_status, + 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. - 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. - -

These message should be handled by the - client. The ssh channel - behavior can be used when writing a client. -

- exit_status(ConnectionRef, ChannelId, Status) -> ok Sends the exit status of a command to the client. @@ -166,9 +269,9 @@ Status = integer() -

Sends the exit status of a command to the client.

+

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

 - + reply_request(ConnectionRef, WantReply, Status, CannelId) -> ok @@ -183,10 +286,9 @@

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 after handling an ssh connection + "noop". Should be called while handling an ssh connection protocol message containing a WantReply boolean - value. See the ssh_channel behavior callback handle_ssh_msg/2 + value.

@@ -206,7 +308,7 @@ Timeout = timeout() -

Sends channel data. +

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

@@ -228,9 +330,7 @@ session_channel(ConnectionRef, Timeout) -> session_channel(ConnectionRef, InitialWindowSize, MaxPacketSize, Timeout) -> {ok, ssh_channel_id()} | {error, Reason} - Opens a channel for a ssh session. A session is a - remote execution of a program. The program may be a shell, an - application, a system command, or some built-in subsystem. + Opens a channel for a ssh session. ConnectionRef = ssh_connection_ref() InitialWindowSize = integer() @@ -239,9 +339,8 @@ Reason = term() -

Opens a channel for a ssh session. A session is a - remote execution of a program. The program may be a shell, an - application, a system command, or some built-in subsystem. +

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.

@@ -258,8 +357,8 @@ Timeout = timeout() -

Environment variables may be passed to the shell/command to be - started later. +

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

@@ -267,17 +366,16 @@ shell(ConnectionRef, ChannelId) -> ssh_request_status() - Will request that the user's default shell (typically - defined in /etc/passwd in UNIX systems) be started at the other + Requests that the user's default shell (typically + defined in /etc/passwd in UNIX systems) shall be executed at the server end. ConnectionRef = ssh_connection_ref() ChannelId = ssh_channel_id() -

Will request that the user's default shell (typically - defined in /etc/passwd in UNIX systems) be started at the - other end. +

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.

@@ -292,7 +390,7 @@ Timeout = timeout() -

Sends a request to execute a predefined subsystem. +

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

-- cgit v1.2.3 From 671cf55d2388ef3c30f8e0e6b3e5ec824b02da09 Mon Sep 17 00:00:00 2001 From: Ingela Anderton Andin Date: Tue, 6 Nov 2012 10:55:39 +0100 Subject: ssh: Document and clean up SSH behaviours --- lib/ssh/doc/src/ssh_connection.xml | 4 ++-- 1 file changed, 2 insertions(+), 2 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 4480f0a093..c66622307f 100644 --- a/lib/ssh/doc/src/ssh_connection.xml +++ b/lib/ssh/doc/src/ssh_connection.xml @@ -91,7 +91,7 @@ refered to are on OS-level and not something generated by an Erlang program. - A remote execution may terminate violently due to a signal @@ -274,7 +274,7 @@ - reply_request(ConnectionRef, WantReply, Status, CannelId) -> ok + reply_request(ConnectionRef, WantReply, Status, ChannelId) -> ok Send status replies to requests that want such replies. ConnectionRef = ssh_connection_ref() -- cgit v1.2.3