diff options
Diffstat (limited to 'lib/ssh/doc')
| -rw-r--r-- | lib/ssh/doc/src/Makefile | 15 | ||||
| -rw-r--r-- | lib/ssh/doc/src/ref_man.xml | 3 | ||||
| -rw-r--r-- | lib/ssh/doc/src/specs.xml | 7 | ||||
| -rw-r--r-- | lib/ssh/doc/src/ssh.xml | 6 | ||||
| -rw-r--r-- | lib/ssh/doc/src/ssh_channel.xml | 5 | ||||
| -rw-r--r-- | lib/ssh/doc/src/ssh_daemon_channel.xml | 127 | ||||
| -rw-r--r-- | lib/ssh/doc/src/ssh_protocol.xml | 2 | ||||
| -rw-r--r-- | lib/ssh/doc/src/ssh_server_channel.xml | 176 | ||||
| -rw-r--r-- | lib/ssh/doc/src/ssh_sftpd.xml | 2 | ||||
| -rw-r--r-- | lib/ssh/doc/src/using_ssh.xml | 2 |
10 files changed, 205 insertions, 140 deletions
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 @@ <xi:include href="ssh_app.xml"/> <xi:include href="ssh.xml"/> <xi:include href="ssh_channel.xml"/> - <xi:include href="ssh_daemon_channel.xml"/> + <xi:include href="ssh_server_channel.xml"/> + <!-- xi:include href="ssh_daemon_channel.xml"/ --> <xi:include href="ssh_connection.xml"/> <xi:include href="ssh_client_key_api.xml"/> <xi:include href="ssh_server_key_api.xml"/> 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 @@ <?xml version="1.0" encoding="utf-8" ?> <specs xmlns:xi="http://www.w3.org/2001/XInclude"> + <xi:include href="../specs/specs_ssh.xml"/> <xi:include href="../specs/specs_ssh_channel.xml"/> - <xi:include href="../specs/specs_ssh_daemon_channel.xml"/> <xi:include href="../specs/specs_ssh_client_key_api.xml"/> <xi:include href="../specs/specs_ssh_connection.xml"/> + <xi:include href="../specs/specs_ssh_daemon_channel.xml"/> + <xi:include href="../specs/specs_ssh_server_channel.xml"/> <xi:include href="../specs/specs_ssh_server_key_api.xml"/> - <xi:include href="../specs/specs_ssh_sftpd.xml"/> <xi:include href="../specs/specs_ssh_sftp.xml"/> - <xi:include href="../specs/specs_ssh.xml"/> + <xi:include href="../specs/specs_ssh_sftpd.xml"/> </specs> 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 @@ <seealso marker="ssh_sftp#start_channel/1">ssh_sftp:start_channel/1,2,3</seealso>. </p> <p>To write your own client channel handler, use the behaviour - <seealso marker="ssh_channel">ssh_channel</seealso>. and server channel handlers use - <seealso marker="ssh_daemon_channel">ssh_daemon_channel</seealso> behaviour. + <seealso marker="ssh_channel">ssh_channel</seealso>. For server channel handlers use + <seealso marker="ssh_server_channel">ssh_server_channel</seealso> behaviour (replaces ssh_daemon_channel). </p> <p>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 @@ <seealso marker="ssh_connection#subsystem/4">ssh_connection:subsystem/4</seealso>. </p> <p>The <c>channel_callback</c> is the module that implements the - <seealso marker="ssh_daemon_channel">ssh_daemon_channel</seealso> + <seealso marker="ssh_server_channel">ssh_server_channel</seealso> (replaces ssh_daemon_channel) behaviour in the daemon. See the section <seealso marker="using_ssh#usersguide_creating_a_subsystem">Creating a Subsystem</seealso> 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 @@ </p> <note><p>When implementing a <c>ssh</c> subsystem for daemons, use - <seealso marker="ssh_daemon_channel">-behaviour(ssh_daemon_channel)</seealso> instead. + <seealso marker="ssh_server_channel">-behaviour(ssh_server_channel)</seealso> (Replaces ssh_daemon_channel) + instead. </p> </note> @@ -223,7 +224,7 @@ <title>Callback Functions</title> <p> The following functions are to be exported from a - <c>ssh_daemon_channel</c> callback module. + <c>ssh_channel</c> callback module. </p> <marker id="cb_timeouts"></marker> <section> 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 @@ <modulesummary>-behaviour(ssh_daemon_channel). </modulesummary> <description> - <p>SSH services (clients and servers) are implemented as channels - that are multiplexed over an SSH connection and communicates over - the <url href="http://www.ietf.org/rfc/rfc4254.txt"> SSH - Connection Protocol</url>. 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 <c>ssh</c> applications supervisor tree. + <p>This behaviour should NOT be used for new programs but is kept for compatibility. </p> - - <note><p>When implementing a client subsystem handler, use - <seealso marker="ssh_channel">-behaviour(ssh_channel)</seealso> instead. - </p> - </note> - + <p>It is replaced by <seealso marker="ssh_server_channel">ssh_server_channel</seealso>.</p> </description> - <section> - <title>Callback Functions</title> - <p> - The following functions are to be exported from a - <c>ssh_daemon_channel</c> callback module. - </p> - </section> - <funcs> <func> - <name>Module:init(Args) -> {ok, State} | {ok, State, timeout()} | - {stop, Reason}</name> - <fsummary>Makes necessary initializations and returns the - initial channel state if the initializations succeed.</fsummary> - <type> - <v>Args = term()</v> - <d>Last argument to <c>start_link/4</c>.</d> - <v>State = term()</v> - <v>Reason = term()</v> - </type> - <desc> - <p>Makes necessary initializations and returns the initial channel - state if the initializations succeed. - </p> - <p>The time-out values that can be returned - have the same semantics as in a <seealso marker="stdlib:gen_server">gen_server</seealso>. - If the time-out occurs, <seealso marker="#Module:handle_msg-2">handle_msg/2</seealso> - is called as <c>handle_msg(timeout, State)</c>. - </p> - </desc> - </func> - - <func> - <name>Module:handle_msg(Msg, State) -> {ok, State} | - {stop, ChannelId, State}</name> - - <fsummary>Handles other messages than SSH connection protocol, - call, or cast messages sent to the channel.</fsummary> - <type> - <v>Msg = timeout | term()</v> - <v>ChannelId = <seealso marker="ssh#type-channel_id">ssh:channel_id()</seealso></v> - <v>State = term() </v> - </type> - <desc> - <p>Handles other messages than SSH Connection Protocol, call, or - cast messages sent to the channel. - </p> - - <p>Possible Erlang 'EXIT' messages is to be handled by this - function and all channels are to handle the following message.</p> - - <taglist> - <tag><c>{ssh_channel_up, ssh:channel_id(), ssh:connection_ref()}</c></tag> - <item><p>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 <c>{ok, State}</c>. - </p></item> - </taglist> - </desc> - </func> - - <func> - <name>Module:handle_ssh_msg(Msg, State) -> {ok, State} | {stop, - ChannelId, State}</name> - <fsummary>Handles <c>ssh</c> connection protocol messages.</fsummary> - <type> - <v>Msg = ssh_connection:event()</v> - <v>ChannelId = <seealso marker="ssh#type-channel_id">ssh:channel_id()</seealso></v> - <v>State = term()</v> - </type> - <desc> - <p>Handles SSH Connection Protocol messages that may need - service-specific attention. For details, - see <seealso marker="ssh_connection"> ssh_connection:event()</seealso>. - </p> - - <p>The following message is taken care of by the - <c>ssh_daemon_channel</c> behavior.</p> - - <taglist> - <tag><c>{closed, ssh:channel_id()}</c></tag> - <item><p>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 <c>normal</c>.</p></item> - </taglist> - </desc> - </func> - - <func> - <name>Module:terminate(Reason, State) -> _</name> - <fsummary>Does cleaning up before channel process termination. - </fsummary> - <type> - <v>Reason = term()</v> - <v>State = term()</v> - </type> + <name>Module:CALLBACK(..)</name> + <fsummary>ssh_daemon_channel is replaced by ssh_server_channel</fsummary> <desc> - <p>This function is called by a channel process when it is - about to terminate. Before this function is called, <seealso - marker="ssh_connection#close-2"> ssh_connection:close/2 - </seealso> 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 <c>Reason</c>. The return value is ignored. + <p>See <seealso marker="ssh_server_channel">ssh_server_channel</seealso> which replaces this module. </p> </desc> </func> - </funcs> </erlref> 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 <seealso marker="ssh_channel">ssh_channel</seealso> / - <seealso marker="ssh_daemon_channel">ssh_daemon_channel</seealso> + <seealso marker="ssh_server_channel">ssh_server_channel</seealso> (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 @@ +<?xml version="1.0" encoding="utf-8" ?> +<!DOCTYPE erlref SYSTEM "erlref.dtd"> + +<erlref> + <header> + <copyright> + <year>2009</year> + <year>2016</year> + <holder>Ericsson AB, All Rights Reserved</holder> + </copyright> + <legalnotice> + 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. + </legalnotice> + <title>ssh_server_channel</title> + <prepared></prepared> + <docno></docno> + <date></date> + <rev></rev> + </header> + <module>ssh_server_channel</module> + <modulesummary>-behaviour(ssh_server_channel). (Replaces ssh_daemon_channel) + </modulesummary> + <description> + <note> + <p>This module replaces ssh_daemon_channel.</p> + <p>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 + </p> + </note> + + <p>SSH services (clients and servers) are implemented as channels + that are multiplexed over an SSH connection and communicates over + the <url href="http://www.ietf.org/rfc/rfc4254.txt"> SSH + Connection Protocol</url>. 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 <c>ssh</c> applications supervisor tree. + </p> + + <note><p>When implementing a client subsystem handler, use + <seealso marker="ssh_channel">-behaviour(ssh_channel)</seealso> instead. + </p> + </note> + + </description> + + <section> + <title>Callback Functions</title> + <p> + The following functions are to be exported from a + <c>ssh_server_channel</c> callback module. + </p> + </section> + + <funcs> + <func> + <name>Module:init(Args) -> {ok, State} | {ok, State, timeout()} | + {stop, Reason}</name> + <fsummary>Makes necessary initializations and returns the + initial channel state if the initializations succeed.</fsummary> + <type> + <v>Args = term()</v> + <d>Last argument to <c>start_link/4</c>.</d> + <v>State = term()</v> + <v>Reason = term()</v> + </type> + <desc> + <p>Makes necessary initializations and returns the initial channel + state if the initializations succeed. + </p> + <p>The time-out values that can be returned + have the same semantics as in a <seealso marker="stdlib:gen_server">gen_server</seealso>. + If the time-out occurs, <seealso marker="#Module:handle_msg-2">handle_msg/2</seealso> + is called as <c>handle_msg(timeout, State)</c>. + </p> + </desc> + </func> + + <func> + <name>Module:handle_msg(Msg, State) -> {ok, State} | + {stop, ChannelId, State}</name> + + <fsummary>Handles other messages than SSH connection protocol, + call, or cast messages sent to the channel.</fsummary> + <type> + <v>Msg = timeout | term()</v> + <v>ChannelId = <seealso marker="ssh#type-channel_id">ssh:channel_id()</seealso></v> + <v>State = term() </v> + </type> + <desc> + <p>Handles other messages than SSH Connection Protocol, call, or + cast messages sent to the channel. + </p> + + <p>Possible Erlang 'EXIT' messages is to be handled by this + function and all channels are to handle the following message.</p> + + <taglist> + <tag><c>{ssh_channel_up, ssh:channel_id(), ssh:connection_ref()}</c></tag> + <item><p>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 <c>{ok, State}</c>. + </p></item> + </taglist> + </desc> + </func> + + <func> + <name>Module:handle_ssh_msg(Msg, State) -> {ok, State} | {stop, + ChannelId, State}</name> + <fsummary>Handles <c>ssh</c> connection protocol messages.</fsummary> + <type> + <v>Msg = ssh_connection:event()</v> + <v>ChannelId = <seealso marker="ssh#type-channel_id">ssh:channel_id()</seealso></v> + <v>State = term()</v> + </type> + <desc> + <p>Handles SSH Connection Protocol messages that may need + service-specific attention. For details, + see <seealso marker="ssh_connection"> ssh_connection:event()</seealso>. + </p> + + <p>The following message is taken care of by the + <c>ssh_server_channel</c> behavior.</p> + + <taglist> + <tag><c>{closed, ssh:channel_id()}</c></tag> + <item><p>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 <c>normal</c>.</p></item> + </taglist> + </desc> + </func> + + <func> + <name>Module:terminate(Reason, State) -> _</name> + <fsummary>Does cleaning up before channel process termination. + </fsummary> + <type> + <v>Reason = term()</v> + <v>State = term()</v> + </type> + <desc> + <p>This function is called by a channel process when it is + about to terminate. Before this function is called, <seealso + marker="ssh_connection#close-2"> ssh_connection:close/2 + </seealso> 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 <c>Reason</c>. The return value is ignored. + </p> + </desc> + </func> + + </funcs> + +</erlref> 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 @@ <item><p><c>"sftp"</c></p></item> <tag><c>channel_callback() =</c></tag> <item><p><c>atom()</c> - Name of the Erlang module implementing the subsystem using the - <seealso marker="ssh_daemon_channel">ssh_daemon_channel</seealso> behaviour.</p></item> + <seealso marker="ssh_server_channel">ssh_server_channel</seealso> (replaces ssh_daemon_channel) behaviour.</p></item> <tag><c>channel_init_args() =</c></tag> <item><p><c>list()</c> - The one given as argument to function <c>subsystem_spec/1</c>.</p></item> </taglist> 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), <code type="erl" > -module(ssh_echo_server). --behaviour(ssh_daemon_channel). +-behaviour(ssh_server_channel). % replaces ssh_daemon_channel -record(state, { n, id, |