diff options
Diffstat (limited to 'lib/ssh/doc/src')
| -rw-r--r-- | lib/ssh/doc/src/Makefile | 205 | ||||
| -rw-r--r-- | lib/ssh/doc/src/book.xml | 46 | ||||
| -rw-r--r-- | lib/ssh/doc/src/fascicules.xml | 15 | ||||
| -rw-r--r-- | lib/ssh/doc/src/make.dep | 19 | ||||
| -rw-r--r-- | lib/ssh/doc/src/notes.xml | 588 | ||||
| -rw-r--r-- | lib/ssh/doc/src/notes_history.xml | 737 | ||||
| -rw-r--r-- | lib/ssh/doc/src/part_notes.xml | 38 | ||||
| -rw-r--r-- | lib/ssh/doc/src/part_notes_history.xml | 36 | ||||
| -rw-r--r-- | lib/ssh/doc/src/ref_man.xml | 41 | ||||
| -rw-r--r-- | lib/ssh/doc/src/ssh.xml | 337 | ||||
| -rw-r--r-- | lib/ssh/doc/src/ssh_channel.xml | 520 | ||||
| -rw-r--r-- | lib/ssh/doc/src/ssh_connection.xml | 302 | ||||
| -rw-r--r-- | lib/ssh/doc/src/ssh_sftp.xml | 501 | ||||
| -rw-r--r-- | lib/ssh/doc/src/ssh_sftpd.xml | 94 | ||||
| -rw-r--r-- | lib/ssh/doc/src/user_guide.gif | bin | 0 -> 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åkan Mattsson</responsible> + <docno></docno> + <approved>Hå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 Binary files differnew file mode 100644 index 0000000000..e6275a803d --- /dev/null +++ b/lib/ssh/doc/src/user_guide.gif |
