From d2f4de0a8e36e6a25cfd7446ea6fc3623b7f1495 Mon Sep 17 00:00:00 2001 From: Hans Nilsson Date: Thu, 26 Apr 2018 11:50:11 +0200 Subject: ssh: ssh_daemon_channel replaced by ssh_server_channel --- lib/ssh/doc/src/Makefile | 15 +-- lib/ssh/doc/src/ref_man.xml | 3 +- lib/ssh/doc/src/specs.xml | 7 +- lib/ssh/doc/src/ssh.xml | 6 +- lib/ssh/doc/src/ssh_channel.xml | 5 +- lib/ssh/doc/src/ssh_daemon_channel.xml | 127 +----------------------- lib/ssh/doc/src/ssh_protocol.xml | 2 +- lib/ssh/doc/src/ssh_server_channel.xml | 176 +++++++++++++++++++++++++++++++++ lib/ssh/doc/src/ssh_sftpd.xml | 2 +- lib/ssh/doc/src/using_ssh.xml | 2 +- 10 files changed, 205 insertions(+), 140 deletions(-) create mode 100644 lib/ssh/doc/src/ssh_server_channel.xml (limited to 'lib/ssh/doc') diff --git a/lib/ssh/doc/src/Makefile b/lib/ssh/doc/src/Makefile index f47a1bfb40..9b5bee34fa 100644 --- a/lib/ssh/doc/src/Makefile +++ b/lib/ssh/doc/src/Makefile @@ -38,20 +38,23 @@ RELSYSDIR = $(RELEASE_PATH)/lib/$(APPLICATION)-$(VSN) # Target Specs # ---------------------------------------------------- XML_APPLICATION_FILES = ref_man.xml -XML_REF3_FILES = ssh.xml \ +XML_REF3_FILES = \ + ssh.xml \ ssh_channel.xml \ - ssh_daemon_channel.xml \ - ssh_connection.xml \ ssh_client_key_api.xml \ + ssh_connection.xml \ + ssh_daemon_channel.xml \ + ssh_server_channel.xml \ ssh_server_key_api.xml \ ssh_sftp.xml \ ssh_sftpd.xml \ XML_REF6_FILES = ssh_app.xml -XML_PART_FILES = \ - usersguide.xml -XML_CHAPTER_FILES = notes.xml \ +XML_PART_FILES = usersguide.xml + +XML_CHAPTER_FILES = \ + notes.xml \ introduction.xml \ using_ssh.xml \ configure_algos.xml diff --git a/lib/ssh/doc/src/ref_man.xml b/lib/ssh/doc/src/ref_man.xml index 1e1cff9119..3351699c66 100644 --- a/lib/ssh/doc/src/ref_man.xml +++ b/lib/ssh/doc/src/ref_man.xml @@ -36,7 +36,8 @@ - + + diff --git a/lib/ssh/doc/src/specs.xml b/lib/ssh/doc/src/specs.xml index f7837f9c5c..15e76cb5fa 100644 --- a/lib/ssh/doc/src/specs.xml +++ b/lib/ssh/doc/src/specs.xml @@ -1,13 +1,14 @@ + - + + - - + diff --git a/lib/ssh/doc/src/ssh.xml b/lib/ssh/doc/src/ssh.xml index c403989ba9..da122b6081 100644 --- a/lib/ssh/doc/src/ssh.xml +++ b/lib/ssh/doc/src/ssh.xml @@ -68,8 +68,8 @@ ssh_sftp:start_channel/1,2,3.

To write your own client channel handler, use the behaviour - ssh_channel. and server channel handlers use - ssh_daemon_channel behaviour. + ssh_channel. For server channel handlers use + ssh_server_channel behaviour (replaces ssh_daemon_channel).

Both clients and daemons accepts options that controls the exact behaviour. Some options are common to both. The three sets are called @@ -379,7 +379,7 @@ ssh_connection:subsystem/4.

The channel_callback is the module that implements the - ssh_daemon_channel + ssh_server_channel (replaces ssh_daemon_channel) behaviour in the daemon. See the section Creating a Subsystem in the User's Guide for more information and an example. diff --git a/lib/ssh/doc/src/ssh_channel.xml b/lib/ssh/doc/src/ssh_channel.xml index b4bcd148f3..63a480d747 100644 --- a/lib/ssh/doc/src/ssh_channel.xml +++ b/lib/ssh/doc/src/ssh_channel.xml @@ -47,7 +47,8 @@

