aboutsummaryrefslogtreecommitdiffstats
path: root/lib/ssh/doc/src
diff options
context:
space:
mode:
authorErlang/OTP <[email protected]>2009-11-20 14:54:40 +0000
committerErlang/OTP <[email protected]>2009-11-20 14:54:40 +0000
commit84adefa331c4159d432d22840663c38f155cd4c1 (patch)
treebff9a9c66adda4df2106dfd0e5c053ab182a12bd /lib/ssh/doc/src
downloadotp-84adefa331c4159d432d22840663c38f155cd4c1.tar.gz
otp-84adefa331c4159d432d22840663c38f155cd4c1.tar.bz2
otp-84adefa331c4159d432d22840663c38f155cd4c1.zip
The R13B03 release.OTP_R13B03
Diffstat (limited to 'lib/ssh/doc/src')
-rw-r--r--lib/ssh/doc/src/Makefile205
-rw-r--r--lib/ssh/doc/src/book.xml46
-rw-r--r--lib/ssh/doc/src/fascicules.xml15
-rw-r--r--lib/ssh/doc/src/make.dep19
-rw-r--r--lib/ssh/doc/src/notes.xml588
-rw-r--r--lib/ssh/doc/src/notes_history.xml737
-rw-r--r--lib/ssh/doc/src/part_notes.xml38
-rw-r--r--lib/ssh/doc/src/part_notes_history.xml36
-rw-r--r--lib/ssh/doc/src/ref_man.xml41
-rw-r--r--lib/ssh/doc/src/ssh.xml337
-rw-r--r--lib/ssh/doc/src/ssh_channel.xml520
-rw-r--r--lib/ssh/doc/src/ssh_connection.xml302
-rw-r--r--lib/ssh/doc/src/ssh_sftp.xml501
-rw-r--r--lib/ssh/doc/src/ssh_sftpd.xml94
-rw-r--r--lib/ssh/doc/src/user_guide.gifbin0 -> 1581 bytes
15 files changed, 3479 insertions, 0 deletions
diff --git a/lib/ssh/doc/src/Makefile b/lib/ssh/doc/src/Makefile
new file mode 100644
index 0000000000..d2907a39d7
--- /dev/null
+++ b/lib/ssh/doc/src/Makefile
@@ -0,0 +1,205 @@
+#
+# %CopyrightBegin%
+#
+# Copyright Ericsson AB 2004-2009. All Rights Reserved.
+#
+# The contents of this file are subject to the Erlang Public License,
+# Version 1.1, (the "License"); you may not use this file except in
+# compliance with the License. You should have received a copy of the
+# Erlang Public License along with this software. If not, it can be
+# retrieved online at http://www.erlang.org/.
+#
+# Software distributed under the License is distributed on an "AS IS"
+# basis, WITHOUT WARRANTY OF ANY KIND, either express or implied. See
+# the License for the specific language governing rights and limitations
+# under the License.
+#
+# %CopyrightEnd%
+#
+
+#
+include $(ERL_TOP)/make/target.mk
+include $(ERL_TOP)/make/$(TARGET)/otp.mk
+
+# ----------------------------------------------------
+# Application version
+# ----------------------------------------------------
+include ../../vsn.mk
+VSN=$(SSH_VSN)
+APPLICATION=ssh
+
+# ----------------------------------------------------
+# Include dependency
+# ----------------------------------------------------
+
+
+ifndef DOCSUPPORT
+include make.dep
+endif
+
+# ----------------------------------------------------
+# Release directory specification
+# ----------------------------------------------------
+RELSYSDIR = $(RELEASE_PATH)/lib/$(APPLICATION)-$(VSN)
+
+# ----------------------------------------------------
+# Target Specs
+# ----------------------------------------------------
+XML_APPLICATION_FILES = ref_man.xml
+XML_REF3_FILES = \
+ ssh.xml \
+ ssh_channel.xml \
+ ssh_connection.xml\
+ ssh_sftp.xml \
+ ssh_sftpd.xml \
+
+XML_PART_FILES = part_notes.xml part_notes_history.xml
+XML_CHAPTER_FILES = notes.xml notes_history.xml
+
+BOOK_FILES = book.xml
+
+# ----------------------------------------------------
+
+HTML_FILES = $(XML_APPLICATION_FILES:%.xml=$(HTMLDIR)/%.html) \
+ $(XML_PART_FILES:%.xml=$(HTMLDIR)/%.html)
+
+INFO_FILE = ../../info
+EXTRA_FILES = \
+ $(DEFAULT_GIF_FILES) \
+ $(DEFAULT_HTML_FILES) \
+ $(XML_REF3_FILES:%.xml=$(HTMLDIR)/%.html) \
+ $(XML_CHAPTER_FILES:%.xml=$(HTMLDIR)/%.html)
+
+# notes_history.html \
+
+
+MAN3_FILES = $(XML_REF3_FILES:%.xml=$(MAN3DIR)/%.3)
+
+
+ifdef DOCSUPPORT
+
+HTML_REF_MAN_FILE = $(HTMLDIR)/index.html
+
+TOP_PDF_FILE = $(PDFDIR)/$(APPLICATION)-$(VSN).pdf
+
+else
+
+TEX_FILES_BOOK = \
+ $(BOOK_FILES:%.xml=%.tex)
+TEX_FILES_REF_MAN = $(XML_REF3_FILES:%.xml=%.tex) \
+ $(XML_APPLICATION_FILES:%.xml=%.tex)
+TEX_FILES_USERS_GUIDE = \
+ $(XML_CHAPTER_FILES:%.xml=%.tex)
+
+TOP_PDF_FILE = $(APPLICATION)-$(VSN).pdf
+TOP_PS_FILE = $(APPLICATION)-$(VSN).ps
+
+$(TOP_PDF_FILE): book.dvi ../../vsn.mk
+ $(DVI2PS) $(DVIPS_FLAGS) -f $< | $(DISTILL) $(DISTILL_FLAGS) > $@
+
+$(TOP_PS_FILE): book.dvi ../../vsn.mk
+ $(DVI2PS) $(DVIPS_FLAGS) -f $< > $@
+
+endif
+
+# ----------------------------------------------------
+# FLAGS
+# ----------------------------------------------------
+XML_FLAGS +=
+DVIPS_FLAGS +=
+
+# ----------------------------------------------------
+# Targets
+# ----------------------------------------------------
+$(HTMLDIR)/%.gif: %.gif
+ $(INSTALL_DATA) $< $@
+
+ifdef DOCSUPPORT
+
+docs: pdf html man
+
+$(TOP_PDF_FILE): $(XML_FILES)
+
+pdf: $(TOP_PDF_FILE)
+
+html: $(HTML_REF_MAN_FILE)
+
+clean clean_docs:
+ rm -rf $(HTMLDIR)/*
+ rm -f $(MAN3DIR)/*
+ rm -f $(TOP_PDF_FILE) $(TOP_PDF_FILE:%.pdf=%.fo)
+ rm -f errs core *~
+
+else
+
+ifeq ($(DOCTYPE),pdf)
+docs: pdf
+else
+ifeq ($(DOCTYPE),ps)
+docs: ps
+else
+docs: html man
+endif
+endif
+
+pdf: $(TOP_PDF_FILE)
+
+ps: $(TOP_PS_FILE)
+
+html: $(HTML_FILES)
+
+clean clean_docs clean_tex:
+ rm -f $(TEX_FILES_USERS_GUIDE) $(TEX_FILES_REF_MAN) $(TEX_FILES_BOOK)
+ rm -f $(HTML_FILES) $(MAN3_FILES)
+ rm -f $(TOP_PDF_FILE) $(TOP_PS_FILE)
+ rm -f errs core *~ *xmls_output *xmls_errs $(LATEX_CLEAN)
+
+endif
+
+man: $(MAN3_FILES)
+
+
+debug opt:
+
+
+# ----------------------------------------------------
+# Release Target
+# ----------------------------------------------------
+include $(ERL_TOP)/make/otp_release_targets.mk
+
+ifdef DOCSUPPORT
+
+release_docs_spec: docs
+ $(INSTALL_DIR) $(RELSYSDIR)/doc/pdf
+ $(INSTALL_DATA) $(TOP_PDF_FILE) $(RELSYSDIR)/doc/pdf
+ $(INSTALL_DIR) $(RELSYSDIR)/doc/html
+ $(INSTALL_DATA) $(HTMLDIR)/* \
+ $(RELSYSDIR)/doc/html
+ $(INSTALL_DATA) $(INFO_FILE) $(RELSYSDIR)
+ $(INSTALL_DIR) $(RELEASE_PATH)/man/man3
+ $(INSTALL_DATA) $(MAN3DIR)/* $(RELEASE_PATH)/man/man3
+else
+
+ifeq ($(DOCTYPE),pdf)
+release_docs_spec: pdf
+ $(INSTALL_DIR) $(RELEASE_PATH)/pdf
+ $(INSTALL_DATA) $(TOP_PDF_FILE) $(RELEASE_PATH)/pdf
+else
+ifeq ($(DOCTYPE),ps)
+release_docs_spec: ps
+ $(INSTALL_DIR) $(RELEASE_PATH)/ps
+ $(INSTALL_DATA) $(TOP_PS_FILE) $(RELEASE_PATH)/ps
+else
+release_docs_spec: docs
+ $(INSTALL_DIR) $(RELSYSDIR)/doc/html
+ $(INSTALL_DATA) $(EXTRA_FILES) $(HTML_FILES) \
+ $(RELSYSDIR)/doc/html
+ $(INSTALL_DATA) $(INFO_FILE) $(RELSYSDIR)
+ $(INSTALL_DIR) $(RELEASE_PATH)/man/man3
+ $(INSTALL_DATA) $(MAN3_FILES) $(RELEASE_PATH)/man/man3
+endif
+endif
+
+endif
+
+release_spec:
diff --git a/lib/ssh/doc/src/book.xml b/lib/ssh/doc/src/book.xml
new file mode 100644
index 0000000000..0375c441af
--- /dev/null
+++ b/lib/ssh/doc/src/book.xml
@@ -0,0 +1,46 @@
+<?xml version="1.0" encoding="latin1" ?>
+<!DOCTYPE book SYSTEM "book.dtd">
+
+<book xmlns:xi="http://www.w3.org/2001/XInclude">
+ <header titlestyle="normal">
+ <copyright>
+ <year>2005</year><year>2009</year>
+ <holder>Ericsson AB. All Rights Reserved.</holder>
+ </copyright>
+ <legalnotice>
+ The contents of this file are subject to the Erlang Public License,
+ Version 1.1, (the "License"); you may not use this file except in
+ compliance with the License. You should have received a copy of the
+ Erlang Public License along with this software. If not, it can be
+ retrieved online at http://www.erlang.org/.
+
+ Software distributed under the License is distributed on an "AS IS"
+ basis, WITHOUT WARRANTY OF ANY KIND, either express or implied. See
+ the License for the specific language governing rights and limitations
+ under the License.
+
+ </legalnotice>
+
+ <title>SSH</title>
+ <prepared>OTP Team</prepared>
+ <docno></docno>
+ <date>2007-10-06</date>
+ <rev>%VSN%</rev>
+ <file>book.sgml</file>
+ </header>
+ <insidecover>
+ </insidecover>
+ <pagetext>SSH</pagetext>
+ <preamble>
+ <contents level="2"></contents>
+ </preamble>
+ <applications>
+ <xi:include href="ref_man.xml"/>
+ </applications>
+ <releasenotes>
+ <xi:include href="notes.xml"/>
+ </releasenotes>
+ <listofterms></listofterms>
+ <index></index>
+</book>
+
diff --git a/lib/ssh/doc/src/fascicules.xml b/lib/ssh/doc/src/fascicules.xml
new file mode 100644
index 0000000000..43090b4aed
--- /dev/null
+++ b/lib/ssh/doc/src/fascicules.xml
@@ -0,0 +1,15 @@
+<?xml version="1.0" encoding="latin1" ?>
+<!DOCTYPE fascicules SYSTEM "fascicules.dtd">
+
+<fascicules>
+ <fascicule file="ref_man" href="ref_man_frame.html" entry="yes">
+ Reference Manual
+ </fascicule>
+ <fascicule file="part_notes" href="part_notes_frame.html" entry="no">
+ Release Notes
+ </fascicule>
+ <fascicule file="" href="../../../../doc/print.html" entry="no">
+ Off-Print
+ </fascicule>
+</fascicules>
+
diff --git a/lib/ssh/doc/src/make.dep b/lib/ssh/doc/src/make.dep
new file mode 100644
index 0000000000..cfe2f9617b
--- /dev/null
+++ b/lib/ssh/doc/src/make.dep
@@ -0,0 +1,19 @@
+# ----------------------------------------------------
+# >>>> Do not edit this file <<<<
+# This file was automaticly generated by
+# /home/otp/bin/docdepend
+# ----------------------------------------------------
+
+
+# ----------------------------------------------------
+# TeX files that the DVI file depend on
+# ----------------------------------------------------
+
+book.dvi: book.tex ref_man.tex ssh.tex ssh_channel.tex \
+ ssh_connection.tex ssh_sftp.tex ssh_sftpd.tex
+
+# ----------------------------------------------------
+# Source inlined when transforming from source to LaTeX
+# ----------------------------------------------------
+
+book.tex: ref_man.xml
diff --git a/lib/ssh/doc/src/notes.xml b/lib/ssh/doc/src/notes.xml
new file mode 100644
index 0000000000..54e0cf9059
--- /dev/null
+++ b/lib/ssh/doc/src/notes.xml
@@ -0,0 +1,588 @@
+<?xml version="1.0" encoding="latin1" ?>
+<!DOCTYPE chapter SYSTEM "chapter.dtd">
+
+<chapter>
+ <header>
+ <copyright>
+ <year>2004</year><year>2009</year>
+ <holder>Ericsson AB. All Rights Reserved.</holder>
+ </copyright>
+ <legalnotice>
+ The contents of this file are subject to the Erlang Public License,
+ Version 1.1, (the "License"); you may not use this file except in
+ compliance with the License. You should have received a copy of the
+ Erlang Public License along with this software. If not, it can be
+ retrieved online at http://www.erlang.org/.
+
+ Software distributed under the License is distributed on an "AS IS"
+ basis, WITHOUT WARRANTY OF ANY KIND, either express or implied. See
+ the License for the specific language governing rights and limitations
+ under the License.
+
+ </legalnotice>
+
+ <title>SSH Release Notes</title>
+ <prepared></prepared>
+ <docno></docno>
+ <date></date>
+ <rev>%VSN%</rev>
+ <file>notes.xml</file>
+ </header>
+
+ <section><title>Ssh 1.1.7</title>
+
+ <section><title>Fixed Bugs and Malfunctions</title>
+ <list>
+ <item>
+ <p>
+ Now clear all processes when a connnection is terminated.</p>
+ <p>
+ Own Id: OTP-8121 Aux Id:</p>
+ </item>
+ <item>
+ <p>
+ In some rare cases the connection handler could enter an infinite loop.</p>
+ <p>
+ Own Id: OTP-8277 Aux Id: seq11428</p>
+ </item>
+ <item>
+ <p>
+ If an SFTP server did not respond with EOF, the function
+ ssh_sftp:list_dir/2/3 would enter an infinite loop.</p>
+ <p>
+ Own Id: OTP-8278 Aux Id: seq11450</p>
+ </item>
+ </list>
+ </section>
+
+ <section><title>Improvements and New Features</title>
+ <list>
+ <item>
+ <p>
+ The documentation is now built with open source tools (xsltproc and fop)
+ that exists on most platforms. One visible change is that the frames are removed.</p>
+ <p>
+ Own Id: OTP-8201 Aux Id:</p>
+ </item>
+ </list>
+ </section>
+
+ </section>
+
+ <section><title>Ssh 1.1.6</title>
+
+ <section><title>Fixed Bugs and Malfunctions</title>
+ <list>
+ <item>
+ <p>
+ ssh_sftp:start_channel did not handle all possible return
+ values from ssh_channel:start correctly.
+ </p>
+ <p>
+ Own Id: OTP-8176 Aux Id: </p>
+ </item>
+ <item>
+ <p>
+ SFTPD did not handle rename command (version 4) correctly.
+ </p>
+ <p>
+ Own Id: OTP-8175 Aux Id: seq11373</p>
+ </item>
+ <item>
+ <p>
+ If a connection manager already had been terminated it could cause a channel
+ to generate a crash report when it was about to stop.
+ </p>
+ <p>
+ Own Id: OTP-8174 Aux Id: seq11377</p>
+ </item>
+ <item>
+ <p>
+ Requests could result in badarg or badmatch EXIT messages in the connection
+ manager if the channel no longer existed.</p>
+ <p>
+ Own Id: OTP-8173 Aux Id: seq11379</p>
+ </item>
+ <item>
+ <p>
+ ssh_transport:unpack/3 could cause a badarg error.</p>
+ <p>
+ Own Id: OTP-8162 Aux Id:</p>
+ </item>
+ </list>
+ </section>
+
+ <section><title>Improvements and New Features</title>
+ <list>
+ <item>
+ <p>
+ The encryption algorithm aes128-cbc is now supported.
+ Requires that crypto-1.6.1 is available.</p>
+ <p>
+ Own Id: OTP-8110 Aux Id:</p>
+ </item>
+ </list>
+ </section>
+
+ </section>
+
+
+ <section><title>Ssh 1.1.5</title>
+
+ <section><title>Fixed Bugs and Malfunctions</title>
+ <list>
+ <item>
+ <p>
+ ssh_sftp:start_channel/3 did not handle timout correctly.</p>
+ <p>
+ Own Id: OTP-8159 Aux Id: seq11386</p>
+ </item>
+ <item>
+ <p>
+ If a progress message was not recieved after invoking ssh:connect/3
+ the call could hang for ever. A timeout option has also been added.</p>
+ <p>
+ Own Id: OTP-8160 Aux Id: seq11386</p>
+ </item>
+ <item>
+ <p>
+ A comma has been missing in the ssh.appup file since SSH-1.0.2.</p>
+ <p>
+ Own Id: OTP-8161 Aux Id:</p>
+ </item>
+ </list>
+ </section>
+
+ </section>
+
+ <section><title>Ssh 1.1.4</title>
+
+ <section><title>Fixed Bugs and Malfunctions</title>
+ <list>
+ <item>
+ <p>
+ SSH sometimes caused a crash report at disconnect.</p>
+ <p>
+ Own Id: OTP-8071 Aux Id: seq11319</p>
+ </item>
+ </list>
+ </section>
+
+ </section>
+
+ <section><title>Ssh 1.1.3</title>
+
+ <section><title>Fixed Bugs and Malfunctions</title>
+ <list>
+ <item>
+ <p>
+ The operation ssh_sftp:stop_channel/1 returned an
+ exception if the connection already had been closed.</p>
+ <p>
+ Own Id: OTP-7996 Aux Id: seq11281</p>
+ </item>
+ <item>
+ <p>
+ SSH did not handle if supervisor:start_child/2 returned
+ {error, already_present}.</p>
+ <p>
+ Own Id: OTP-8034 Aux Id: seq11307</p>
+ </item>
+ <item>
+ <p>
+ SSH no longer cause supervisor reports when a connection is
+ terminated in a controlled manner.</p>
+ <p>
+ Own Id: OTP-8035 Aux Id: seq11308</p>
+ </item>
+ </list>
+ </section>
+
+ </section>
+
+ <section><title>Ssh 1.1.2</title>
+
+ <section><title>Fixed Bugs and Malfunctions</title>
+ <list>
+ <item>
+ <p>
+ Ssh confused local and remote channel id's, which in some
+ cases resulted in that messages were discarded.</p>
+ <p>
+ Own Id: OTP-7914 Aux Id: seq11234</p>
+ </item>
+ <item>
+ <p>
+ Ssh could not handle echo values other than 0 and 1.</p>
+ <p>
+ Own Id: OTP-7917 Aux Id: seq11238</p>
+ </item>
+ <item>
+ <p>
+ A crash occurred if a non-valid channel reference was received.</p>
+ <p>
+ Own Id: OTP-7918 Aux Id: seq11238</p>
+ </item>
+ <item>
+ <p>
+ Sftpd connections was not closed after receiving eof from a client.</p>
+ <p>
+ Own Id: OTP-7921 Aux Id: seq11222</p>
+ </item>
+ <item>
+ <p>
+ It was not possible to start a SFTP subsystem on certain platforms,
+ i.e. those who do not support symbolic links.</p>
+ <p>
+ Own Id: OTP-7930 Aux Id: </p>
+ </item>
+ <item>
+ <p>
+ In some cases the message {ssh_cm, ssh_connection_ref(), {closed, ssh_channel_id()}}
+ was not passed to the registered callback module.</p>
+ <p>
+ Own Id: OTP-7957 Aux Id: </p>
+ </item>
+ </list>
+ </section>
+
+ <section><title>Improvements and New Features</title>
+ <list>
+ <item>
+ <p>
+ By using the sftpd option {max_files, Integer}, the message
+ size for READDIR commands can be reduced.</p>
+ <p>
+ Own Id: OTP-7919 Aux Id: seq11230</p>
+ </item>
+ </list>
+ </section>
+
+ </section>
+
+ <section><title>Ssh 1.1.1</title>
+
+ <section><title>Fixed Bugs and Malfunctions</title>
+ <list>
+ <item>
+ <p>
+ The erlang ssh server has presented itself incorrectly,
+ using the special version ssh-1.99, although it never has
+ supported versions below 2.0. Since ssh-1.1 client
+ versions below 2.0 are correctly rejected instead of
+ letting the server crash later on. Alas the problem with
+ the presentation string was not discovered until after
+ ssh.1.1 was released. Now the server will present itself
+ as ssh-2.0.</p>
+ <p>
+ Own Id: OTP-7795</p>
+ </item>
+ <item>
+ <p>
+ An internal function call used an incorrect parameter, which
+ caused problem when the old listen API was used. This was
+ introduced in Ssh-1.1.</p>
+ <p>
+ Own Id: OTP-7920 Aux Id: seq11211</p>
+ </item>
+ </list>
+ </section>
+
+ <section><title>Improvements and New Features</title>
+ <list>
+ <item>
+ <p>
+ Ssh timeouts will now behave as expected e.i. defaults to
+ infinity only the user of the ssh application can know of
+ a reasonable timeout value for their application.</p>
+ <p>
+ *** POTENTIAL INCOMPATIBILITY ***</p>
+ <p>
+ Own Id: OTP-7807</p>
+ </item>
+ <item>
+ <p>
+ The implementation of timeouts added as a patch in
+ ssh-1.0.1 was slightly changed and is now documented.</p>
+ <p>
+ Own Id: OTP-7808</p>
+ </item>
+ <item>
+ <p>
+ To honor the multiplexing of channels over one ssh
+ connection concept ssh_sftp:connect/ [1,2,3] is
+ deprecated and replaced by ssh_sftp:start_channel/[1,2,3]
+ and ssh_sftp:stop/1 is deprecated and replaced by
+ ssh_sftp:stop_channel/1 and to stop the ssh connection
+ ssh:close/ 1 should be called.</p>
+ <p>
+ Own Id: OTP-7809</p>
+ </item>
+ <item>
+ <p>
+ Added the message {ssh_channel_up, ChannelId,
+ ConnectionManager} that shall be handled by the channel
+ callback handle_msg/2. This makes the function
+ handle_msg/2 a mandatory function for ssh channels
+ implementations which it was not in ssh-1.1.</p>
+ <p>
+ *** POTENTIAL INCOMPATIBILITY ***</p>
+ <p>
+ Own Id: OTP-7828</p>
+ </item>
+ </list>
+ </section>
+
+ </section>
+
+ <section><title>Ssh 1.1</title>
+
+ <section><title>Fixed Bugs and Malfunctions</title>
+ <list>
+ <item>
+ <p>
+ A flaw in the implementation of the supervision tree
+ caused the ssh daemon to close the connections to all
+ currently logged in users if one user logged out. Another
+ problem related to the supervision tree caused the closing
+ down of clients to leak processes e.i. all processes was
+ not shutdown correctly.</p>
+ <p>
+ Own Id: OTP-7676</p>
+ </item>
+ <item>
+ <p>
+ Tabs could cause ssh_cli to print things in a surprising
+ way.</p>
+ <p>
+ Own Id: OTP-7683 Aux Id: seq11102 </p>
+ </item>
+ <item>
+ <p>
+ [sftp, sftpd] - Added patch to make sftp timestamps more
+ correct, in the long run it would be nice to have better
+ support in file to be able to make it always behave
+ correctly now it will be correct 99 % of time instead of
+ almost never correct, at least on unix-based platforms.</p>
+ <p>
+ Own Id: OTP-7685 Aux Id: seq11082 </p>
+ </item>
+ <item>
+ <p>
+ [sftpd] - Added patch to further improve handling of
+ symbolic links in the sftp-server.</p>
+ <p>
+ Own Id: OTP-7766 Aux Id: seq11101 </p>
+ </item>
+ <item>
+ <p>
+ Ssh incorrectly sent the local id instead of the remote
+ id of a channel to the peer. For simpler cases these ids
+ often happen to have the same value. One case when they
+ do not is when the client sends an exec command two times
+ in a raw on the same ssh connection (different channels
+ of course as the channel will be closed when the exec
+ command has been evaluated) .</p>
+ <p>
+ Own Id: OTP-7767</p>
+ </item>
+ <item>
+ <p>
+ Packet data could be lost under high load due to the fact
+ that buffered data was sometimes wrongly discarded before
+ it had been sent.</p>
+ <p>
+ Own Id: OTP-7768</p>
+ </item>
+ <item>
+ <p>
+ Improved ipv6-handling as some assumptions about inet
+ functions where incorrect.</p>
+ <p>
+ Own Id: OTP-7770</p>
+ </item>
+ </list>
+ </section>
+
+
+ <section><title>Improvements and New Features</title>
+ <list>
+ <item>
+ <p>
+ Added new API function ssh:connection_info/2.</p>
+ <p>
+ Own Id: OTP-7456</p>
+ </item>
+ <item>
+ <p>
+ Now starts ssh channel processes later avoiding
+ synchronization problems between processes.</p>
+ <p>
+ Own Id: OTP-7516</p>
+ </item>
+ <item>
+ <p>
+ Ssh now rejects old versions of the ssh protocol for
+ security reasons. (Even if they where not correctly
+ rejected before the connection would probably have failed
+ anyway due to other reasons.)</p>
+ <p>
+ Own Id: OTP-7645 Aux Id: seq11094 </p>
+ </item>
+ <item>
+ <p>
+ New API module ssh_channel has been added. This is a
+ behaviour to facilitate the implementation of ssh clients
+ and plug in subsystems to the ssh daemon. Note that this
+ slightly changes the options to the API function
+ ssh:daemon/[1,2,3] deprecating all no longer documented
+ options. Note that the new API enforces the "logical way"
+ of using the old API e.i. making the subsystem process
+ part of the ssh applications supervisor tree, so missuses
+ of the old API are not compatible with the new API.</p>
+ <p>
+ *** POTENTIAL INCOMPATIBILITY ***</p>
+ <p>
+ Own Id: OTP-7769</p>
+ </item>
+ </list>
+ </section>
+
+ <section><title>Known Bugs and Problems</title>
+ <list>
+ <item>
+ <p>
+ Public keys protected by a password are currently not
+ handled by the erlang ssh application.</p>
+ <p>
+ Own Id: OTP-6400 Aux Id: 10595 </p>
+ </item>
+ </list>
+ </section>
+
+ </section>
+
+ <section><title>Ssh 1.0.2</title>
+
+ <section><title>Fixed Bugs and Malfunctions</title>
+ <list>
+ <item>
+ <p>
+ [sftpd] - Listing of symbolic link directories should now
+ work as expected.</p>
+ <p>
+ Own Id: OTP-7141 Aux Id: seq10856 </p>
+ </item>
+ </list>
+ </section>
+
+ </section>
+
+ <section><title>Ssh 1.0.1</title>
+
+ <section><title>Fixed Bugs and Malfunctions</title>
+ <list>
+ <item>
+ <p>
+ [sftp] - When listing a directory with more than 100
+ files only the first 100 where listed. This has now been
+ fixed.</p>
+ <p>
+ Own Id: OTP-7318 Aux Id: seq10953 </p>
+ </item>
+ <item>
+ <p>
+ When restarting an ssh-system the expected return value
+ from ssh_system_sup:restart_acceptor/2 was incorrect,
+ this is no longer the case.</p>
+ <p>
+ Own Id: OTP-7564 Aux Id: seq11055 </p>
+ </item>
+ <item>
+ <p>
+ A few minor bugs where fixed in ssh_userreg.erl and
+ ssh_connection_manager and a a ssh_cli option was added
+ to restore backwards compatibility with the old ssh_cm -
+ API.</p>
+ <p>
+ Own Id: OTP-7565</p>
+ </item>
+ <item>
+ <p>
+ Fixed bug in ipv6 support and added option to disable
+ ipv6 as a workaround for badly configured computers.</p>
+ <p>
+ Own Id: OTP-7566</p>
+ </item>
+ </list>
+ </section>
+
+ <section><title>Improvements and New Features</title>
+ <list>
+ <item>
+ <p>
+ [sftp] - Option added to set timeout value in sftp.</p>
+ <p>
+ Own Id: OTP-7305 Aux Id: seq10945 </p>
+ </item>
+ </list>
+ </section>
+
+ </section>
+
+ <section><title>Ssh 1.0</title>
+
+ <section><title>Fixed Bugs and Malfunctions</title>
+ <list>
+ <item>
+ <p>
+ Removed some special handling of prompts that made ssh
+ behave differently than openssh.</p>
+ <p>
+ Own Id: OTP-7485 Aux Id: seq11025 </p>
+ </item>
+ <item>
+ <p>
+ Bug in encoding of pty opts has been fixed.</p>
+ <p>
+ Own Id: OTP-7504</p>
+ </item>
+ </list>
+ </section>
+
+
+ <section><title>Improvements and New Features</title>
+ <list>
+ <item>
+ <p>
+ The architecture of the ssh processes has been
+ reconstructed to fit in a supervision tree as to become a
+ real OTP application and benefit from this when starting
+ and stopping.</p>
+ <p>
+ Own Id: OTP-7356 Aux Id: seq10899 </p>
+ </item>
+ <item>
+ <p>
+ Support for pty option echo off added. Requires kernel
+ from R12B-4.</p>
+ <p>
+ *** POTENTIAL INCOMPATIBILITY ***</p>
+ <p>
+ Own Id: OTP-7502 Aux Id: seq10959 </p>
+ </item>
+ <item>
+ <p>
+ The ssh API has been enhanced a lot of old API functions
+ has become deprecated.</p>
+ <p>
+ Own Id: OTP-7503</p>
+ </item>
+ </list>
+ </section>
+
+ <!-- p>For information about older versions see
+ <url href="part_notes_history_frame.html">release notes history</url>.</p -->
+ </section>
+</chapter>
+
diff --git a/lib/ssh/doc/src/notes_history.xml b/lib/ssh/doc/src/notes_history.xml
new file mode 100644
index 0000000000..bfebcd4bf4
--- /dev/null
+++ b/lib/ssh/doc/src/notes_history.xml
@@ -0,0 +1,737 @@
+<?xml version="1.0" encoding="latin1" ?>
+<!DOCTYPE chapter SYSTEM "chapter.dtd">
+
+<chapter>
+ <header>
+ <copyright>
+ <year>2009</year>
+ <year>2009</year>
+ <holder>Ericsson AB, All Rights Reserved</holder>
+ </copyright>
+ <legalnotice>
+ The contents of this file are subject to the Erlang Public License,
+ Version 1.1, (the "License"); you may not use this file except in
+ compliance with the License. You should have received a copy of the
+ Erlang Public License along with this software. If not, it can be
+ retrieved online at http://www.erlang.org/.
+
+ Software distributed under the License is distributed on an "AS IS"
+ basis, WITHOUT WARRANTY OF ANY KIND, either express or implied. See
+ the License for the specific language governing rights and limitations
+ under the License.
+
+ The Initial Developer of the Original Code is Ericsson AB.
+ </legalnotice>
+
+ <title>SSH Release Notes History</title>
+ <prepared></prepared>
+ <responsible></responsible>
+ <docno></docno>
+ <approved></approved>
+ <checked></checked>
+ <date></date>
+ <rev>A</rev>
+ <file>notes_history.xml</file>
+ </header>
+
+ <section><title>Ssh 0.9.9.6</title>
+
+ <section><title>Improvements and New Features</title>
+ <list>
+ <item>
+ <p>
+ Updated asn1 file due to change in the asn1 compiler.
+ This has no semantical effect on the ssh application.</p>
+ <p>
+ Own Id: OTP-7246</p>
+ </item>
+ <item>
+ <p>
+ Allows for the option {fd, FD} in listen and connect
+ calls. The option is passed on to gen_tcp:listen and
+ gen_tcp:connect</p>
+ <p>
+ Own Id: OTP-7247</p>
+ </item>
+ </list>
+ </section>
+</section>
+
+ <section><title>Ssh 0.9.9.5</title>
+
+ <section><title>Fixed Bugs and Malfunctions</title>
+ <list>
+ <item>
+ <p>
+ Putty version 0.60 sends ignore messages, which hanged
+ the OTP ssh server.</p>
+ <p>
+ Own Id: OTP-7076</p>
+ </item>
+ <item>
+ <p>
+ ssh_cm hanged when connection was closed during
+ handshake. (Triggered by putty 0.60 client.)</p>
+ <p>
+ Own Id: OTP-7089</p>
+ </item>
+ <item>
+ <p>
+ Fixed crash in server when receiving an empty ignore-msg.
+ (From the putty 0.60 client.)</p>
+ <p>
+ Own Id: OTP-7135</p>
+ </item>
+ </list>
+ </section>
+
+
+ <section><title>Improvements and New Features</title>
+ <list>
+ <item>
+ <p>
+ Now uses the base 64 encode/decode function in stdlib.</p>
+ <p>
+ Own Id: OTP-6486</p>
+ </item>
+ <item>
+ <p>
+ Removed runtime dependency on asn1.</p>
+ <p>
+ Own Id: OTP-6570</p>
+ </item>
+ <item>
+ <p>
+ Documentation update of ssh.</p>
+ <p>
+ Own Id: OTP-7063 Aux Id: seq10789 </p>
+ </item>
+ <item>
+ <p>
+ Same listener is used for both sshd and sftpd. Previously
+ the sftpd server had to be run on a separate port, now
+ the sshd listener will start an sftpd server when an sftp
+ client connects.</p>
+ <p>
+ Own Id: OTP-7090 Aux Id: seq10675 </p>
+ </item>
+ <item>
+ <p>
+ Kebord-interactive support, according to rfc 4256, has
+ been added to the ssh client. Also the option
+ <c>quiet_mode</c> has been added so that unwanted banners
+ may be suppressed.</p>
+ <p>
+ Own Id: OTP-7106 Aux Id: seq10841 </p>
+ </item>
+ </list>
+ </section>
+
+ </section>
+
+ <section><title>Ssh 0.9.9.4</title>
+
+ <section><title>Improvements and New Features</title>
+ <list>
+ <item>
+ <p>
+ [sftpd] - Root parameter now behaves as expected,
+ instead of making sftpd malfunction.</p>
+ <p>
+ Own Id: OTP-7057 Aux Id: seq10830 </p>
+ </item>
+ </list>
+ </section>
+ </section>
+
+ <section><title>Ssh 0.9.9.3</title>
+
+ <section><title>Fixed Bugs and Malfunctions</title>
+ <list>
+ <item>
+ <p>
+ The sftp-server could crash if a "ls" was done on the
+ client, and a file was removed while ssh_sftpd:list_dir
+ was reading the directory, an error code from
+ read_file_info wasn't handled properly. This fix makes ls
+ return an error code instead.</p>
+ <p>
+ Own Id: OTP-6854 Aux Id: seq10740 </p>
+ </item>
+ <item>
+ <p>
+ Fixed bugs in prompting in ssl_cli. Prompts like \003>
+ were written as \300>. Also, newlines and returns was
+ removed.</p>
+ <p>
+ Own Id: OTP-6917 Aux Id: seq10773 </p>
+ </item>
+ </list>
+ </section>
+
+ <section><title>Improvements and New Features</title>
+ <list>
+ <item>
+ <p>
+ [sftpd] - New option "root" to set the root of the
+ sftp-server and the callback module for file handling now
+ has a state parameter.</p>
+ <p>
+ Own Id: OTP-7075 Aux Id: seq10675 </p>
+ </item>
+ </list>
+ </section>
+ </section>
+
+ <section>
+ <title>Ssh 0.9.9.2</title>
+ <section>
+ <title>Better error-handling in ssh_sshd:listen</title>
+ <list type="bulleted">
+ <item>
+ <p>The caller was hanged when listening with ssh_sshd:listen
+ (or ssh_sftpd:listen) on a port and IP already in use.
+ Now an error is returned instead.</p>
+ <p>Own Id: OTP-6727</p>
+ </item>
+ </list>
+ </section>
+
+ <section>
+ <title>Fix in ssh_sftpd</title>
+ <list type="bulleted">
+ <item>
+ <p>Cd ../.. didn't work when connecting to a ssh_sftpd server.</p>
+ <p>Own Id: OTP-6727</p>
+ </item>
+ </list>
+ </section>
+ </section>
+
+ <section>
+ <title>Ssh 0.9.9.1</title>
+
+ <section>
+ <title>Minor Makefile changes</title>
+ <list type="bulleted">
+ <item>
+ <p>Removed use of <c><![CDATA[erl_flags]]></c> from Makefile.</p>
+ <p>Own Id: OTP-6689</p>
+ </item>
+ </list>
+ </section>
+ </section>
+
+ <section>
+ <title>Ssh 0.9.9</title>
+
+ <section>
+ <title>Fixed Bugs and Malfunctions</title>
+ <list type="bulleted">
+ <item>
+ <p>A race condition that could make the server crash if a
+ client sent a SSH_MSG_USERAUTH_REQUEST packet immediately
+ after its SSH_MSG_SERVICE_REQUEST, is removed.</p>
+ <p>Own Id: OTP-6379 Aux Id: seq10523 </p>
+ </item>
+ </list>
+ </section>
+ </section>
+
+ <section>
+ <title>Ssh 0.9.8</title>
+
+ <section>
+ <title>Fixed Bugs and Malfunctions</title>
+ <list type="bulleted">
+ <item>
+ <p>Corrected minor bugs and removed dead code found by
+ dialyzer.</p>
+ <p>Own Id: OTP-6524</p>
+ </item>
+ </list>
+ </section>
+ </section>
+
+ <section>
+ <title>Ssh 0.9.7</title>
+
+ <section>
+ <title>Fixed Bugs and Malfunctions</title>
+ <list type="bulleted">
+ <item>
+ <p>[sftp] - The function ssh_sftp:make_symlink/3 was not
+ fully implemented.</p>
+ <p>Own Id: OTP-6446</p>
+ </item>
+ <item>
+ <p>[ssh] - An internal value was, due to a bug, always set
+ to undefined even when it was not, this could lead to
+ connections being wrongly refused.</p>
+ <p>Own Id: OTP-6450</p>
+ </item>
+ <item>
+ <p>A pattern matching was missing "/binary" resulting in
+ that the internal function ssh_xfer:decode_acl/2 did not
+ work as expected.</p>
+ <p>Own Id: OTP-6458</p>
+ </item>
+ <item>
+ <p>[sftp] - read_link/2 did not return the documented value</p>
+ <p>Own Id: OTP-6471</p>
+ </item>
+ <item>
+ <p>Removed debugg printouts from ssh_cli.erl</p>
+ <p>Own Id: OTP-6483</p>
+ </item>
+ <item>
+ <p>[sftp, ssh] - The connection timeout was overridden by an
+ internal gen_server default timeout.</p>
+ <p>Own Id: OTP-6488 Aux Id: seq10569 </p>
+ </item>
+ </list>
+ </section>
+ </section>
+
+ <section>
+ <title>Ssh 0.9.6</title>
+
+ <section>
+ <title>Fixed Bugs and Malfunctions</title>
+ <list type="bulleted">
+ <item>
+ <p>Removed debug printout from production code.</p>
+ <p>Own Id: OTP-6348 Aux Id: seq10510 </p>
+ </item>
+ <item>
+ <p>[sftpd] - When the sftp client ends the session the
+ server will now behave correctly and not leave the client
+ hanging.</p>
+ <p>Own Id: OTP-6349 Aux Id: seq10510 </p>
+ </item>
+ <item>
+ <p>[sftpd] - No longer used files were not closed until the
+ session was ended.</p>
+ <p>Own Id: OTP-6350 Aux Id: seq10514 </p>
+ </item>
+ <item>
+ <p>[sftpd] - File rename requests sent by sftp version 3
+ clients were not handled.</p>
+ <p>Own Id: OTP-6352 Aux Id: seq10513 </p>
+ </item>
+ <item>
+ <p>[sftpd] - Request that did not fit into one ssh message
+ were not handled.</p>
+ <p>Own Id: OTP-6353 Aux Id: seq10515 </p>
+ </item>
+ <item>
+ <p>Removed error logging of auth method none, as this is not
+ an error but rather a feature, that is used to get
+ initial information from the server.</p>
+ <p>Own Id: OTP-6414</p>
+ </item>
+ </list>
+ </section>
+
+ <section>
+ <title>Improvements and New Features</title>
+ <list type="bulleted">
+ <item>
+ <p>[sftpd] - Added new option to specify a callback module
+ for the sftpd-server file handling. The default callback
+ module uses file and filelib.</p>
+ <p>Own Id: OTP-6356 Aux Id: seq10519 </p>
+ </item>
+ </list>
+ </section>
+ </section>
+
+ <section>
+ <title>Ssh 0.9.5</title>
+
+ <section>
+ <title>Fixed Bugs and Malfunctions</title>
+ <list type="bulleted">
+ <item>
+ <p>The data window in SSH wasn't resized in the ssh_cli
+ receive data, this made the ssh_cli-server hang if more
+ than 64K data was received at one time. The option
+ tcp_nodelay was added, for nodelay in tcp connections.</p>
+ <p>Own Id: OTP-6231</p>
+ </item>
+ </list>
+ </section>
+ </section>
+
+ <section>
+ <title>SSH 0.9.4</title>
+
+ <section>
+ <title>Reported Fixed Bugs and Malfunctions</title>
+ <list type="bulleted">
+ <item>
+ <p>Unnecessary explicit start of crypto application
+ in ssh application. This has been removed. The
+ app-file specifies that ssh depends on the crypto app.
+ This is enough. See also the
+ <seealso marker="ssh">ssh</seealso> module.</p>
+ <p>Also changed some error reports to info reports.</p>
+ <p>Own Id: OTP-6183</p>
+ <p>Aux Id: Seq 10383</p>
+ </item>
+ </list>
+ </section>
+ </section>
+
+ <section>
+ <title>SSH 0.9.3</title>
+
+ <section>
+ <title>Improvements and New Features</title>
+ <list type="bulleted">
+ <item>
+ <p>Added way for cli to get peer name</p>
+ <p>Own Id: OTP-6138</p>
+ </item>
+ </list>
+ </section>
+ </section>
+
+ <section>
+ <title>SSH 0.9.2</title>
+
+ <section>
+ <title>Improvements and New Features</title>
+ <list type="bulleted">
+ <item>
+ <p>Added some options to listen</p>
+ <p>Own Id: OTP-6070</p>
+ </item>
+ </list>
+ </section>
+ </section>
+
+ <section>
+ <title>SSH 0.9.1</title>
+ <section><title>Ssh 0.9.9.4</title>
+
+ <section><title>Improvements and New Features</title>
+ <list>
+ <item>
+ <p>
+ [sftpd] - Root parameter now behaves as expected,
+ instead of making sftpd malfunction.</p>
+ <p>
+ Own Id: OTP-7057 Aux Id: seq10830 </p>
+ </item>
+ </list>
+ </section>
+ </section>
+
+ <section><title>Ssh 0.9.9.3</title>
+
+ <section><title>Fixed Bugs and Malfunctions</title>
+ <list>
+ <item>
+ <p>
+ The sftp-server could crash if a "ls" was done on the
+ client, and a file was removed while ssh_sftpd:list_dir
+ was reading the directory, an error code from
+ read_file_info wasn't handled properly. This fix makes ls
+ return an error code instead.</p>
+ <p>
+ Own Id: OTP-6854 Aux Id: seq10740 </p>
+ </item>
+ <item>
+ <p>
+ Fixed bugs in prompting in ssl_cli. Prompts like \003>
+ were written as \300>. Also, newlines and returns was
+ removed.</p>
+ <p>
+ Own Id: OTP-6917 Aux Id: seq10773 </p>
+ </item>
+ </list>
+ </section>
+
+ <section><title>Improvements and New Features</title>
+ <list>
+ <item>
+ <p>
+ [sftpd] - New option "root" to set the root of the
+ sftp-server and the callback module for file handling now
+ has a state parameter.</p>
+ <p>
+ Own Id: OTP-7075 Aux Id: seq10675 </p>
+ </item>
+ </list>
+ </section>
+ </section>
+
+ <section>
+ <title>Ssh 0.9.9.2</title>
+ <section>
+ <title>Better error-handling in ssh_sshd:listen</title>
+ <list type="bulleted">
+ <item>
+ <p>The caller was hanged when listening with ssh_sshd:listen
+ (or ssh_sftpd:listen) on a port and IP already in use.
+ Now an error is returned instead.</p>
+ <p>Own Id: OTP-6727</p>
+ </item>
+ </list>
+ </section>
+
+ <section>
+ <title>Fix in ssh_sftpd</title>
+ <list type="bulleted">
+ <item>
+ <p>Cd ../.. didn't work when connecting to a ssh_sftpd server.</p>
+ <p>Own Id: OTP-6727</p>
+ </item>
+ </list>
+ </section>
+ </section>
+
+ <section>
+ <title>Ssh 0.9.9.1</title>
+
+ <section>
+ <title>Minor Makefile changes</title>
+ <list type="bulleted">
+ <item>
+ <p>Removed use of <c><![CDATA[erl_flags]]></c> from Makefile.</p>
+ <p>Own Id: OTP-6689</p>
+ </item>
+ </list>
+ </section>
+ </section>
+
+ <section>
+ <title>Ssh 0.9.9</title>
+
+ <section>
+ <title>Fixed Bugs and Malfunctions</title>
+ <list type="bulleted">
+ <item>
+ <p>A race condition that could make the server crash if a
+ client sent a SSH_MSG_USERAUTH_REQUEST packet immediately
+ after its SSH_MSG_SERVICE_REQUEST, is removed.</p>
+ <p>Own Id: OTP-6379 Aux Id: seq10523 </p>
+ </item>
+ </list>
+ </section>
+ </section>
+
+ <section>
+ <title>Ssh 0.9.8</title>
+
+ <section>
+ <title>Fixed Bugs and Malfunctions</title>
+ <list type="bulleted">
+ <item>
+ <p>Corrected minor bugs and removed dead code found by
+ dialyzer.</p>
+ <p>Own Id: OTP-6524</p>
+ </item>
+ </list>
+ </section>
+ </section>
+
+ <section>
+ <title>Ssh 0.9.7</title>
+
+ <section>
+ <title>Fixed Bugs and Malfunctions</title>
+ <list type="bulleted">
+ <item>
+ <p>[sftp] - The function ssh_sftp:make_symlink/3 was not
+ fully implemented.</p>
+ <p>Own Id: OTP-6446</p>
+ </item>
+ <item>
+ <p>[ssh] - An internal value was, due to a bug, always set
+ to undefined even when it was not, this could lead to
+ connections being wrongly refused.</p>
+ <p>Own Id: OTP-6450</p>
+ </item>
+ <item>
+ <p>A pattern matching was missing "/binary" resulting in
+ that the internal function ssh_xfer:decode_acl/2 did not
+ work as expected.</p>
+ <p>Own Id: OTP-6458</p>
+ </item>
+ <item>
+ <p>[sftp] - read_link/2 did not return the documented value</p>
+ <p>Own Id: OTP-6471</p>
+ </item>
+ <item>
+ <p>Removed debugg printouts from ssh_cli.erl</p>
+ <p>Own Id: OTP-6483</p>
+ </item>
+ <item>
+ <p>[sftp, ssh] - The connection timeout was overridden by an
+ internal gen_server default timeout.</p>
+ <p>Own Id: OTP-6488 Aux Id: seq10569 </p>
+ </item>
+ </list>
+ </section>
+ </section>
+
+ <section>
+ <title>Ssh 0.9.6</title>
+
+ <section>
+ <title>Fixed Bugs and Malfunctions</title>
+ <list type="bulleted">
+ <item>
+ <p>Removed debug printout from production code.</p>
+ <p>Own Id: OTP-6348 Aux Id: seq10510 </p>
+ </item>
+ <item>
+ <p>[sftpd] - When the sftp client ends the session the
+ server will now behave correctly and not leave the client
+ hanging.</p>
+ <p>Own Id: OTP-6349 Aux Id: seq10510 </p>
+ </item>
+ <item>
+ <p>[sftpd] - No longer used files were not closed until the
+ session was ended.</p>
+ <p>Own Id: OTP-6350 Aux Id: seq10514 </p>
+ </item>
+ <item>
+ <p>[sftpd] - File rename requests sent by sftp version 3
+ clients were not handled.</p>
+ <p>Own Id: OTP-6352 Aux Id: seq10513 </p>
+ </item>
+ <item>
+ <p>[sftpd] - Request that did not fit into one ssh message
+ were not handled.</p>
+ <p>Own Id: OTP-6353 Aux Id: seq10515 </p>
+ </item>
+ <item>
+ <p>Removed error logging of auth method none, as this is not
+ an error but rather a feature, that is used to get
+ initial information from the server.</p>
+ <p>Own Id: OTP-6414</p>
+ </item>
+ </list>
+ </section>
+
+ <section>
+ <title>Improvements and New Features</title>
+ <list type="bulleted">
+ <item>
+ <p>[sftpd] - Added new option to specify a callback module
+ for the sftpd-server file handling. The default callback
+ module uses file and filelib.</p>
+ <p>Own Id: OTP-6356 Aux Id: seq10519 </p>
+ </item>
+ </list>
+ </section>
+ </section>
+
+ <section>
+ <title>Ssh 0.9.5</title>
+
+ <section>
+ <title>Fixed Bugs and Malfunctions</title>
+ <list type="bulleted">
+ <item>
+ <p>The data window in SSH wasn't resized in the ssh_cli
+ receive data, this made the ssh_cli-server hang if more
+ than 64K data was received at one time. The option
+ tcp_nodelay was added, for nodelay in tcp connections.</p>
+ <p>Own Id: OTP-6231</p>
+ </item>
+ </list>
+ </section>
+ </section>
+
+ <section>
+ <title>SSH 0.9.4</title>
+
+ <section>
+ <title>Reported Fixed Bugs and Malfunctions</title>
+ <list type="bulleted">
+ <item>
+ <p>Unnecessary explicit start of crypto application
+ in ssh application. This has been removed. The
+ app-file specifies that ssh depends on the crypto app.
+ This is enough. See also the
+ <seealso marker="ssh">ssh</seealso> module.</p>
+ <p>Also changed some error reports to info reports.</p>
+ <p>Own Id: OTP-6183</p>
+ <p>Aux Id: Seq 10383</p>
+ </item>
+ </list>
+ </section>
+ </section>
+
+ <section>
+ <title>SSH 0.9.3</title>
+
+ <section>
+ <title>Improvements and New Features</title>
+ <list type="bulleted">
+ <item>
+ <p>Added way for cli to get peer name</p>
+ <p>Own Id: OTP-6138</p>
+ </item>
+ </list>
+ </section>
+ </section>
+
+ <section>
+ <title>SSH 0.9.2</title>
+
+ <section>
+ <title>Improvements and New Features</title>
+ <list type="bulleted">
+ <item>
+ <p>Added some options to listen</p>
+ <p>Own Id: OTP-6070</p>
+ </item>
+ </list>
+ </section>
+ </section>
+
+ <section>
+ <title>SSH 0.9.1</title>
+
+ <section>
+ <title>Improvements and New Features</title>
+ <list type="bulleted">
+ <item>
+ <p>Fixes in ssh_sftp, changes of timeout handling,
+ expand_fun moved to io:setopts</p>
+ <p>Own Id: OTP-5877 Aux Id: OTP-5781 </p>
+ </item>
+ </list>
+ </section>
+ </section>
+
+ <section>
+ <title>SSH 0.9</title>
+
+ <section>
+ <title>Improvements and New Features</title>
+ <list type="bulleted">
+ <item>
+ <p>The previously undocumented and UNSUPPORTED <c><![CDATA[ssh]]></c>
+ application has been updated and documented. This release
+ of the <c><![CDATA[ssh]]></c> application is still considered to be a
+ beta release and (if necessary) there could still be
+ changes in its API before it reaches 1.0.</p>
+ <p>Also, more cryptographic algorithms have been added to
+ the <c><![CDATA[crypto]]></c> application.</p>
+ <p>*** POTENTIAL INCOMPATIBILITY ***</p>
+ <p>Own Id: OTP-5631</p>
+ </item>
+ </list>
+ </section>
+ </section>
+ </section>
+
+</chapter>
+
+
diff --git a/lib/ssh/doc/src/part_notes.xml b/lib/ssh/doc/src/part_notes.xml
new file mode 100644
index 0000000000..f87efffe5c
--- /dev/null
+++ b/lib/ssh/doc/src/part_notes.xml
@@ -0,0 +1,38 @@
+<?xml version="1.0" encoding="latin1" ?>
+<!DOCTYPE part SYSTEM "part.dtd">
+
+<part xmlns:xi="http://www.w3.org/2001/XInclude">
+ <header>
+ <copyright>
+ <year>2004</year><year>2009</year>
+ <holder>Ericsson AB. All Rights Reserved.</holder>
+ </copyright>
+ <legalnotice>
+ The contents of this file are subject to the Erlang Public License,
+ Version 1.1, (the "License"); you may not use this file except in
+ compliance with the License. You should have received a copy of the
+ Erlang Public License along with this software. If not, it can be
+ retrieved online at http://www.erlang.org/.
+
+ Software distributed under the License is distributed on an "AS IS"
+ basis, WITHOUT WARRANTY OF ANY KIND, either express or implied. See
+ the License for the specific language governing rights and limitations
+ under the License.
+
+ </legalnotice>
+
+ <title>SSH Release Notes</title>
+ <prepared>Jakob Cederlund</prepared>
+ <docno></docno>
+ <date></date>
+ <rev>%VSN%</rev>
+ <file>part_notes.sgml</file>
+ </header>
+ <description>
+ <p>This document describes the changes made to the SSH application.
+ </p>
+ <p>For information about older versions see
+ <url href="part_notes_history_frame.html">release notes history</url>.</p> </description>
+ <xi:include file="notes.xml"/>
+</part>
+
diff --git a/lib/ssh/doc/src/part_notes_history.xml b/lib/ssh/doc/src/part_notes_history.xml
new file mode 100644
index 0000000000..49f72fd3db
--- /dev/null
+++ b/lib/ssh/doc/src/part_notes_history.xml
@@ -0,0 +1,36 @@
+<?xml version="1.0" encoding="latin1" ?>
+<!DOCTYPE part SYSTEM "part.dtd">
+
+<part>
+ <header>
+ <copyright>
+ <year>2004</year>
+ <year>2007</year>
+ <holder>Ericsson AB, All Rights Reserved</holder>
+ </copyright>
+ <legalnotice>
+ The contents of this file are subject to the Erlang Public License,
+ Version 1.1, (the "License"); you may not use this file except in
+ compliance with the License. You should have received a copy of the
+ Erlang Public License along with this software. If not, it can be
+ retrieved online at http://www.erlang.org/.
+
+ Software distributed under the License is distributed on an "AS IS"
+ basis, WITHOUT WARRANTY OF ANY KIND, either express or implied. See
+ the License for the specific language governing rights and limitations
+ under the License.
+
+ The Initial Developer of the Original Code is Ericsson AB.
+ </legalnotice>
+
+ <title>Ssh</title>
+ <prepared>Ingela Anderton Andin</prepared>
+ <docno></docno>
+ <date></date>
+ <rev></rev>
+ <file>part_notes.xml</file>
+ </header>
+ <include file="notes_history"></include>
+</part>
+
+
diff --git a/lib/ssh/doc/src/ref_man.xml b/lib/ssh/doc/src/ref_man.xml
new file mode 100644
index 0000000000..c05c3051b0
--- /dev/null
+++ b/lib/ssh/doc/src/ref_man.xml
@@ -0,0 +1,41 @@
+<?xml version="1.0" encoding="latin1" ?>
+<!DOCTYPE application SYSTEM "application.dtd">
+
+<application xmlns:xi="http://www.w3.org/2001/XInclude">
+ <header>
+ <copyright>
+ <year>2004</year><year>2009</year>
+ <holder>Ericsson AB. All Rights Reserved.</holder>
+ </copyright>
+ <legalnotice>
+ The contents of this file are subject to the Erlang Public License,
+ Version 1.1, (the "License"); you may not use this file except in
+ compliance with the License. You should have received a copy of the
+ Erlang Public License along with this software. If not, it can be
+ retrieved online at http://www.erlang.org/.
+
+ Software distributed under the License is distributed on an "AS IS"
+ basis, WITHOUT WARRANTY OF ANY KIND, either express or implied. See
+ the License for the specific language governing rights and limitations
+ under the License.
+
+ </legalnotice>
+
+ <title>SSH Reference Manual</title>
+ <prepared>Jakob Cederlund</prepared>
+ <docno></docno>
+ <date>2007-10-06</date>
+ <rev>%VSN%</rev>
+ <file>application.sgml</file>
+ </header>
+ <description>
+ <p>The SSH application is an erlang implementation of the
+ secure shell protocol.</p>
+ </description>
+ <xi:include href="ssh.xml"/>
+ <xi:include href="ssh_channel.xml"/>
+ <xi:include href="ssh_connection.xml"/>
+ <xi:include href="ssh_sftp.xml"/>
+ <xi:include href="ssh_sftpd.xml"/>
+</application>
+
diff --git a/lib/ssh/doc/src/ssh.xml b/lib/ssh/doc/src/ssh.xml
new file mode 100644
index 0000000000..aca5c9cdc4
--- /dev/null
+++ b/lib/ssh/doc/src/ssh.xml
@@ -0,0 +1,337 @@
+<?xml version="1.0" encoding="latin1" ?>
+<!DOCTYPE erlref SYSTEM "erlref.dtd">
+
+<erlref>
+ <header>
+ <copyright>
+ <year>2004</year><year>2009</year>
+ <holder>Ericsson AB. All Rights Reserved.</holder>
+ </copyright>
+ <legalnotice>
+ The contents of this file are subject to the Erlang Public License,
+ Version 1.1, (the "License"); you may not use this file except in
+ compliance with the License. You should have received a copy of the
+ Erlang Public License along with this software. If not, it can be
+ retrieved online at http://www.erlang.org/.
+
+ Software distributed under the License is distributed on an "AS IS"
+ basis, WITHOUT WARRANTY OF ANY KIND, either express or implied. See
+ the License for the specific language governing rights and limitations
+ under the License.
+
+ </legalnotice>
+
+ <title>ssh</title>
+ <prepared>Ingela Anderton Andin</prepared>
+ <responsible>H&aring;kan Mattsson</responsible>
+ <docno></docno>
+ <approved>H&aring;kan Mattsson</approved>
+ <checked></checked>
+ <date>2007-10-06</date>
+ <rev>PA1</rev>
+ </header>
+ <module>ssh</module>
+ <modulesummary>Main API of the SSH application</modulesummary>
+ <description>
+ <p>Interface module for the SSH application</p>
+ </description>
+
+
+ <section>
+ <title>COMMON DATA TYPES </title>
+ <p>Type definitions that are used more than once in
+ this module:</p>
+ <p><c>boolean() = true | false </c></p>
+ <p><c>string() = list of ASCII characters</c></p>
+ <p><c>ssh_daemon_ref() - opaque to the user
+ returned by ssh:daemon/[1,2,3]</c></p>
+ <p><c>ssh_connection_ref() - opaque to the user
+ returned by ssh:connect/3</c></p>
+ <p><c>ip_address() - {N1,N2,N3,N4} % IPv4 |
+ {K1,K2,K3,K4,K5,K6,K7,K8} % IPv6</c></p>
+ <p><c>subsystem_spec() = {subsystem_name(), {channel_callback(), channel_init_args()}} </c></p>
+ <p><c>subsystem_name() = string() </c></p>
+ <p><c>channel_callback() = atom() - Name of the erlang module
+ implementing the subsystem using the ssh_channel behavior see</c>
+ <seealso marker="ssh_channel">ssh_channel(3)</seealso></p>
+ <p><c>channel_init_args() = list()</c></p>
+ </section>
+
+ <funcs>
+
+ <func>
+ <name>close(ConnectionRef) -> ok </name>
+ <fsummary>Closes a ssh connection</fsummary>
+ <type>
+ <v>ConnectionRef = ssh_connection_ref()</v>
+ </type>
+ <desc><p>Closes a ssh connection.</p>
+ </desc>
+ </func>
+
+ <func>
+ <name>connect(Host, Port, Options) -> </name>
+ <name>connect(Host, Port, Options, Timeout) -> {ok, ssh_connection_ref()}
+ | {error, Reason}</name>
+ <fsummary>Connect to an ssh server.</fsummary>
+ <type>
+ <v>Host = string()</v>
+ <v>Port = integer()</v>
+ <d>The default is <c><![CDATA[22]]></c>, the registered port for SSH.</d>
+ <v>Options = [{Option, Value}]</v>
+ <v>Timeout = infinity | integer(milliseconds)</v>
+ </type>
+ <desc>
+ <p>Connects to an SSH server. No channel is started this is done
+ by calling ssh_connect:session_channel/2.</p>
+ <p>Options are:</p>
+ <taglist>
+ <tag><c><![CDATA[{user_dir, String}]]></c></tag>
+ <item>
+ <p>Sets the user directory e.i. the directory containing
+ ssh configuration files for the user such as
+ <c><![CDATA[known_hosts]]></c>, <c><![CDATA[id_rsa, id_dsa]]></c> and
+ <c><![CDATA[authorized_key]]></c>. Defaults to the directory normally
+ referred to as <c><![CDATA[~/.ssh]]></c> </p>
+ </item>
+ <tag><c><![CDATA[{silently_accept_hosts, boolean()}]]></c></tag>
+ <item>
+ <p>When true hosts are added to the
+ file <c><![CDATA[known_hosts]]></c> without asking the user.
+ Defaults to false.
+ </p>
+ </item>
+ <tag><c><![CDATA[{user_interaction, boolean()}]]></c></tag>
+ <item>
+ <p>If false disables the client to connect to the server
+ if any user interaction is needed such as accepting that
+ the server will be added to the <c>known_hosts</c> file or
+ supplying a password. Defaults to true.
+ Even if user interaction is allowed it can be
+ suppressed by other options such as silently_accept_hosts and
+ password. Do note that it may not always be desirable to use
+ those options from a security point of view.</p>
+ </item>
+ <tag><c><![CDATA[{public_key_alg, ssh_rsa | ssh_dsa}]]></c></tag>
+ <item>
+ <p>Sets the preferred public key algorithm to use for user
+ authentication. If the the preferred algorithm fails of
+ some reason, the other algorithm is tried. The default is
+ to try <c><![CDATA[ssh_rsa]]></c> first.</p>
+ </item>
+ <tag><c><![CDATA[{connect_timeout, timeout()}]]></c></tag>
+ <item>
+ <p>Sets a timeout on the transport layer connection. Defaults to infinity.</p>
+ </item>
+ <tag><c><![CDATA[{user, String}]]></c></tag>
+ <item>
+ <p>Provide a user name. If this option is not given, ssh
+ reads from the environment (<c><![CDATA[LOGNAME]]></c> or
+ <c><![CDATA[USER]]></c> on unix,
+ <c><![CDATA[USERNAME]]></c> on Windows).</p>
+ </item>
+ <tag><c><![CDATA[{password, string()}]]></c></tag>
+ <item>
+ <p>Provide a password for password authentication. If
+ this option is not given, the user will be asked for a
+ password if the password authentication method is
+ attempted.</p>
+ </item>
+ <tag><c><![CDATA[{user_auth, Fun/3}]]></c></tag>
+ <item>
+ <p>Provide a fun for password authentication. The fun
+ will be called as <c><![CDATA[fun(User, Password, Opts)]]></c> and
+ should return <c><![CDATA[true]]></c> or <c><![CDATA[false]]></c>.</p>
+ </item>
+ <tag><c><![CDATA[{key_cb, atom() = KeyCallbackModule}]]></c></tag>
+ <item>
+ <p>Provide a special call-back module for key handling.
+ The call-back module should be modeled after the
+ <c><![CDATA[ssh_file]]></c> module. The functions that must
+ be exported are:
+ <c><![CDATA[private_host_rsa_key/2]]></c>,
+ <c><![CDATA[private_host_dsa_key/2]]></c>,
+ <c><![CDATA[lookup_host_key/3]]></c> and
+ <c><![CDATA[add_host_key/3]]></c>. This is considered
+ somewhat experimental and will be better documented later on.</p>
+ </item>
+ <tag><c><![CDATA[{fd, file_descriptor()}]]></c></tag>
+ <item>
+ <p>Allow an existing file-descriptor to be used
+ (simply passed on to the transport protocol).</p></item>
+ </taglist>
+ </desc>
+ </func>
+
+ <func>
+ <name>connection_info(ConnectionRef, [Option]) ->[{Option, Value}] </name>
+ <fsummary> Retrieves information about a connection. </fsummary>
+ <type>
+ <v>Option = client_version | server_version | peer</v>
+ <v>Value = term() </v>
+ </type>
+ <desc>
+ <p> Retrieves information about a connection.
+ </p>
+ </desc>
+ </func>
+
+ <func>
+ <name>daemon(Port) -> </name>
+ <name>daemon(Port, Options) -> </name>
+ <name>daemon(HostAddress, Port, Options) -> ssh_daemon_ref()</name>
+ <fsummary>Starts a server listening for SSH connections
+ on the given port.</fsummary>
+ <type>
+ <v>Port = integer()</v>
+ <v>HostAddress = ip_address() | any</v>
+ <v>Options = [{Option, Value}]</v>
+ <v>Option = atom()</v>
+ <v>Value = term()</v>
+ </type>
+ <desc>
+ <p>Starts a server listening for SSH connections on the given port.</p>
+
+ <p>Options are:</p>
+ <taglist>
+ <tag><c><![CDATA[{subsystems, [subsystem_spec()]]]></c></tag>
+ <item>
+ Provides specifications for handling of subsystems. The
+ "sftp" subsystem-spec can be retrieved by calling
+ ssh_sftd:subsystem_spec/1. If the subsystems option in not present
+ the value of <c>[ssh_sftd:subsystem_spec([])]</c> will be used.
+ It is of course possible to set the option to the empty list
+ if you do not want the daemon to run any subsystems at all.
+ </item>
+ <tag><c><![CDATA[{shell, {Module, Function, Args} | fun(string() = User) - > pid() |
+ fun(string() = User, ip_address() = PeerAddr) -> pid()}]]></c></tag>
+ <item>
+ Defines the read-eval-print loop used when a shell is requested
+ by the client. Example use the
+ erlang shell: <c><![CDATA[{shell, start, []}]]></c> which is
+ the default behavior.
+ </item>
+ <tag><c><![CDATA[{ssh_cli,{channel_callback(), channel_init_args()}}]]></c></tag>
+ <item>
+ Provide your own cli implementation, e.i. a channel callback
+ module that implements a shell and command execution. Note
+ that you may customize the shell read-eval-print loop using the
+ option <c>shell</c> which is much less work than implementing
+ your own cli channel.
+ </item>
+ <tag><c><![CDATA[{system_dir, string()}]]></c></tag>
+ <item>
+ <p>Sets the system directory, containing the host files
+ that identifies the host for ssh. The default is
+ <c><![CDATA[/etc/ssh]]></c>, note that SSH normally
+ requires the host files there to be readable only by
+ root.</p>
+ </item>
+ <tag><c><![CDATA[{user_passwords, [{string() = User, string() = Password}]}]]></c></tag>
+ <item>
+ <p>Provide passwords for password authentication.They will
+ be used when someone tries to connect to the server and
+ public key user authentication fails. The option provides
+ a list of valid user names and the corresponding password.
+ </p>
+ </item>
+ <tag><c><![CDATA[{password, string()}]]></c></tag>
+ <item>
+ <p>Provide a global password that will authenticate any
+ user. From a security perspective this option makes
+ the server very vulnerable.</p>
+ </item>
+ <tag><c><![CDATA[{pwdfun, fun/2}]]></c></tag>
+ <item>
+ <p>Provide a function for password validation. This is called
+ with user and password as strings, and should return
+ <c><![CDATA[true]]></c> if the password is valid and
+ <c><![CDATA[false]]></c> otherwise.</p>
+ </item>
+ <tag><c><![CDATA[{fd, file_descriptor()}]]></c></tag>
+ <item>
+ <p>Allow an existing file-descriptor to be used
+ (simply passed on to the transport protocol).</p></item>
+ </taglist>
+ </desc>
+ </func>
+
+ <func>
+ <name>shell(Host) -> </name>
+ <name>shell(Host, Option) -> </name>
+ <name>shell(Host, Port, Option) -> _</name>
+ <fsummary> </fsummary>
+ <type>
+ <v> Host = string()</v>
+ <v> Port = integer()</v>
+ <v> Options - see ssh:connect/3</v>
+ </type>
+ <desc>
+ <p>Starts an interactive shell to an SSH server on the
+ given <c>Host</c>. The function waits for user input,
+ and will not return until the remote shell is ended (e.g. on
+ exit from the shell).
+ </p>
+ </desc>
+ </func>
+
+ <func>
+ <name>start() -> </name>
+ <name>start(Type) -> ok | {error, Reason}</name>
+ <fsummary>Starts the Ssh application. </fsummary>
+ <type>
+ <v>Type = permanent | transient | temporary</v>
+ <v>Reason = term() </v>
+ </type>
+ <desc>
+ <p>Starts the Ssh application. Default type
+ is temporary. See also
+ <seealso marker="kernel:application">application(3)</seealso>
+ Requires that the crypto application has been started.
+ </p>
+ </desc>
+ </func>
+
+ <func>
+ <name>stop() -> ok </name>
+ <fsummary>Stops the Ssh application.</fsummary>
+ <desc>
+ <p>Stops the Ssh application. See also
+ <seealso marker="kernel:application">application(3)</seealso></p>
+ </desc>
+ </func>
+
+ <func>
+ <name>stop_daemon(DaemonRef) -> </name>
+ <name>stop_daemon(Address, Port) -> ok </name>
+ <fsummary>Stops the listener and all connections started by
+ the listener.</fsummary>
+ <type>
+ <v>DaemonRef = ssh_daemon_ref()</v>
+ <v>Address = ip_address()</v>
+ <v>Port = integer()</v>
+ </type>
+ <desc>
+ <p>Stops the listener and all connections started by
+ the listener.</p>
+ </desc>
+ </func>
+
+ <func>
+ <name>stop_listener(DaemonRef) -> </name>
+ <name>stop_listener(Address, Port) -> ok </name>
+ <fsummary>Stops the listener, but leaves existing connections started
+ by the listener up and running.</fsummary>
+ <type>
+ <v>DaemonRef = ssh_daemon_ref()</v>
+ <v>Address = ip_address()</v>
+ <v>Port = integer()</v>
+ </type>
+ <desc>
+ <p>Stops the listener, but leaves existing connections started
+ by the listener up and running.</p>
+ </desc>
+ </func>
+ </funcs>
+
+</erlref>
diff --git a/lib/ssh/doc/src/ssh_channel.xml b/lib/ssh/doc/src/ssh_channel.xml
new file mode 100644
index 0000000000..c2b7aa94a5
--- /dev/null
+++ b/lib/ssh/doc/src/ssh_channel.xml
@@ -0,0 +1,520 @@
+<?xml version="1.0" encoding="latin1" ?>
+<!DOCTYPE erlref SYSTEM "erlref.dtd">
+
+<erlref>
+ <header>
+ <copyright>
+ <year>2009</year>
+ <year>2009</year>
+ <holder>Ericsson AB, All Rights Reserved</holder>
+ </copyright>
+ <legalnotice>
+ The contents of this file are subject to the Erlang Public License,
+ Version 1.1, (the "License"); you may not use this file except in
+ compliance with the License. You should have received a copy of the
+ Erlang Public License along with this software. If not, it can be
+ retrieved online at http://www.erlang.org/.
+
+ Software distributed under the License is distributed on an "AS IS"
+ basis, WITHOUT WARRANTY OF ANY KIND, either express or implied. See
+ the License for the specific language governing rights and limitations
+ under the License.
+
+ The Initial Developer of the Original Code is Ericsson AB.
+ </legalnotice>
+
+ <title>ssh_channel</title>
+ <prepared>Ingela Anderton Andin</prepared>
+ <responsible></responsible>
+ <docno></docno>
+ <approved></approved>
+ <checked></checked>
+ <date></date>
+ <rev></rev>
+ </header>
+ <module>ssh_channel</module>
+ <modulesummary>Generic Ssh Channel Behavior
+ </modulesummary>
+ <description>
+ <p>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.
+ </p>
+ </description>
+
+ <section>
+ <title>COMMON DATA TYPES </title>
+
+ <p>Type definitions that are used more than once in this module
+ and/or abstractions to indicate the intended use of the data
+ type:</p>
+
+ <p><c>boolean() = true | false </c></p>
+ <p><c>string() = list of ASCII characters</c></p>
+ <p><c>timeout() = infinity | integer() - in milliseconds.</c></p>
+ <p><c>ssh_connection_ref() - opaque to the user returned by
+ ssh:connect/3 or sent to a ssh channel process</c></p>
+ <p><c>ssh_channel_id() = integer() </c></p>
+ <p><c>ssh_data_type_code() = 1 ("stderr") | 0 ("normal") are
+ currently valid values see RFC 4254 section 5.2.</c></p>
+ </section>
+
+ <funcs>
+ <func>
+ <name>call(ChannelRef, Msg) -></name>
+ <name>call(ChannelRef, Msg, Timeout) -> Reply | {error, Reason}</name>
+ <fsummary> Makes a synchronous call to a channel.</fsummary>
+ <type>
+ <v>ChannelRef = pid() </v>
+ <d>As returned by start_link/4 </d>
+ <v>Msg = term() </v>
+ <v>Timeout = timeout() </v>
+ <v>Reply = term() </v>
+ <v>Reason = closed | timeout </v>
+ </type>
+ <desc>
+ <p>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
+ <c>CallbackModule:handle_call/3</c> to handle the message.
+ If the channel process does not exist <c>{error, closed}</c> is returned.
+ </p>
+ </desc>
+ </func>
+
+ <func>
+ <name>cast(ChannelRef, Msg) -> ok </name>
+ <fsummary>Sends an asynchronous message to the channel
+ ChannelRef and returns ok.</fsummary>
+ <type>
+ <v>ChannelRef = pid() </v>
+ <d>As returned by start_link/4 </d>
+ <v>Msg = term() </v>
+ </type>
+ <desc>
+ <p>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
+ <c>CallbackModule:handle_cast/2</c> to handle the message.
+ </p>
+ </desc>
+ </func>
+
+ <func>
+ <name>enter_loop(State) -> _ </name>
+ <fsummary> Makes an existing process into a ssh_channel process. </fsummary>
+ <type>
+ <v> State = term() - as returned by ssh_channel:init/1</v>
+ </type>
+ <desc>
+ <p> Makes an existing process into a <c>ssh_channel</c>
+ process. Does not return, instead the calling process will
+ enter the <c>ssh_channel</c> process receive loop and become a
+ <c>ssh_channel process.</c> The process must have been started using
+ one of the start functions in proc_lib, see <seealso
+ marker="stdlib:proc_lib">proc_lib(3)</seealso>. The
+ user is responsible for any initialization of the process
+ and needs to call ssh_channel:init/1.
+ </p>
+ </desc>
+ </func>
+
+ <func>
+ <name>init(Options) -> {ok, State} | {ok, State, Timeout} | {stop, Reason} </name>
+ <fsummary> Initiates a ssh_channel process.</fsummary>
+ <type>
+ <v> Options = [{Option, Value}]</v>
+ </type>
+ <desc>
+ <p>
+ The following options must be present:
+ </p>
+ <taglist>
+ <tag><c><![CDATA[{channel_cb, atom()}]]></c></tag>
+ <item>The module that implements the channel behavior.</item>
+
+ <tag><c><![CDATA[{init_args(), list()}]]></c></tag>
+ <item> The list of arguments to the callback modules
+ init function.</item>
+
+ <tag><c><![CDATA[{cm, connection_ref()}]]></c></tag>
+ <item> Reference to the ssh connection.</item>
+
+ <tag><c><![CDATA[{channel_id, channel_id()}]]></c></tag>
+ <item> Id of the ssh channel.</item>
+
+ </taglist>
+
+ <note><p>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 <c>proc_lib</c> instead calling
+ <c>ssh_channel:start/4</c> or <c>ssh_channel:start_link/4</c> </p>
+ </note>
+ </desc>
+ </func>
+
+ <func>
+ <name>reply(Client, Reply) -> _</name>
+ <fsummary>Send a reply to a client.</fsummary>
+ <type>
+ <v>Client - opaque to the user, see explanation below</v>
+ <v>Reply = term()</v>
+ </type>
+ <desc>
+ <p>This function can be used by a channel to explicitly send a
+ reply to a client that called <c>call/[2,3]</c> when the reply
+ cannot be defined in the return value of
+ <c>CallbackModule:handle_call/3</c>.</p>
+ <p><c>Client</c> must be the <c>From</c> argument provided to
+ the callback function <c>handle_call/3</c>.
+ <c>Reply</c> is an arbitrary term,
+ which will be given back to the client as the return value of
+ <c>ssh_channel:call/[2,3].</c></p>
+ </desc>
+ </func>
+
+ <func>
+ <name>start(SshConnection, ChannelId, ChannelCb, CbInitArgs) -> </name>
+ <name>start_link(SshConnection, ChannelId, ChannelCb, CbInitArgs) ->
+ {ok, ChannelRef} | {error, Reason}</name>
+ <fsummary> Starts a processes that handles a ssh channel. </fsummary>
+ <type>
+ <v>SshConnection = ssh_connection_ref()</v>
+ <v>ChannelId = ssh_channel_id() </v>
+ <d> As returned by ssh_connection:session_channel/[2,4]</d>
+ <v>ChannelCb = atom()</v>
+ <d> The name of the module implementing the service specific parts
+ of the channel.</d>
+ <v>CbInitArgs = [term()]</v>
+ <d>Argument list for the init function in the callback module. </d>
+ <v>ChannelRef = pid()</v>
+ </type>
+ <desc>
+ <p>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.
+ </p>
+ </desc>
+ </func>
+
+ </funcs>
+
+ <section>
+ <title>CALLBACK FUNCTIONS</title>
+
+ <p>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
+ <seealso marker="ssh">ssh:daemon/[2, 3]</seealso>. The
+ handle_call/3, handle_cast/2 code_change/3 and enter_loop/1
+ functions are only relevant when implementing a client side
+ channel.</p>
+ </section>
+
+ <section>
+ <marker id="cb_timeouts"></marker>
+ <title> CALLBACK TIMEOUTS</title>
+ <p> 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 <c>Timeout</c> milliseconds. A timeout
+ is represented by the atom <c>timeout</c> which should be handled
+ by the <seealso marker="#handle_msg">handle_msg/2</seealso>
+ callback function. The atom infinity can be used to wait
+ indefinitely, this is the default value. </p>
+ </section>
+
+ <funcs>
+ <func>
+ <name>CallbackModule:code_change(OldVsn, State, Extra) -> {ok,
+ NewState}</name>
+ <fsummary> Converts process state when code is changed.</fsummary>
+ <type>
+ <v> Converts process state when code is changed.</v>
+ </type>
+ <desc>
+ <p>This function is called by a client side channel when it
+ should update its internal state during a release
+ upgrade/downgrade, i.e. when the instruction
+ <c>{update,Module,Change,...}</c> where
+ <c>Change={advanced,Extra}</c> is given in the <c>appup</c>
+ file. See <seealso
+ marker="doc/design_principles:release_handling#instr">OTP
+ Design Principles</seealso> 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.
+ </p>
+
+ <note><p>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.</p></note>
+
+ <p>In the case of an upgrade, <c>OldVsn</c> is <c>Vsn</c>, and
+ in the case of a downgrade, <c>OldVsn</c> is
+ <c>{down,Vsn}</c>. <c>Vsn</c> is defined by the <c>vsn</c>
+ attribute(s) of the old version of the callback module
+ <c>Module</c>. If no such attribute is defined, the version
+ is the checksum of the BEAM file.</p>
+ <p><c>State</c> is the internal state of the channel.</p>
+ <p><c>Extra</c> is passed as-is from the <c>{advanced,Extra}</c>
+ part of the update instruction.</p>
+ <p>The function should return the updated internal state.</p>
+ </desc>
+ </func>
+
+ <func>
+ <name>CallbackModule: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 ssh_channel:start_link/4.</d>
+ <v> State = term() </v>
+ <v>Timeout = timeout() </v>
+ <v> Reason = term() </v>
+ </type>
+ <desc>
+ <p> Makes necessary initializations and returns the initial channel
+ state if the initializations succeed.
+ </p>
+ <p>For more detailed information on timeouts see the section
+ <seealso marker="#cb_timeouts">CALLBACK TIMEOUTS</seealso>. </p>
+ </desc>
+ </func>
+
+ <func>
+ <name>CallbackModule:handle_call(Msg, From, State) -> Result</name>
+ <fsummary> Handles messages sent by calling
+ <c>ssh_channel:call/[2,3]</c></fsummary>
+ <type>
+ <v>Msg = term()</v>
+ <v>From = opaque to the user should be used as argument to
+ ssh_channel:reply/2</v>
+ <v>State = term()</v>
+ <v>Result = {reply, Reply, NewState} | {reply, Reply, NewState, Timeout}
+ | {noreply, NewState} | {noreply , NewState, Timeout}
+ | {stop, Reason, Reply, NewState} | {stop, Reason, NewState} </v>
+ <v>Reply = term() - will be the return value of ssh_channel:call/[2,3]</v>
+ <v>Timeout = timeout() </v>
+ <v>NewState = term() - a possible updated version of State</v>
+ <v>Reason = term()</v>
+ </type>
+ <desc>
+ <p>Handles messages sent by calling
+ <c>ssh_channel:call/[2,3]</c>
+ </p>
+ <p>For more detailed information on timeouts see the section
+ <seealso marker="#cb_timeouts">CALLBACK TIMEOUTS</seealso>. </p>
+ </desc>
+ </func>
+
+ <func>
+ <name>CallbackModule:handle_cast(Msg, State) -> Result</name>
+ <fsummary> Handles messages sent by calling
+ <c>ssh_channel:cact/2</c></fsummary>
+ <type>
+ <v>Msg = term()</v>
+ <v>State = term()</v>
+ <v>Result = {noreply, NewState} | {noreply, NewState, Timeout}
+ | {stop, Reason, NewState}</v>
+ <v>NewState = term() - a possible updated version of State</v>
+ <v>Timeout = timeout() </v>
+ <v>Reason = term()</v>
+ </type>
+ <desc>
+ <p> Handles messages sent by calling
+ <c>ssh_channel:cast/2</c>
+ </p>
+ <p>For more detailed information on timeouts see the section
+ <seealso marker="#cb_timeouts">CALLBACK TIMEOUTS</seealso>. </p>
+ <marker id="handle_msg"></marker>
+ </desc>
+ </func>
+
+ <func>
+ <name>CallbackModule:handle_msg(Msg, State) -> {ok, State} |
+ {stop, ChannelId, State}</name>
+
+ <fsummary> Handle other messages than ssh connection protocol,
+ call or cast messages sent to the channel.</fsummary>
+ <type>
+ <v>Msg = timeout | term()</v>
+ <v>State = term() </v>
+ </type>
+ <desc>
+ <p>Handle other messages than ssh connection protocol, call or
+ cast messages sent to the channel.
+ </p>
+
+ <p> Possible erlang 'EXIT'-messages should be handled by this
+ function and all channels should handle the following message.</p>
+
+ <taglist>
+ <tag><c><![CDATA[{ssh_channel_up, ssh_channel_id(),
+ ssh_connection_ref()}]]></c></tag>
+ <item>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}.
+ </item>
+ </taglist>
+ </desc>
+ </func>
+
+ <func>
+ <name>CallbackModule:handle_ssh_msg(Msg, State) -> {ok, State} | {stop,
+ ssh_channel_id(), State}</name>
+ <fsummary> Handles ssh connection protocol messages. </fsummary>
+ <type>
+ <v>Msg = {ssh_cm, ssh_connection_ref(), SshMsg}</v>
+ <v> SshMsg = tuple() - see message list below</v>
+ <v>State = term()</v>
+ </type>
+ <desc>
+ <p> Handles ssh connection protocol messages that may need
+ service specific attention.
+ </p>
+
+ <p> All channels should handle the following messages. For
+ channels implementing subsystems the handle_ssh_msg-callback
+ will not be called for any other messages. </p>
+
+ <taglist>
+ <tag><c><![CDATA[{ssh_cm, ssh_connection_ref(), {data, ssh_channel_id(),
+ ssh_data_type_code(), binary() = Data}}]]></c></tag>
+ <item> Data has arrived on the channel. When the callback
+ for this message returns the channel behavior will adjust
+ the ssh flow control window.</item>
+
+ <tag><c><![CDATA[{ssh_cm, ssh_connection_ref(), {eof,
+ ssh_channel_id()}}]]></c></tag>
+ <item>Indicteas that the other side will not send any more
+ data.</item>
+
+ <tag><c><![CDATA[{ssh_cm, ssh_connection_ref(), {signal,
+ ssh_channel_id(), ssh_signal()}} ]]></c></tag>
+ <item>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.</item>
+
+ <tag><c><![CDATA[{ssh_cm, ssh_connection_ref(),
+ {exit_signal, ssh_channel_id(), string() = exit_signal,
+ string() = ErrorMsg, string() =
+ LanguageString}}]]></c></tag>
+ <item>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</item>
+
+ <tag><c><![CDATA[{ssh_cm, ssh_connection_ref(), {exit_status,
+ ssh_channel_id(), integer() = ExitStatus}}]]></c></tag>
+ <item> 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.</item>
+ </taglist>
+
+ <p> Channels implementing a shell and command execution on the server side
+ should also handle the following messages. </p>
+
+ <taglist>
+ <tag><c><![CDATA[{ssh_cm, ssh_connection_ref(), {env, ssh_channel_id(),
+ boolean() = WantReply, string() = Var, string() = Value}}]]></c></tag>
+ <item> 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 <c>
+ WantReply</c> as the second argument.
+ </item>
+
+ <tag><c><![CDATA[{ssh_cm, ConnectionRef, {exec, ssh_channel_id(),
+ boolean() = WantReply, string() = Cmd}}]]></c></tag>
+ <item> 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 <c>
+ WantReply</c> as the second argument.</item>
+
+ <tag><c><![CDATA[{ssh_cm, ssh_connection_ref(), {pty, ssh_channel_id(),
+ boolean() = WantReply, {string() = Terminal, integer() = CharWidth,
+ integer() = RowHeight, integer() = PixelWidth, integer() = PixelHight,
+ [{atom() | integer() = Opcode,
+ integer() = Value}] = TerminalModes}}}]]></c></tag>
+ <item>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 <c>Opcode</c> in the
+ <c>TerminalModes</c> 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 <c>OP code: 53, mnemonic name ECHO erlang atom:
+ echo</c>. Note that before the callback returns it should
+ call the function ssh_connection:reply_request/4 with the
+ boolean value of <c> WantReply</c> as the second
+ argument.</item>
+
+ <tag><c><![CDATA[{ssh_cm, ConnectionRef, {shell, boolean() =
+ WantReply}}]]></c></tag>
+ <item> 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 <c>
+ WantReply</c> as the second argument.
+ </item>
+
+ <tag><c><![CDATA[ {ssh_cm, ssh_connection_ref(), {window_change,
+ ssh_channel_id(), integer() = CharWidth, integer() = RowHeight,
+ integer() = PixWidth, integer() = PixHeight}}]]></c></tag>
+ <item> 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.</item>
+ </taglist>
+
+ <p> The following message is completely taken care of by the
+ ssh channel behavior</p>
+
+ <taglist>
+ <tag><c><![CDATA[{ssh_cm, ssh_connection_ref(), {closed,
+ ssh_channel_id()}}]]></c></tag>
+ <item> 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.</item>
+ </taglist>
+ </desc>
+ </func>
+
+ <func>
+ <name>CallbackModule:terminate(Reason, State) -> _</name>
+ <fsummary> </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 ssh_connection:close/2
+ will be called if it has not been called earlier.
+ This function should be the opposite of <c>CallbackModule:init/1</c>
+ and do 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_connection.xml b/lib/ssh/doc/src/ssh_connection.xml
new file mode 100644
index 0000000000..499cbbeabe
--- /dev/null
+++ b/lib/ssh/doc/src/ssh_connection.xml
@@ -0,0 +1,302 @@
+<?xml version="1.0" encoding="latin1" ?>
+<!DOCTYPE erlref SYSTEM "erlref.dtd">
+
+<erlref>
+ <header>
+ <copyright>
+ <year>2008</year>
+ <year>2008</year>
+ <holder>Ericsson AB, All Rights Reserved</holder>
+ </copyright>
+ <legalnotice>
+ The contents of this file are subject to the Erlang Public License,
+ Version 1.1, (the "License"); you may not use this file except in
+ compliance with the License. You should have received a copy of the
+ Erlang Public License along with this software. If not, it can be
+ retrieved online at http://www.erlang.org/.
+
+ Software distributed under the License is distributed on an "AS IS"
+ basis, WITHOUT WARRANTY OF ANY KIND, either express or implied. See
+ the License for the specific language governing rights and limitations
+ under the License.
+
+ The Initial Developer of the Original Code is Ericsson AB.
+ </legalnotice>
+
+ <title>ssh_connection</title>
+ <prepared>Ingela Anderton Andin</prepared>
+ <responsible></responsible>
+ <docno></docno>
+ <approved></approved>
+ <checked></checked>
+ <date></date>
+ <rev></rev>
+ </header>
+ <module>ssh_connection</module>
+ <modulesummary>This module provides an API to the ssh connection protocol.
+ </modulesummary>
+ <description>
+ <p>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.</p>
+ </description>
+
+ <section>
+ <title>COMMON DATA TYPES </title>
+ <p>Type definitions that are used more than once in this module and/or
+ abstractions to indicate the intended use of the data type:</p>
+
+ <p><c>boolean() = true | false </c></p>
+ <p><c>string() = list of ASCII characters</c></p>
+ <p><c>timeout() = infinity | integer() - in milliseconds.</c></p>
+ <p><c>ssh_connection_ref() - opaque to the user returned by
+ ssh:connect/3 or sent to a ssh channel processes</c></p>
+ <p><c>ssh_channel_id() = integer() </c></p>
+ <p><c>ssh_data_type_code() = 1 ("stderr") | 0 ("normal") are
+ currently valid values see RFC 4254 section 5.2.</c></p>
+ <p><c>ssh_request_status() = success | failure</c></p>
+ </section>
+
+ <section>
+ <title>MESSAGES SENT TO CHANNEL PROCESSES</title>
+
+ <p>As a result of the ssh connection protocol messages on the form
+ <c><![CDATA[{ssh_cm, ssh_connection_ref(), term()}]]></c>
+ 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 <seealso
+ marker="ssh_channel">handle_ssh_msg/2 </seealso> </p>
+ </section>
+
+ <funcs>
+
+ <func>
+ <name>adjust_window(ConnectionRef, ChannelId, NumOfBytes) -> ok</name>
+ <fsummary>Adjusts the ssh flowcontrol window. </fsummary>
+ <type>
+ <v> ConnectionRef = ssh_connection_ref() </v>
+ <v> ChannelId = ssh_channel_id() </v>
+ <v> NumOfBytes = integer()</v>
+ </type>
+ <desc>
+ <p>Adjusts the ssh flowcontrol window. </p>
+
+ <note><p>This will be taken care of by the ssh_channel
+ behavior when the callback <seealso marker="ssh_channel">
+ handle_ssh_msg/2 </seealso> 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.</p></note>
+ </desc>
+ </func>
+
+ <func>
+ <name>close(ConnectionRef, ChannelId) -> ok</name>
+ <fsummary>Sends a close message on the channel <c>ChannelId</c>. </fsummary>
+ <type>
+ <v> ConnectionRef = ssh_connection_ref() </v>
+ <v> ChannelId = ssh_channel_id()</v>
+ </type>
+ <desc>
+ <p>Sends a close message on the channel <c>ChannelId</c>
+ </p>
+
+ <note><p>This function will be called by the ssh channel
+ behavior when the channel is terminated see <seealso
+ marker="ssh_channel"> ssh_channel(3) </seealso> and should
+ normally not be called explicitly.</p></note>
+ </desc>
+ </func>
+
+ <func>
+ <name>exec(ConnectionRef, ChannelId, Command, TimeOut) -> ssh_request_status() </name>
+ <fsummary>Will request that the server start the
+ execution of the given command. </fsummary>
+ <type>
+ <v> ConnectionRef = ssh_connection_ref() </v>
+ <v> ChannelId = ssh_channel_id()</v>
+ <v> Command = string()</v>
+ <v>Timeout = timeout() </v>
+ </type>
+ <desc>
+ <p>Will request that the server start the execution of the
+ given command, the result will be received as:</p>
+
+ <taglist>
+ <tag><c> N X {ssh_cm,
+ ssh_connection_ref(), {data, ssh_channel_id(), ssh_data_type_code(),
+ binary() = Data}} </c></tag>
+ <item>The result of executing the command may be only one line
+ or thousands of lines depending on the command.</item>
+
+ <tag><c> 1 X {ssh_cm, ssh_connection_ref(), {eof, ssh_channel_id()}}</c></tag>
+ <item>Indicates that no more data will be sent.</item>
+
+ <tag><c>0 or 1 X {ssh_cm,
+ ssh_connection_ref(), {exit_signal,
+ ssh_channel_id(), string() = ExitSignal, string() = ErrorMsg, string() = LanguageString}}</c></tag>
+ <item>Not all systems send signals. For details on valid string
+ values see RFC 4254 section 6.10 </item>
+
+ <tag><c>0 or 1 X {ssh_cm, ssh_connection_ref(), {exit_status,
+ ssh_channel_id(), integer() = ExitStatus}}</c></tag>
+ <item>It is recommended by the <c>ssh connection protocol</c> that this
+ message shall be sent, but that may not always be the case.</item>
+
+ <tag><c> 1 X {ssh_cm, ssh_connection_ref(),
+ {closed, ssh_channel_id()}}</c></tag>
+ <item>Indicates that the ssh channel started for the
+ execution of the command has now been shutdown.</item>
+ </taglist>
+
+ <p> These message should be handled by the
+ client. The <seealso marker="ssh_channel">ssh channel
+ behavior</seealso> can be used when writing a client.
+ </p>
+ </desc>
+ </func>
+
+
+ <func>
+ <name>exit_status(ConnectionRef, ChannelId, Status) -> ok</name>
+ <fsummary>Sends the exit status of a command to the client.</fsummary>
+ <type>
+ <v> ConnectionRef = ssh_connection_ref() </v>
+ <v> ChannelId = ssh_channel_id()</v>
+ <v> Status = integer()</v>
+ </type>
+ <desc>
+ <p>Sends the exit status of a command to the client.</p>
+ </desc>
+ </func>
+
+ <func>
+ <name>reply_request(ConnectionRef, WantReply, Status, CannelId) -> ok</name>
+ <fsummary>Send status replies to requests that want such replies. </fsummary>
+ <type>
+ <v> ConnectionRef = ssh_connection_ref() </v>
+ <v> WantReply = boolean()</v>
+ <v> Status = ssh_request_status() </v>
+ <v> ChannelId = ssh_channel_id()</v>
+ </type>
+ <desc>
+ <p>Sends status replies to requests where the requester has
+ stated that they want a status report e.i .<c> WantReply = true</c>,
+ if <c> WantReply</c> is false calling this function will be a
+ "noop". Should be called after handling an ssh connection
+ protocol message containing a <c>WantReply</c> boolean
+ value. See the ssh_channel behavior callback <seealso
+ marker="ssh_channel"> handle_ssh_msg/2 </seealso>
+ </p>
+ </desc>
+ </func>
+
+ <func>
+ <name>send(ConnectionRef, ChannelId, Data) -></name>
+ <name>send(ConnectionRef, ChannelId, Data, Timeout) -></name>
+ <name>send(ConnectionRef, ChannelId, Type, Data) -></name>
+ <name>send(ConnectionRef, ChannelId, Type, Data, TimeOut) ->
+ ok | {error, timeout}</name>
+ <fsummary>Sends channel data </fsummary>
+ <type>
+ <v> ConnectionRef = ssh_connection_ref() </v>
+ <v> ChannelId = ssh_channel_id()</v>
+ <v> Data = binary()</v>
+ <v> Type = ssh_data_type_code()</v>
+ <v> Timeout = timeout()</v>
+ </type>
+ <desc>
+ <p>Sends channel data.
+ </p>
+ </desc>
+ </func>
+
+ <func>
+ <name>send_eof(ConnectionRef, ChannelId) -> ok </name>
+ <fsummary>Sends eof on the channel <c>ChannelId</c>. </fsummary>
+ <type>
+ <v> ConnectionRef = ssh_connection_ref() </v>
+ <v> ChannelId = ssh_channel_id()</v>
+ </type>
+ <desc>
+ <p>Sends eof on the channel <c>ChannelId</c>.
+ </p>
+ </desc>
+ </func>
+
+ <func>
+ <name>session_channel(ConnectionRef, Timeout) -> </name>
+ <name>session_channel(ConnectionRef, InitialWindowSize,
+ MaxPacketSize, Timeout) -> {ok, ssh_channel_id()} | {error, Reason}</name>
+ <fsummary>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. </fsummary>
+ <type>
+ <v> ConnectionRef = ssh_connection_ref()</v>
+ <v> InitialWindowSize = integer() </v>
+ <v> MaxPacketSize = integer() </v>
+ <v> Timeout = timeout()</v>
+ <v> Reason = term() </v>
+ </type>
+ <desc>
+ <p>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.
+ </p>
+ </desc>
+ </func>
+
+ <func>
+ <name>setenv(ConnectionRef, ChannelId, Var, Value, TimeOut) -> ssh_request_status()</name>
+ <fsummary> Environment variables may be passed to the
+ shell/command to be started later.</fsummary>
+ <type>
+ <v> ConnectionRef = ssh_connection_ref() </v>
+ <v> ChannelId = ssh_channel_id()</v>
+ <v> Var = string()</v>
+ <v> Value = string()</v>
+ <v> Timeout = timeout()</v>
+ </type>
+ <desc>
+ <p> Environment variables may be passed to the shell/command to be
+ started later.
+ </p>
+ </desc>
+ </func>
+
+ <func>
+ <name>shell(ConnectionRef, ChannelId) -> ssh_request_status()
+ </name>
+ <fsummary> Will request that the user's default shell (typically
+ defined in /etc/passwd in UNIX systems) be started at the other
+ end. </fsummary>
+ <type>
+ <v> ConnectionRef = ssh_connection_ref() </v>
+ <v> ChannelId = ssh_channel_id()</v>
+ </type>
+ <desc>
+ <p> Will request that the user's default shell (typically
+ defined in /etc/passwd in UNIX systems) be started at the
+ other end.
+ </p>
+ </desc>
+ </func>
+
+ <func>
+ <name>subsystem(ConnectionRef, ChannelId, Subsystem, Timeout) -> ssh_request_status()</name>
+ <fsummary> </fsummary>
+ <type>
+ <v> ConnectionRef = ssh_connection_ref() </v>
+ <v> ChannelId = ssh_channel_id()</v>
+ <v> Subsystem = string()</v>
+ <v> Timeout = timeout()</v>
+ </type>
+ <desc>
+ <p> Sends a request to execute a predefined subsystem.
+ </p>
+ </desc>
+ </func>
+
+ </funcs>
+
+</erlref>
diff --git a/lib/ssh/doc/src/ssh_sftp.xml b/lib/ssh/doc/src/ssh_sftp.xml
new file mode 100644
index 0000000000..208b2b4e72
--- /dev/null
+++ b/lib/ssh/doc/src/ssh_sftp.xml
@@ -0,0 +1,501 @@
+<?xml version="1.0" encoding="latin1" ?>
+<!DOCTYPE erlref SYSTEM "erlref.dtd">
+
+<erlref>
+ <header>
+ <copyright>
+ <year>2005</year><year>2009</year>
+ <holder>Ericsson AB. All Rights Reserved.</holder>
+ </copyright>
+ <legalnotice>
+ The contents of this file are subject to the Erlang Public License,
+ Version 1.1, (the "License"); you may not use this file except in
+ compliance with the License. You should have received a copy of the
+ Erlang Public License along with this software. If not, it can be
+ retrieved online at http://www.erlang.org/.
+
+ Software distributed under the License is distributed on an "AS IS"
+ basis, WITHOUT WARRANTY OF ANY KIND, either express or implied. See
+ the License for the specific language governing rights and limitations
+ under the License.
+
+ </legalnotice>
+
+ <title>ssh_sftp</title>
+ <prepared>Jakob Cederlund</prepared>
+ <responsible></responsible>
+ <docno>1</docno>
+ <approved></approved>
+ <checked></checked>
+ <date>2005-09-22</date>
+ <rev>PA1</rev>
+ <file>ssh_sftp.sgml</file>
+ </header>
+ <module>ssh_sftp</module>
+ <modulesummary>SFTP client.</modulesummary>
+ <description>
+ <p>This module implements an SFTP (SSH FTP) client. SFTP is a
+ secure, encrypted file transfer service available for
+ SSH.</p>
+ </description>
+
+ <section>
+ <title>COMMON DATA TYPES </title>
+ <p>Type definitions that are used more than once in this module
+ and/or abstractions to indicate the intended use of the data type:
+ </p>
+ <p><c>ssh_connection_ref() - opaque to the user
+ returned by ssh:connect/3</c></p>
+ <p><c>timeout() = infinity | integer() - in milliseconds.</c></p>
+ </section>
+
+ <section>
+ <title>TIMEOUTS </title>
+ <p>If the request functions for the sftp channel return {error, timeout}
+ it does not mean that the request did not reach the server and was
+ not performed, it only means that we did not receive an answer from the
+ server within the time that was expected.</p>
+ </section>
+
+ <funcs>
+ <func>
+ <name>start_channel(ConnectionRef) -> </name>
+ <name>start_channel(ConnectionRef, Options) -> </name>
+ <name>start_channel(Host, Options) -></name>
+ <name>start_channel(Host, Port, Options) -> {ok, Pid} | {ok, Pid, ConnectionRef} |
+ {error, Reason}</name>
+ <fsummary>Starts a sftp client</fsummary>
+ <type>
+ <v>Host = string()</v>
+ <v>ConnectionRef = ssh_connection_ref()</v>
+ <v>Port = integer()</v>
+ <v>Options = [{Option, Value}]</v>
+ <v>Reason = term()</v>
+ </type>
+ <desc>
+ <p>If not provided, setups a ssh connection in this case a
+ connection reference will be returned too. A ssh channel
+ process is started to handle the communication with the SFTP
+ server, the returned pid for this process should be used as
+ input to all other API functions in this module.</p>
+
+ <p>Options are:</p>
+ <taglist>
+ <tag><c><![CDATA[{timeout, timeout()}]]></c></tag>
+ <item>
+ <p>The timeout is passed to the ssh_channel start function,
+ and defaults to infinity.</p>
+ </item>
+ </taglist>
+ <p>All other options are directly passed to
+ <seealso marker="ssh">ssh:connect/3</seealso> or ignored if a
+ connection is already provided. </p>
+ </desc>
+ </func>
+
+ <func>
+ <name>stop_channel(ChannelPid) -> ok</name>
+ <fsummary>Stops the sftp client channel.</fsummary>
+ <type>
+ <v>ChannelPid = pid()</v>
+ </type>
+ <desc>
+ <p>Stops a sftp channel. If the ssh connection should be closed
+ call <seealso marker="ssh">ssh:close/1</seealso>.</p>
+ </desc>
+ </func>
+
+ <func>
+ <name>read_file(ChannelPid, File) -> </name>
+ <name>read_file(ChannelPid, File, Timeout) -> {ok, Data} | {error, Reason}</name>
+ <fsummary>Read a file</fsummary>
+ <type>
+ <v>ChannelPid = pid()</v>
+ <v>File = string()</v>
+ <v>Data = binary()</v>
+ <v>Timeout = timeout()</v>
+ <v>Reason = term()</v>
+ </type>
+ <desc>
+ <p>Reads a file from the server, and returns the data in a binary,
+ like <c><![CDATA[file:read_file/1]]></c>.</p>
+ </desc>
+ </func>
+ <func>
+ <name>write_file(ChannelPid, File, Iolist) -> </name>
+ <name>write_file(ChannelPid, File, Iolist, Timeout) -> ok | {error, Reason}</name>
+ <fsummary>Write a file</fsummary>
+ <type>
+ <v>ChannelPid = pid()</v>
+ <v>File = string()</v>
+ <v>Iolist = iolist()</v>
+ <v>Timeout = timeout()</v>
+ <v>Reason = term()</v>
+ </type>
+ <desc>
+ <p>Writes a file to the server, like <c><![CDATA[file:write_file/2]]></c>.
+ The file is created if it's not there.</p>
+ </desc>
+ </func>
+ <func>
+ <name>list_dir(ChannelPid, Path) -> </name>
+ <name>list_dir(ChannelPid, Path, Timeout) -> {ok, Filenames} | {error, Reason}</name>
+ <fsummary>List directory</fsummary>
+ <type>
+ <v>ChannelPid = pid()</v>
+ <v>Path = string()</v>
+ <v>Filenames = [Filename]</v>
+ <v>Filename = string()</v>
+ <v>Timeout = timeout()</v>
+ <v>Reason = term()</v>
+ </type>
+ <desc>
+ <p>Lists the given directory on the server, returning the
+ filenames as a list of strings.</p>
+ </desc>
+ </func>
+ <func>
+ <name>open(ChannelPid, File, Mode) -> </name>
+ <name>open(ChannelPid, File, Mode, Timeout) -> {ok, Handle} | {error, Reason}</name>
+ <fsummary>Open a file and return a handle</fsummary>
+ <type>
+ <v>ChannelPid = pid()</v>
+ <v>File = string()</v>
+ <v>Mode = [Modeflag]</v>
+ <v>Modeflag = read | write | creat | trunc | append | binary</v>
+ <v>Timeout = timeout()</v>
+ <v>Handle = term()</v>
+ <v>Reason = term()</v>
+ </type>
+ <desc>
+ <p>Opens a file on the server, and returns a handle that
+ is used for reading or writing.</p>
+ </desc>
+ </func>
+ <func>
+ <name>opendir(ChannelPid, Path) -> </name>
+ <name>opendir(ChannelPid, Path, Timeout) -> {ok, Handle} | {error, Reason}</name>
+ <fsummary>Open a directory and return a handle</fsummary>
+ <type>
+ <v>ChannelPid = pid()</v>
+ <v>Path = string()</v>
+ <v>Timeout = timeout()</v>
+ <v>Reason = term()</v>
+ </type>
+ <desc>
+ <p>Opens a handle to a directory on the server, the handle
+ is used for reading directory contents.</p>
+ </desc>
+ </func>
+ <func>
+ <name>close(ChannelPid, Handle) -> </name>
+ <name>close(ChannelPid, Handle, Timeout) -> ok | {error, Reason}</name>
+ <fsummary>Close an open handle</fsummary>
+ <type>
+ <v>ChannelPid = pid()</v>
+ <v>Handle = term()</v>
+ <v>Timeout = timeout()</v>
+ <v>Reason = term()</v>
+ </type>
+ <desc>
+ <p>Closes a handle to an open file or directory on the server.</p>
+ </desc>
+ </func>
+ <func>
+ <name>read(ChannelPid, Handle, Len) -> </name>
+ <name>read(ChannelPid, Handle, Len, Timeout) -> {ok, Data} | eof | {error, Error}</name>
+ <name>pread(ChannelPid, Handle, Position, Len) -> </name>
+ <name>pread(ChannelPid, Handle, Position, Len, Timeout) -> {ok, Data} | eof | {error, Error}</name>
+ <fsummary>Read from an open file</fsummary>
+ <type>
+ <v>ChannelPid = pid()</v>
+ <v>Handle = term()</v>
+ <v>Position = integer()</v>
+ <v>Len = integer()</v>
+ <v>Timeout = timeout()</v>
+ <v>Data = string() | binary()</v>
+ <v>Reason = term()</v>
+ </type>
+ <desc>
+ <p>Reads <c><![CDATA[Len]]></c> bytes from the file referenced by
+ <c><![CDATA[Handle]]></c>. Returns <c><![CDATA[{ok, Data}]]></c>, or <c><![CDATA[eof]]></c>, or
+ <c><![CDATA[{error, Reason}]]></c>. If the file is opened with <c><![CDATA[binary]]></c>,
+ <c><![CDATA[Data]]></c> is a binary, otherwise it is a string.</p>
+ <p>If the file is read past eof, only the remaining bytes
+ will be read and returned. If no bytes are read, <c><![CDATA[eof]]></c>
+ is returned.</p>
+ <p>The <c><![CDATA[pread]]></c> function reads from a specified position,
+ combining the <c><![CDATA[position]]></c> and <c><![CDATA[read]]></c> functions.</p>
+ </desc>
+ </func>
+ <func>
+ <name>aread(ChannelPid, Handle, Len) -> {async, N} | {error, Error}</name>
+ <name>apread(ChannelPid, Handle, Position, Len) -> {async, N} | {error, Error}</name>
+ <fsummary>Read asynchronously from an open file</fsummary>
+ <type>
+ <v>ChannelPid = pid()</v>
+ <v>Handle = term()</v>
+ <v>Position = integer()</v>
+ <v>Len = integer()</v>
+ <v>N = term()</v>
+ <v>Reason = term()</v>
+ </type>
+ <desc>
+ <p>Reads from an open file, without waiting for the result. If the
+ handle is valid, the function returns <c><![CDATA[{async, N}]]></c>, where N
+ is a term guaranteed to be unique between calls of <c><![CDATA[aread]]></c>.
+ The actual data is sent as a message to the calling process. This
+ message has the form <c><![CDATA[{async_reply, N, Result}]]></c>, where
+ <c><![CDATA[Result]]></c> is the result from the read, either <c><![CDATA[{ok, Data}]]></c>,
+ or <c><![CDATA[eof]]></c>, or <c><![CDATA[{error, Error}]]></c>.</p>
+ <p>The <c><![CDATA[apread]]></c> function reads from a specified position,
+ combining the <c><![CDATA[position]]></c> and <c><![CDATA[aread]]></c> functions.</p>
+ </desc>
+ </func>
+ <func>
+ <name>write(ChannelPid, Handle, Data) -></name>
+ <name>write(ChannelPid, Handle, Data, Timeout) -> ok | {error, Error}</name>
+ <name>pwrite(ChannelPid, Handle, Position, Data) -> ok </name>
+ <name>pwrite(ChannelPid, Handle, Position, Data, Timeout) -> ok | {error, Error}</name>
+ <fsummary>Write to an open file</fsummary>
+ <type>
+ <v>ChannelPid = pid()</v>
+ <v>Handle = term()</v>
+ <v>Position = integer()</v>
+ <v>Data = iolist()</v>
+ <v>Timeout = timeout()</v>
+ <v>Reason = term()</v>
+ </type>
+ <desc>
+ <p>Write <c><![CDATA[data]]></c> to the file referenced by <c><![CDATA[Handle]]></c>.
+ The file should be opened with <c><![CDATA[write]]></c> or <c><![CDATA[append]]></c>
+ flag. Returns <c><![CDATA[ok]]></c> if successful and <c><![CDATA[{error, Reason}]]></c>
+ otherwise.</p>
+ <p>Typical error reasons are:</p>
+ <taglist>
+ <tag><c><![CDATA[ebadf]]></c></tag>
+ <item>
+ <p>The file is not opened for writing.</p>
+ </item>
+ <tag><c><![CDATA[enospc]]></c></tag>
+ <item>
+ <p>There is a no space left on the device.</p>
+ </item>
+ </taglist>
+ </desc>
+ </func>
+ <func>
+ <name>awrite(ChannelPid, Handle, Data) -> ok | {error, Reason} </name>
+ <name>apwrite(ChannelPid, Handle, Position, Data) -> ok | {error, Reason}</name>
+ <fsummary>Write asynchronously to an open file</fsummary>
+ <type>
+ <v>ChannelPid = pid()</v>
+ <v>Handle = term()</v>
+ <v>Position = integer()</v>
+ <v>Len = integer()</v>
+ <v>Data = binary()</v>
+ <v>Timeout = timeout()</v>
+ <v>Reason = term()</v>
+ </type>
+ <desc>
+ <p>Writes to an open file, without waiting for the result. If the
+ handle is valid, the function returns <c><![CDATA[{async, N}]]></c>, where N
+ is a term guaranteed to be unique between calls of
+ <c><![CDATA[awrite]]></c>. The result of the <c><![CDATA[write]]></c> operation is sent
+ as a message to the calling process. This message has the form
+ <c><![CDATA[{async_reply, N, Result}]]></c>, where <c><![CDATA[Result]]></c> is the result
+ from the write, either <c><![CDATA[ok]]></c>, or <c><![CDATA[{error, Error}]]></c>.</p>
+ <p>The <c><![CDATA[apwrite]]></c> writes on a specified position, combining
+ the <c><![CDATA[position]]></c> and <c><![CDATA[awrite]]></c> operations.</p>
+ </desc>
+ </func>
+ <func>
+ <name>position(ChannelPid, Handle, Location) -> </name>
+ <name>position(ChannelPid, Handle, Location, Timeout) -> {ok, NewPosition | {error, Error}</name>
+ <fsummary>Seek position in open file</fsummary>
+ <type>
+ <v>ChannelPid = pid()</v>
+ <v>Handle = term()</v>
+ <v>Location = Offset | {bof, Offset} | {cur, Offset} | {eof, Offset} | bof | cur | eof</v>
+ <v>Offset = int()</v>
+ <v>Timeout = timeout()</v>
+ <v>NewPosition = integer()</v>
+ <v>Reason = term()</v>
+ </type>
+ <desc>
+ <p>Sets the file position of the file referenced by <c><![CDATA[Handle]]></c>.
+ Returns <c><![CDATA[{ok, NewPosition]]></c> (as an absolute offset) if
+ successful, otherwise <c><![CDATA[{error, Reason}]]></c>. <c><![CDATA[Location]]></c> is
+ one of the following:</p>
+ <taglist>
+ <tag><c><![CDATA[Offset]]></c></tag>
+ <item>
+ <p>The same as <c><![CDATA[{bof, Offset}]]></c>.</p>
+ </item>
+ <tag><c><![CDATA[{bof, Offset}]]></c></tag>
+ <item>
+ <p>Absolute offset.</p>
+ </item>
+ <tag><c><![CDATA[{cur, Offset}]]></c></tag>
+ <item>
+ <p>Offset from the current position.</p>
+ </item>
+ <tag><c><![CDATA[{eof, Offset}]]></c></tag>
+ <item>
+ <p>Offset from the end of file.</p>
+ </item>
+ <tag><c><![CDATA[bof | cur | eof]]></c></tag>
+ <item>
+ <p>The same as above with <c><![CDATA[Offset]]></c> 0.</p>
+ </item>
+ </taglist>
+ </desc>
+ </func>
+ <func>
+ <name>read_file_info(ChannelPid, Name) -> </name>
+ <name>read_file_info(ChannelPid, Name, Timeout) -> {ok, FileInfo} | {error, Reason}</name>
+ <fsummary>Get information about a file</fsummary>
+ <type>
+ <v>ChannelPid = pid()</v>
+ <v>Name = string()</v>
+ <v>Handle = term()</v>
+ <v>Timeout = timeout()</v>
+ <v>FileInfo = record()</v>
+ <v>Reason = term()</v>
+ </type>
+ <desc>
+ <p>Returns a <c><![CDATA[file_info]]></c> record from the file specified by
+ <c><![CDATA[Name]]></c> or <c><![CDATA[Handle]]></c>, like <c><![CDATA[file:read_file_info/2]]></c>.</p>
+ </desc>
+ </func>
+ <func>
+ <name>read_link_info(ChannelPid, Name) -> {ok, FileInfo} | {error, Reason}</name>
+ <name>read_link_info(ChannelPid, Name, Timeout) -> {ok, FileInfo} | {error, Reason}</name>
+ <fsummary>Get information about a symbolic link</fsummary>
+ <type>
+ <v>ChannelPid = pid()</v>
+ <v>Name = string()</v>
+ <v>Handle = term()</v>
+ <v>Timeout = timeout()</v>
+ <v>FileInfo = record()</v>
+ <v>Reason = term()</v>
+ </type>
+ <desc>
+ <p>Returns a <c><![CDATA[file_info]]></c> record from the symbolic
+ link specified by <c><![CDATA[Name]]></c> or <c><![CDATA[Handle]]></c>, like
+ <c><![CDATA[file:read_link_info/2]]></c>.</p>
+ </desc>
+ </func>
+ <func>
+ <name>write_file_info(ChannelPid, Name, Info) -> </name>
+ <name>write_file_info(ChannelPid, Name, Info, Timeout) -> ok | {error, Reason}</name>
+ <fsummary>Write information for a file</fsummary>
+ <type>
+ <v>ChannelPid = pid()</v>
+ <v>Name = string()</v>
+ <v>Info = record()</v>
+ <v>Timeout = timeout()</v>
+ <v>Reason = term()</v>
+ </type>
+ <desc>
+ <p>Writes file information from a <c><![CDATA[file_info]]></c> record to the
+ file specified by <c><![CDATA[Name]]></c>, like <c><![CDATA[file:write_file_info]]></c>.</p>
+ </desc>
+ </func>
+ <func>
+ <name>read_link(ChannelPid, Name) -> </name>
+ <name>read_link(ChannelPid, Name, Timeout) -> {ok, Target} | {error, Reason}</name>
+ <fsummary>Read symbolic link</fsummary>
+ <type>
+ <v>ChannelPid = pid()</v>
+ <v>Name = string()</v>
+ <v>Target = string()</v>
+ <v>Reason = term()</v>
+ </type>
+ <desc>
+ <p>Read the link target from the symbolic link specified
+ by <c><![CDATA[name]]></c>, like <c><![CDATA[file:read_link/1]]></c>.</p>
+ </desc>
+ </func>
+ <func>
+ <name>make_symlink(ChannelPid, Name, Target) -> </name>
+ <name>make_symlink(ChannelPid, Name, Target, Timeout) -> ok | {error, Reason}</name>
+ <fsummary>Create symbolic link</fsummary>
+ <type>
+ <v>ChannelPid = pid()</v>
+ <v>Name = string()</v>
+ <v>Target = string()</v>
+ <v>Reason = term()</v>
+ </type>
+ <desc>
+ <p>Creates a symbolic link pointing to <c><![CDATA[Target]]></c> with the
+ name <c><![CDATA[Name]]></c>, like <c><![CDATA[file:make_symlink/2]]></c>.</p>
+ </desc>
+ </func>
+ <func>
+ <name>rename(ChannelPid, OldName, NewName) -> </name>
+ <name>rename(ChannelPid, OldName, NewName, Timeout) -> ok | {error, Reason}</name>
+ <fsummary>Rename a file</fsummary>
+ <type>
+ <v>ChannelPid = pid()</v>
+ <v>OldName = string()</v>
+ <v>NewName = string()</v>
+ <v>Timeout = timeout()</v>
+ <v>Reason = term()</v>
+ </type>
+ <desc>
+ <p>Renames a file named <c><![CDATA[OldName]]></c>, and gives it the name
+ <c><![CDATA[NewName]]></c>, like <c><![CDATA[file:rename/2]]></c></p>
+ </desc>
+ </func>
+ <func>
+ <name>delete(ChannelPid, Name) -> </name>
+ <name>delete(ChannelPid, Name, Timeout) -> ok | {error, Reason}</name>
+ <fsummary>Delete a file</fsummary>
+ <type>
+ <v>ChannelPid = pid()</v>
+ <v>Name = string()</v>
+ <v>Timeout = timeout()</v>
+ <v>Reason = term()</v>
+ </type>
+ <desc>
+ <p>Deletes the file specified by <c><![CDATA[Name]]></c>, like
+ <c><![CDATA[file:delete/1]]></c></p>
+ </desc>
+ </func>
+ <func>
+ <name>make_dir(ChannelPid, Name) -> </name>
+ <name>make_dir(ChannelPid, Name, Timeout) -> ok | {error, Reason}</name>
+ <fsummary>Create a directory</fsummary>
+ <type>
+ <v>ChannelPid = pid()</v>
+ <v>Name = string()</v>
+ <v>Timeout = timeout()</v>
+ <v>Reason = term()</v>
+ </type>
+ <desc>
+ <p>Creates a directory specified by <c><![CDATA[Name]]></c>. <c><![CDATA[Name]]></c> should
+ be a full path to a new directory. The directory can only be
+ created in an existing directory.</p>
+ </desc>
+ </func>
+ <func>
+ <name>del_dir(ChannelPid, Name) -> </name>
+ <name>del_dir(ChannelPid, Name, Timeout) -> ok | {error, Reason}</name>
+ <fsummary>Delete an empty directory</fsummary>
+ <type>
+ <v>ChannelPid = pid()</v>
+ <v>Name = string()</v>
+ <v>Timeout = timeout()</v>
+ <v>Reason = term()</v>
+ </type>
+ <desc>
+ <p>Deletes a directory specified by <c><![CDATA[Name]]></c>. The directory
+ should be empty.</p>
+ </desc>
+ </func>
+
+ </funcs>
+
+</erlref>
+
diff --git a/lib/ssh/doc/src/ssh_sftpd.xml b/lib/ssh/doc/src/ssh_sftpd.xml
new file mode 100644
index 0000000000..c857983565
--- /dev/null
+++ b/lib/ssh/doc/src/ssh_sftpd.xml
@@ -0,0 +1,94 @@
+<?xml version="1.0" encoding="latin1" ?>
+<!DOCTYPE erlref SYSTEM "erlref.dtd">
+
+<erlref>
+ <header>
+ <copyright>
+ <year>2005</year><year>2009</year>
+ <holder>Ericsson AB. All Rights Reserved.</holder>
+ </copyright>
+ <legalnotice>
+ The contents of this file are subject to the Erlang Public License,
+ Version 1.1, (the "License"); you may not use this file except in
+ compliance with the License. You should have received a copy of the
+ Erlang Public License along with this software. If not, it can be
+ retrieved online at http://www.erlang.org/.
+
+ Software distributed under the License is distributed on an "AS IS"
+ basis, WITHOUT WARRANTY OF ANY KIND, either express or implied. See
+ the License for the specific language governing rights and limitations
+ under the License.
+
+ </legalnotice>
+
+ <title>ssh_sftpd</title>
+ <prepared>Ingela Anderton Andin</prepared>
+ <responsible></responsible>
+ <docno>1</docno>
+ <approved></approved>
+ <checked></checked>
+ <date>2005-09-22</date>
+ <rev>PA1</rev>
+ <file>ssh_sftpd.sgml</file>
+ </header>
+ <module>ssh_sftpd</module>
+ <modulesummary>Specifies a channel process to handle a sftp subsystem.</modulesummary>
+ <description>
+ <p>Specifies a channel process to handle a sftp subsystem.</p>
+ </description>
+
+ <section>
+ <title>COMMON DATA TYPES </title>
+ <p><c>subsystem_spec() = {subsystem_name(), {channel_callback(), channel_init_args()}} </c></p>
+ <p><c>subsystem_name() = "sftp"</c></p>
+ <p><c>channel_callback() = atom()</c> - Name of the erlang module implementing the
+ subsystem using the ssh_channel behavior see
+ <seealso marker="ssh_channel">ssh_channel(3)</seealso></p>
+ <p><c> channel_init_args() = list() - The one given as argument to function
+ subsystem_spec/1.</c></p>
+ </section>
+ <funcs>
+ <func>
+ <name>subsystem_spec(Options) -> subsystem_spec()</name>
+ <fsummary>Returns the subsystem specification that allows an ssh daemon to handle the subsystem "sftp".</fsummary>
+ <type>
+ <v>Options = [{Option, Value}]</v>
+ </type>
+ <desc>
+ <p>Should be used together with ssh:daemon/[1,2,3]</p>
+ <p>Options are:</p>
+ <taglist>
+ <tag><c><![CDATA[{cwd, String}]]></c></tag>
+ <item>
+ <p>Sets the initial current working directory for the
+ server.</p>
+ </item>
+ <tag><c><![CDATA[{file_handler, CallbackModule}]]></c></tag>
+ <item>
+ <p>Determines which module to call for communicating with
+ the file server. Default value is <c>ssh_sftpd_file</c> that uses the
+ file and filelib API:s to access the standard OTP file
+ server. This option may be used to plug in the use of
+ other file servers.</p>
+ </item>
+ <tag><c><![CDATA[{max_files, Integer}]]></c></tag>
+ <item>
+ <p>The default value is <c>0</c>, which means that there is no upper limit.
+ If supplied, the number of filenames returned to the sftp client per <c>READDIR</c>
+ request, is limited to at most the given value.</p>
+ </item>
+ <tag><c><![CDATA[{root, String}]]></c></tag>
+ <item>
+ <p>Sets the sftp root directory. The user will then not be
+ able to see any files above this root. If for instance
+ the root is set to <c>/tmp</c> the user will see this
+ directory as <c>/</c> and if the user does cd <c>/etc</c>
+ the user will end up in <c>/tmp/etc</c>.
+ </p>
+ </item>
+ </taglist>
+ </desc>
+ </func>
+ </funcs>
+</erlref>
+
diff --git a/lib/ssh/doc/src/user_guide.gif b/lib/ssh/doc/src/user_guide.gif
new file mode 100644
index 0000000000..e6275a803d
--- /dev/null
+++ b/lib/ssh/doc/src/user_guide.gif
Binary files differ
generated by cgit v1.2.3 (git 2.25.1) at 2024-11-05 01:13:56 +0000