aboutsummaryrefslogtreecommitdiffstats
path: root/lib/ssh/doc/src
diff options
context:
space:
mode:
authorHans Nilsson <[email protected]>2018-04-26 11:50:11 +0200
committerHans Nilsson <[email protected]>2018-04-27 10:30:25 +0200
commitd2f4de0a8e36e6a25cfd7446ea6fc3623b7f1495 (patch)
treea8008982b59d5870118a4e1d328536b71c2e679b /lib/ssh/doc/src
parent8b50978cdc82d404f68384e1aadf7685a9d86af4 (diff)
downloadotp-d2f4de0a8e36e6a25cfd7446ea6fc3623b7f1495.tar.gz
otp-d2f4de0a8e36e6a25cfd7446ea6fc3623b7f1495.tar.bz2
otp-d2f4de0a8e36e6a25cfd7446ea6fc3623b7f1495.zip
ssh: ssh_daemon_channel replaced by ssh_server_channel
Diffstat (limited to 'lib/ssh/doc/src')
-rw-r--r--lib/ssh/doc/src/Makefile15
-rw-r--r--lib/ssh/doc/src/ref_man.xml3
-rw-r--r--lib/ssh/doc/src/specs.xml7
-rw-r--r--lib/ssh/doc/src/ssh.xml6
-rw-r--r--lib/ssh/doc/src/ssh_channel.xml5
-rw-r--r--lib/ssh/doc/src/ssh_daemon_channel.xml127
-rw-r--r--lib/ssh/doc/src/ssh_protocol.xml2
-rw-r--r--lib/ssh/doc/src/ssh_server_channel.xml176
-rw-r--r--lib/ssh/doc/src/ssh_sftpd.xml2
-rw-r--r--lib/ssh/doc/src/using_ssh.xml2
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,