When implementing a ssh subsystem for daemons, use - -behaviour(ssh_daemon_channel) instead. + -behaviour(ssh_server_channel) (Replaces ssh_daemon_channel) + instead.

@@ -223,7 +224,7 @@ Callback Functions

The following functions are to be exported from a - ssh_daemon_channel callback module. + ssh_channel callback module.

diff --git a/lib/ssh/doc/src/ssh_daemon_channel.xml b/lib/ssh/doc/src/ssh_daemon_channel.xml index 8b0ff93f5f..254f75a4de 100644 --- a/lib/ssh/doc/src/ssh_daemon_channel.xml +++ b/lib/ssh/doc/src/ssh_daemon_channel.xml @@ -33,137 +33,20 @@ -behaviour(ssh_daemon_channel). -

SSH services (clients and servers) are implemented as channels - that are multiplexed over an SSH connection and communicates over - the SSH - Connection Protocol. This module provides a callback API - that takes care of generic channel aspects for daemons, such as flow control - and close messages. It 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. +

This behaviour should NOT be used for new programs but is kept for compatibility.

- -

When implementing a client subsystem handler, use - -behaviour(ssh_channel) instead. -

- - +

It is replaced by ssh_server_channel.

 -
- Callback Functions -

- The following functions are to be exported from a - ssh_daemon_channel callback module. -

-
- - Module:init(Args) -> {ok, State} | {ok, State, timeout()} | - {stop, Reason} - Makes necessary initializations and returns the - initial channel state if the initializations succeed. - - Args = term() - Last argument to start_link/4. - State = term() - Reason = term() - - -

Makes necessary initializations and returns the initial channel - state if the initializations succeed. -

-

The time-out values that can be returned - have the same semantics as in a gen_server. - If the time-out occurs, handle_msg/2 - is called as handle_msg(timeout, State). -

- - - - - Module:handle_msg(Msg, State) -> {ok, State} | - {stop, ChannelId, State} - - Handles other messages than SSH connection protocol, - call, or cast messages sent to the channel. - - Msg = timeout | term() - ChannelId = ssh:channel_id() - State = term() - - -

Handles other messages than SSH Connection Protocol, call, or - cast messages sent to the channel. -

- -

Possible Erlang 'EXIT' messages is to be handled by this - function and all channels are to handle the following message.

- - - {ssh_channel_up, ssh:channel_id(), ssh:connection_ref()} -

This is the first message that the channel receives. - 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, ignore it by - immediately returning {ok, State}. -

- - - - - - Module:handle_ssh_msg(Msg, State) -> {ok, State} | {stop, - ChannelId, State} - Handles ssh connection protocol messages. - - Msg = ssh_connection:event() - ChannelId = ssh:channel_id() - State = term() - - -

Handles SSH Connection Protocol messages that may need - service-specific attention. For details, - see ssh_connection:event(). -

- -

The following message is taken care of by the - ssh_daemon_channel behavior.

- - - {closed, ssh:channel_id()} -

The channel behavior sends a close message to the - other side, if such a message has not already been sent. - Then it terminates the channel with reason normal.

 - - - - - - Module:terminate(Reason, State) -> _ - Does cleaning up before channel process termination. - - - Reason = term() - State = term() - + Module:CALLBACK(..) + ssh_daemon_channel is replaced by ssh_server_channel -

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

See ssh_server_channel which replaces this module.

- diff --git a/lib/ssh/doc/src/ssh_protocol.xml b/lib/ssh/doc/src/ssh_protocol.xml index 21c755b48e..4548d7bbb6 100644 --- a/lib/ssh/doc/src/ssh_protocol.xml +++ b/lib/ssh/doc/src/ssh_protocol.xml @@ -89,7 +89,7 @@ data/"control information" and when it is done close the channel. The ssh_channel / - ssh_daemon_channel + ssh_server_channel (Replaces ssh_daemon_channel) behaviours makes it easy to write your own SSH client/server processes that use flow control. It handles generic parts of SSH channel management and diff --git a/lib/ssh/doc/src/ssh_server_channel.xml b/lib/ssh/doc/src/ssh_server_channel.xml new file mode 100644 index 0000000000..19fc20fcda --- /dev/null +++ b/lib/ssh/doc/src/ssh_server_channel.xml @@ -0,0 +1,176 @@ + + + + +
+ + 2009 + 2016 + Ericsson AB, All Rights Reserved + + + Licensed under the Apache License, Version 2.0 (the "License"); + you may not use this file except in compliance with the License. + You may obtain a copy of the License at + + http://www.apache.org/licenses/LICENSE-2.0 + + Unless required by applicable law or agreed to in writing, software + distributed under the License is distributed on an "AS IS" BASIS, + WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + See the License for the specific language governing permissions and + limitations under the License. + + The Initial Developer of the Original Code is Ericsson AB. + + ssh_server_channel + + + + +
+ ssh_server_channel + -behaviour(ssh_server_channel). (Replaces ssh_daemon_channel) + + + +

