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_channel.xml | 300 +++++++++++++--------------------------- 1 file changed, 98 insertions(+), 202 deletions(-) (limited to 'lib/ssh/doc/src/ssh_channel.xml') diff --git a/lib/ssh/doc/src/ssh_channel.xml b/lib/ssh/doc/src/ssh_channel.xml index c2b7aa94a5..342de97a1b 100644 --- a/lib/ssh/doc/src/ssh_channel.xml +++ b/lib/ssh/doc/src/ssh_channel.xml @@ -1,11 +1,11 @@ - +
2009 - 2009 + 2012 Ericsson AB, All Rights Reserved @@ -22,31 +22,38 @@ The Initial Developer of the Original Code is Ericsson AB. - ssh_channel - Ingela Anderton Andin - - - - - -
ssh_channel Generic Ssh Channel Behavior -

Ssh services are implemented as channels that are multiplexed - over an ssh connection and communicates via the ssh connection - protocol. This module provides a callback API that takes care of - generic channel aspects such as flow control and close messages - and lets the callback functions take care of the service specific - parts. +

SSH services (clients and servers) are implemented as channels + that are multiplexed over an SSH connection and communicates via + the SSH + Connection Protocol . This module provides a callback API + that takes care of generic channel aspects such as flow control + and close messages and lets the callback functions take care of + the service (application) specific parts. This behavior also ensures + that the channel process honors the principal of an OTP-process so + that it can be part of a supervisor tree. This is a requirement of + channel processes implementing a subsystem that will be added to + the SSH applications supervisor tree.

+ +

The functions init/1, terminate/2, handle_ssh_msg/2 and + handle_msg/2 are the functions that are required + to provide the implementation for a server side channel, such as + an SSH subsystem channel that can be plugged into the Erlang ssh + daemon see ssh:daemon/[2, + 3]. + The handle_call/3, handle_cast/2, code_change/3 and enter_loop/1 + functions are only relevant when implementing a client side + channel.
- 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 @@ -56,31 +63,31 @@

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 process

+ ssh:connect/3 or sent to an SSH channel process

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.

call(ChannelRef, Msg) -> - call(ChannelRef, Msg, Timeout) -> Reply | {error, Reason} + call(ChannelRef, Msg, timeout()) -> Reply | {error, Reason} Makes a synchronous call to a channel. ChannelRef = pid() As returned by start_link/4 Msg = term() - Timeout = timeout() Reply = term() Reason = closed | timeout

Makes a synchronous call to the channel process by sending a message and waiting until a reply arrives or a timeout - occurs. The channel will call - CallbackModule:handle_call/3 to handle the message. - If the channel process does not exist {error, closed} is returned. + occurs. The channel will call CallbackModule:handle_call/3 + to handle the message. If the channel process does not exist + {error, closed} is returned.

@@ -98,32 +105,33 @@

Sends an asynchronous message to the channel process and returns ok immediately, ignoring if the destination node or channel process does not exist. The channel will call - CallbackModule:handle_cast/2 to handle the message. + CallbackModule:handle_cast/2 + to handle the message.

enter_loop(State) -> _ - Makes an existing process into a ssh_channel process. + Makes an existing process an ssh_channel process. - State = term() - as returned by ssh_channel:init/1 + State = term() - as returned by ssh_channel:init/1 -

Makes an existing process into a ssh_channel +

Makes an existing process an ssh_channel process. Does not return, instead the calling process will - enter the ssh_channel process receive loop and become a + enter the ssh_channel process receive loop and become an ssh_channel process. The process must have been started using one of the start functions in proc_lib, see proc_lib(3). The user is responsible for any initialization of the process - and needs to call ssh_channel:init/1. + and needs to call ssh_channel:init/1

- init(Options) -> {ok, State} | {ok, State, Timeout} | {stop, Reason} + init(Options) -> {ok, State} | {ok, State, timeout()} | {stop, Reason} Initiates a ssh_channel process. Options = [{Option, Value}] @@ -134,24 +142,27 @@

- The module that implements the channel behavior. + The module that implements the channel behaviour. - The list of arguments to the callback modules + The list of arguments to the callback module's init function. - Reference to the ssh connection. + Reference to the ssh connection as returned by ssh:connect/3 Id of the ssh channel. -