This module replaces ssh_daemon_channel.

+

The old module is still available for compatibility, but should not be used for new programs. + The old module will not be maintained except for some error corrections +

+ + +

SSH services (clients and servers) are implemented as channels + that are multiplexed over an SSH connection and communicates over + the SSH + Connection Protocol. This module provides a callback API + that takes care of generic channel aspects for daemons, such as flow control + and close messages. It 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. +

+ +

When implementing a client subsystem handler, use + -behaviour(ssh_channel) instead. +

+ + + + +
+ Callback Functions +

+ The following functions are to be exported from a + ssh_server_channel callback module. +

+
+ + + + Module:init(Args) -> {ok, State} | {ok, State, timeout()} | + {stop, Reason} + Makes necessary initializations and returns the + initial channel state if the initializations succeed. + + Args = term() + Last argument to start_link/4. + State = term() + Reason = term() + + +

Makes necessary initializations and returns the initial channel + state if the initializations succeed. +

+

The time-out values that can be returned + have the same semantics as in a gen_server. + If the time-out occurs, handle_msg/2 + is called as handle_msg(timeout, State). +

+ + + + + Module:handle_msg(Msg, State) -> {ok, State} | + {stop, ChannelId, State} + + Handles other messages than SSH connection protocol, + call, or cast messages sent to the channel. + + Msg = timeout | term() + ChannelId = ssh:channel_id() + State = term() + + +

Handles other messages than SSH Connection Protocol, call, or + cast messages sent to the channel. +

+ +

Possible Erlang 'EXIT' messages is to be handled by this + function and all channels are to handle the following message.

+ + + {ssh_channel_up, ssh:channel_id(), ssh:connection_ref()} +

This is the first message that the channel receives. + 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, ignore it by + immediately returning {ok, State}. +

+ + + + + + Module:handle_ssh_msg(Msg, State) -> {ok, State} | {stop, + ChannelId, State} + Handles ssh connection protocol messages. + + Msg = ssh_connection:event() + ChannelId = ssh:channel_id() + State = term() + + +

Handles SSH Connection Protocol messages that may need + service-specific attention. For details, + see ssh_connection:event(). +

+ +

The following message is taken care of by the + ssh_server_channel behavior.

+ + + {closed, ssh:channel_id()} +

The channel behavior sends a close message to the + other side, if such a message has not already been sent. + Then it terminates the channel with reason normal.

 + + + + + + Module:terminate(Reason, State) -> _ + Does cleaning up before channel process termination. + + + Reason = term() + State = term() + + +

This function is called by a channel process when it is + about to terminate. Before this function is called, ssh_connection:close/2 + is called, if it has not been called earlier. + This function does any necessary cleaning + up. When it returns, the channel process terminates with + reason Reason. The return value is ignored. +

+ + + + + + diff --git a/lib/ssh/doc/src/ssh_sftpd.xml b/lib/ssh/doc/src/ssh_sftpd.xml index 4c599a7fb9..a25ce123b3 100644 --- a/lib/ssh/doc/src/ssh_sftpd.xml +++ b/lib/ssh/doc/src/ssh_sftpd.xml @@ -44,7 +44,7 @@

"sftp"

 channel_callback() =

atom() - Name of the Erlang module implementing the subsystem using the - ssh_daemon_channel behaviour.

 + ssh_server_channel (replaces ssh_daemon_channel) behaviour.

channel_init_args() =

list() - The one given as argument to function subsystem_spec/1.

 diff --git a/lib/ssh/doc/src/using_ssh.xml b/lib/ssh/doc/src/using_ssh.xml index bde2aaaf99..fef0784eb6 100644 --- a/lib/ssh/doc/src/using_ssh.xml +++ b/lib/ssh/doc/src/using_ssh.xml @@ -306,7 +306,7 @@ ok = erl_tar:close(HandleRead), -module(ssh_echo_server). --behaviour(ssh_daemon_channel). +-behaviour(ssh_server_channel). % replaces ssh_daemon_channel -record(state, { n, id, -- cgit v1.2.3