This function is normally not called by the user, it is - only needed if for some reason the channel process needs - to be started with help of proc_lib instead calling - ssh_channel:start/4 or ssh_channel:start_link/4

+

This function is normally not called by the + user. The user only needs to call if for some reason the + channel process needs to be started with help of + proc_lib instead of calling + ssh_channel:start/4 or + ssh_channel:start_link/4

@@ -167,12 +178,12 @@

This function can be used by a channel to explicitly send a reply to a client that called call/[2,3] when the reply cannot be defined in the return value of - CallbackModule:handle_call/3.

+ CallbackModule:handle_call/3.

Client must be the From argument provided to the callback function handle_call/3. Reply is an arbitrary term, - which will be given back to the client as the return value of - ssh_channel:call/[2,3].

+ which will be given back to the client as the return value of + ssh_channel:call/[2,3].>

@@ -180,11 +191,12 @@ start(SshConnection, ChannelId, ChannelCb, CbInitArgs) -> start_link(SshConnection, ChannelId, ChannelCb, CbInitArgs) -> {ok, ChannelRef} | {error, Reason} - Starts a processes that handles a ssh channel. + Starts a processes that handles a SSH channel. SshConnection = ssh_connection_ref() ChannelId = ssh_channel_id() - As returned by ssh_connection:session_channel/[2,4] + As returned by cannot be defined in the return value of + ssh_connection:session_channel/[2,4] ChannelCb = atom() The name of the module implementing the service specific parts of the channel. @@ -193,39 +205,24 @@ ChannelRef = pid() -

Starts a processes that handles a ssh channel. Will be - called internally by the ssh daemon or explicitly by the ssh - client implementations. A channel process traps exit signals - by default. +

Starts a processes that handles an SSH channel. It will be + called internally by the SSH daemon or explicitly by the SSH + client implementations. The behavior will set the + trap_exit flag to true.

-
- CALLBACK FUNCTIONS - -

The functions init/1, terminate/2, handle_ssh_msg/2 and - handle_msg/2 are the functions that are required to provide the - implementation for a server side channel, such as a ssh subsystem - channel that can be plugged into the erlang ssh daemon see - ssh:daemon/[2, 3]. The - handle_call/3, handle_cast/2 code_change/3 and enter_loop/1 - functions are only relevant when implementing a client side - channel.

-
-
CALLBACK TIMEOUTS -

If an integer timeout value is provided in a return value of - one of the callback functions, a timeout will occur unless a - message is received within Timeout milliseconds. A timeout - is represented by the atom timeout which should be handled - by the handle_msg/2 - callback function. The atom infinity can be used to wait - indefinitely, this is the default value.

+ +

The timeout values that may be returned by the callback functions + has the same semantics as in a gen_server + If the timout occurs handle_msg/2 + will be called as handle_msg(timeout, State).

@@ -242,18 +239,19 @@ upgrade/downgrade, i.e. when the instruction {update,Module,Change,...} where Change={advanced,Extra} is given in the appup - file. See OTP - Design Principles for more information. Any new - connection will benefit from a server side upgrade but - already started connections on the server side will not be - affected. + file. See OTP + Design Principles for more information.

-

If there are long lived ssh connections and more - than one upgrade in a short time this may cause the old - connections to fail as only two versions of the code may - be loaded simultaneously.

 +

Soft upgrade according to the OTP release concept + is not straight forward for the server side, as subsystem + channel processes are spawned by the SSH application and + hence added to its supervisor tree. It could be possible to + upgrade the subsystem channels, when upgrading the user + application, if the callback functions can handle two + versions of the state, but this function can not be used in + the normal way.

+

In the case of an upgrade, OldVsn is Vsn, and in the case of a downgrade, OldVsn is @@ -269,7 +267,7 @@ - CallbackModule:init(Args) -> {ok, State} | {ok, State, Timeout} | + CallbackModule:init(Args) -> {ok, State} | {ok, State, timeout()} | {stop, Reason} Makes necessary initializations and returns the initial channel state if the initializations succeed. @@ -277,7 +275,6 @@ Args = term() Last argument to ssh_channel:start_link/4. State = term() - Timeout = timeout() Reason = term() @@ -298,17 +295,16 @@ From = opaque to the user should be used as argument to ssh_channel:reply/2 State = term() - Result = {reply, Reply, NewState} | {reply, Reply, NewState, Timeout} - | {noreply, NewState} | {noreply , NewState, Timeout} + Result = {reply, Reply, NewState} | {reply, Reply, NewState, timeout()} + | {noreply, NewState} | {noreply , NewState, timeout()} | {stop, Reason, Reply, NewState} | {stop, Reason, NewState} Reply = term() - will be the return value of ssh_channel:call/[2,3] - Timeout = timeout() - NewState = term() - a possible updated version of State + NewState = term() Reason = term()

Handles messages sent by calling - ssh_channel:call/[2,3] + ssh_channel:call/[2,3]

For more detailed information on timeouts see the section CALLBACK TIMEOUTS.

@@ -322,10 +318,9 @@ Msg = term() State = term() - Result = {noreply, NewState} | {noreply, NewState, Timeout} + Result = {noreply, NewState} | {noreply, NewState, timeout()} | {stop, Reason, NewState} - NewState = term() - a possible updated version of State - Timeout = timeout() + NewState = term() Reason = term() @@ -359,14 +354,14 @@ - This is the first messages that will be received - by the channel, it is sent just before - the ssh_channel:init/1 function returns successfully. - This is especially useful if the server wants - to send a message to the client without first receiving - a message from the client. If the message is not useful - for your particular problem just ignore it by immediately - returning {ok, State}. + This is the first messages that will be received by + the channel, it is sent just before the ssh_channel:init/1 function + returns successfully. This is especially useful if the + server wants to send a message to the client without first + receiving a message from it. If the message is not + useful for your particular scenario just ignore it by + immediately returning {ok, State}. @@ -377,118 +372,19 @@ ssh_channel_id(), State} Handles ssh connection protocol messages. - Msg = {ssh_cm, ssh_connection_ref(), SshMsg} - SshMsg = tuple() - see message list below + Msg = ssh_connection:event() State = term()

Handles ssh connection protocol messages that may need service specific attention.

- -

All channels should handle the following messages. For - channels implementing subsystems the handle_ssh_msg-callback - will not be called for any other messages.

- - - - Data has arrived on the channel. When the callback - for this message returns the channel behavior will adjust - the ssh flow control window. - - - Indicteas that the other side will not send any more - data. - - - A signal can be delivered to the remote - process/service using the following message. Some systems - may not implement signals, in which case they should ignore - this message. - - - 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 - - - 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. - - -

Channels implementing a shell and command execution on the server side - should also handle the following messages.

- - - - Environment variables may be passed to the - shell/command to be started later. Note that before the - callback returns it should call the function - ssh_connection:reply_request/4 with the boolean value of - WantReply as the second argument. - - - - This message will request that the server start the - execution of the given command. Note that before the - callback returns it should call the function - ssh_connection:reply_request/4 with the boolean value of - WantReply as the second argument. - - - 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. Note that before the callback returns it should - call the function ssh_connection:reply_request/4 with the - boolean value of WantReply as the second - argument. - - - This message will request that the user's default - shell be started at the other end. Note that before the - callback returns it should call the function - ssh_connection:reply_request/4 with the value of - WantReply as the second argument. - - - - When the window (terminal) size changes on the client - side, it MAY send a message to the other side to inform it - of the new dimensions. -

The following message is completely taken care of by the ssh channel behavior

- + The channel behavior will send a close message to the other side if such a message has not already been sent and then terminate the channel with reason normal. @@ -505,12 +401,12 @@

This function is called by a channel process when it is - about to terminate. Before this function is called ssh_connection:close/2 - will be called if it has not been called earlier. - This function should be the opposite of CallbackModule:init/1 - and do any necessary cleaning up. When it returns, the - channel process terminates with reason Reason. The return value is - ignored. + about to terminate. Before this function is called ssh_connection:close/2 + will be called if it has not been called earlier. + This function should do any necessary cleaning + up. When it returns, the channel process terminates with + reason Reason. The return value is ignored.

-- cgit v1.2.3