From 84adefa331c4159d432d22840663c38f155cd4c1 Mon Sep 17 00:00:00 2001 From: Erlang/OTP Date: Fri, 20 Nov 2009 14:54:40 +0000 Subject: The R13B03 release. --- lib/ssh/doc/src/Makefile | 205 +++++++++ lib/ssh/doc/src/book.xml | 46 ++ lib/ssh/doc/src/fascicules.xml | 15 + lib/ssh/doc/src/make.dep | 19 + lib/ssh/doc/src/notes.xml | 588 ++++++++++++++++++++++++++ lib/ssh/doc/src/notes_history.xml | 737 +++++++++++++++++++++++++++++++++ lib/ssh/doc/src/part_notes.xml | 38 ++ lib/ssh/doc/src/part_notes_history.xml | 36 ++ lib/ssh/doc/src/ref_man.xml | 41 ++ lib/ssh/doc/src/ssh.xml | 337 +++++++++++++++ lib/ssh/doc/src/ssh_channel.xml | 520 +++++++++++++++++++++++ lib/ssh/doc/src/ssh_connection.xml | 302 ++++++++++++++ lib/ssh/doc/src/ssh_sftp.xml | 501 ++++++++++++++++++++++ lib/ssh/doc/src/ssh_sftpd.xml | 94 +++++ lib/ssh/doc/src/user_guide.gif | Bin 0 -> 1581 bytes 15 files changed, 3479 insertions(+) create mode 100644 lib/ssh/doc/src/Makefile create mode 100644 lib/ssh/doc/src/book.xml create mode 100644 lib/ssh/doc/src/fascicules.xml create mode 100644 lib/ssh/doc/src/make.dep create mode 100644 lib/ssh/doc/src/notes.xml create mode 100644 lib/ssh/doc/src/notes_history.xml create mode 100644 lib/ssh/doc/src/part_notes.xml create mode 100644 lib/ssh/doc/src/part_notes_history.xml create mode 100644 lib/ssh/doc/src/ref_man.xml create mode 100644 lib/ssh/doc/src/ssh.xml create mode 100644 lib/ssh/doc/src/ssh_channel.xml create mode 100644 lib/ssh/doc/src/ssh_connection.xml create mode 100644 lib/ssh/doc/src/ssh_sftp.xml create mode 100644 lib/ssh/doc/src/ssh_sftpd.xml create mode 100644 lib/ssh/doc/src/user_guide.gif (limited to 'lib/ssh/doc/src') 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 @@ + + + + +
+ + 20052009 + Ericsson AB. 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. + + + + SSH + OTP Team + + 2007-10-06 + %VSN% + book.sgml +
+ + + SSH + + + + + + + + + + + + + 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 @@ + + + + + + Reference Manual + + + Release Notes + + + Off-Print + + + 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 @@ + + + + +
+ + 20042009 + Ericsson AB. 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. + + + + SSH Release Notes + + + + %VSN% + notes.xml +
+ +
Ssh 1.1.7 + +
Fixed Bugs and Malfunctions + + +

+ Now clear all processes when a connnection is terminated.

+

+ Own Id: OTP-8121 Aux Id:

+ + +

+ In some rare cases the connection handler could enter an infinite loop.

+

+ Own Id: OTP-8277 Aux Id: seq11428

+ + +

+ If an SFTP server did not respond with EOF, the function + ssh_sftp:list_dir/2/3 would enter an infinite loop.

+

+ Own Id: OTP-8278 Aux Id: seq11450

+ + +
+ +
Improvements and New Features + + +

+ 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.

+

+ Own Id: OTP-8201 Aux Id:

+ + +
+ +
+ +
Ssh 1.1.6 + +
Fixed Bugs and Malfunctions + + +

+ ssh_sftp:start_channel did not handle all possible return + values from ssh_channel:start correctly. +

+

+ Own Id: OTP-8176 Aux Id:

+ + +

+ SFTPD did not handle rename command (version 4) correctly. +

+

+ Own Id: OTP-8175 Aux Id: seq11373

+ + +

+ If a connection manager already had been terminated it could cause a channel + to generate a crash report when it was about to stop. +

+

+ Own Id: OTP-8174 Aux Id: seq11377

+ + +

+ Requests could result in badarg or badmatch EXIT messages in the connection + manager if the channel no longer existed.

+

+ Own Id: OTP-8173 Aux Id: seq11379

+ + +

+ ssh_transport:unpack/3 could cause a badarg error.

+

+ Own Id: OTP-8162 Aux Id:

+ + +
+ +
Improvements and New Features + + +

+ The encryption algorithm aes128-cbc is now supported. + Requires that crypto-1.6.1 is available.

+

+ Own Id: OTP-8110 Aux Id:

+ + +
+ +
+ + +
Ssh 1.1.5 + +
Fixed Bugs and Malfunctions + + +

+ ssh_sftp:start_channel/3 did not handle timout correctly.

+

+ Own Id: OTP-8159 Aux Id: seq11386

+ + +

+ 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.

+

+ Own Id: OTP-8160 Aux Id: seq11386

+ + +

+ A comma has been missing in the ssh.appup file since SSH-1.0.2.

+

+ Own Id: OTP-8161 Aux Id:

+ + +
+ +
+ +
Ssh 1.1.4 + +
Fixed Bugs and Malfunctions + + +

+ SSH sometimes caused a crash report at disconnect.

+

+ Own Id: OTP-8071 Aux Id: seq11319

+ + +
+ +
+ +
Ssh 1.1.3 + +
Fixed Bugs and Malfunctions + + +

+ The operation ssh_sftp:stop_channel/1 returned an + exception if the connection already had been closed.

+

+ Own Id: OTP-7996 Aux Id: seq11281

+ + +

+ SSH did not handle if supervisor:start_child/2 returned + {error, already_present}.

+

+ Own Id: OTP-8034 Aux Id: seq11307

+ + +

+ SSH no longer cause supervisor reports when a connection is + terminated in a controlled manner.

+

+ Own Id: OTP-8035 Aux Id: seq11308

+ + +
+ +
+ +
Ssh 1.1.2 + +
Fixed Bugs and Malfunctions + + +

+ Ssh confused local and remote channel id's, which in some + cases resulted in that messages were discarded.

+

+ Own Id: OTP-7914 Aux Id: seq11234

+ + +

+ Ssh could not handle echo values other than 0 and 1.

+

+ Own Id: OTP-7917 Aux Id: seq11238

+ + +

+ A crash occurred if a non-valid channel reference was received.

+

+ Own Id: OTP-7918 Aux Id: seq11238

+ + +

+ Sftpd connections was not closed after receiving eof from a client.

+

+ Own Id: OTP-7921 Aux Id: seq11222

+ + +

+ It was not possible to start a SFTP subsystem on certain platforms, + i.e. those who do not support symbolic links.

+

+ Own Id: OTP-7930 Aux Id:

+ + +

+ In some cases the message {ssh_cm, ssh_connection_ref(), {closed, ssh_channel_id()}} + was not passed to the registered callback module.

+

+ Own Id: OTP-7957 Aux Id:

+ + +
+ +
Improvements and New Features + + +

+ By using the sftpd option {max_files, Integer}, the message + size for READDIR commands can be reduced.

+

+ Own Id: OTP-7919 Aux Id: seq11230

+ + +
+ +
+ +
Ssh 1.1.1 + +
Fixed Bugs and Malfunctions + + +

+ 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.

+

+ Own Id: OTP-7795

+ + +

+ 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.

+

+ Own Id: OTP-7920 Aux Id: seq11211

+ + +
+ +
Improvements and New Features + + +

+ 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.

+

+ *** POTENTIAL INCOMPATIBILITY ***

+

+ Own Id: OTP-7807

+ + +

+ The implementation of timeouts added as a patch in + ssh-1.0.1 was slightly changed and is now documented.

+

+ Own Id: OTP-7808

+ + +

+ 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.

+

+ Own Id: OTP-7809

+ + +

+ 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.

+

+ *** POTENTIAL INCOMPATIBILITY ***

+

+ Own Id: OTP-7828

+ + +
+ +
+ +
Ssh 1.1 + +
Fixed Bugs and Malfunctions + + +

+ 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.

+

+ Own Id: OTP-7676

+ + +

+ Tabs could cause ssh_cli to print things in a surprising + way.

+

+ Own Id: OTP-7683 Aux Id: seq11102

+ + +

+ [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.

+

+ Own Id: OTP-7685 Aux Id: seq11082

+ + +

+ [sftpd] - Added patch to further improve handling of + symbolic links in the sftp-server.

+

+ Own Id: OTP-7766 Aux Id: seq11101

+ + +

+ 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) .

+

+ Own Id: OTP-7767

+ + +

+ Packet data could be lost under high load due to the fact + that buffered data was sometimes wrongly discarded before + it had been sent.

+

+ Own Id: OTP-7768

+ + +

+ Improved ipv6-handling as some assumptions about inet + functions where incorrect.

+

+ Own Id: OTP-7770

+ + +
+ + +
Improvements and New Features + + +

+ Added new API function ssh:connection_info/2.

+

+ Own Id: OTP-7456

+ + +

+ Now starts ssh channel processes later avoiding + synchronization problems between processes.

+

+ Own Id: OTP-7516

+ + +

+ 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.)

+

+ Own Id: OTP-7645 Aux Id: seq11094

+ + +

+ 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.

+

+ *** POTENTIAL INCOMPATIBILITY ***

+

+ Own Id: OTP-7769

+ + +
+ +
Known Bugs and Problems + + +

+ Public keys protected by a password are currently not + handled by the erlang ssh application.

+

+ Own Id: OTP-6400 Aux Id: 10595

+ + +
+ +
+ +
Ssh 1.0.2 + +
Fixed Bugs and Malfunctions + + +

+ [sftpd] - Listing of symbolic link directories should now + work as expected.

+

+ Own Id: OTP-7141 Aux Id: seq10856

+ + +
+ +
+ +
Ssh 1.0.1 + +
Fixed Bugs and Malfunctions + + +

+ [sftp] - When listing a directory with more than 100 + files only the first 100 where listed. This has now been + fixed.

+

+ Own Id: OTP-7318 Aux Id: seq10953

+ + +

+ When restarting an ssh-system the expected return value + from ssh_system_sup:restart_acceptor/2 was incorrect, + this is no longer the case.

+

+ Own Id: OTP-7564 Aux Id: seq11055

+ + +

+ 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.

+

+ Own Id: OTP-7565

+ + +

+ Fixed bug in ipv6 support and added option to disable + ipv6 as a workaround for badly configured computers.

+

+ Own Id: OTP-7566

+ + +
+ +
Improvements and New Features + + +

+ [sftp] - Option added to set timeout value in sftp.

+

+ Own Id: OTP-7305 Aux Id: seq10945

+ + +
+ +
+ +
Ssh 1.0 + +
Fixed Bugs and Malfunctions + + +

+ Removed some special handling of prompts that made ssh + behave differently than openssh.

+

+ Own Id: OTP-7485 Aux Id: seq11025

+ + +

+ Bug in encoding of pty opts has been fixed.

+

+ Own Id: OTP-7504

+ + +
+ + +
Improvements and New Features + + +

+ 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.

+

+ Own Id: OTP-7356 Aux Id: seq10899

+ + +

+ Support for pty option echo off added. Requires kernel + from R12B-4.

+

+ *** POTENTIAL INCOMPATIBILITY ***

+

+ Own Id: OTP-7502 Aux Id: seq10959

+ + +

+ The ssh API has been enhanced a lot of old API functions + has become deprecated.

+

+ Own Id: OTP-7503

+ + +
+ + +
+ + 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 @@ + + + + +
+ + 2009 + 2009 + Ericsson AB, 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. + + The Initial Developer of the Original Code is Ericsson AB. + + + SSH Release Notes History + + + + + + + A + notes_history.xml +
+ +
Ssh 0.9.9.6 + +
Improvements and New Features + + +

+ Updated asn1 file due to change in the asn1 compiler. + This has no semantical effect on the ssh application.

+

+ Own Id: OTP-7246

+ + +

+ Allows for the option {fd, FD} in listen and connect + calls. The option is passed on to gen_tcp:listen and + gen_tcp:connect

+

+ Own Id: OTP-7247

+ + +
+
+ +
Ssh 0.9.9.5 + +
Fixed Bugs and Malfunctions + + +

+ Putty version 0.60 sends ignore messages, which hanged + the OTP ssh server.

+

+ Own Id: OTP-7076

+ + +

+ ssh_cm hanged when connection was closed during + handshake. (Triggered by putty 0.60 client.)

+

+ Own Id: OTP-7089

+ + +

+ Fixed crash in server when receiving an empty ignore-msg. + (From the putty 0.60 client.)

+

+ Own Id: OTP-7135

+ + +
+ + +
Improvements and New Features + + +

+ Now uses the base 64 encode/decode function in stdlib.

+

+ Own Id: OTP-6486

+ + +

+ Removed runtime dependency on asn1.

+

+ Own Id: OTP-6570

+ + +

+ Documentation update of ssh.

+

+ Own Id: OTP-7063 Aux Id: seq10789

+ + +

+ 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.

+

+ Own Id: OTP-7090 Aux Id: seq10675

+ + +

+ Kebord-interactive support, according to rfc 4256, has + been added to the ssh client. Also the option + quiet_mode has been added so that unwanted banners + may be suppressed.

+

+ Own Id: OTP-7106 Aux Id: seq10841

+ + +
+ +
+ +
Ssh 0.9.9.4 + +
Improvements and New Features + + +

+ [sftpd] - Root parameter now behaves as expected, + instead of making sftpd malfunction.

+

+ Own Id: OTP-7057 Aux Id: seq10830

+ + +
+
+ +
Ssh 0.9.9.3 + +
Fixed Bugs and Malfunctions + + +

+ 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.

+

+ Own Id: OTP-6854 Aux Id: seq10740

+ + +

+ Fixed bugs in prompting in ssl_cli. Prompts like \003> + were written as \300>. Also, newlines and returns was + removed.

+

+ Own Id: OTP-6917 Aux Id: seq10773

+ + +
+ +
Improvements and New Features + + +

+ [sftpd] - New option "root" to set the root of the + sftp-server and the callback module for file handling now + has a state parameter.

+

+ Own Id: OTP-7075 Aux Id: seq10675

+ + +
+
+ +
+ Ssh 0.9.9.2 +
+ Better error-handling in ssh_sshd:listen + + +

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.

+

Own Id: OTP-6727

+ + +
+ +
+ Fix in ssh_sftpd + + +

Cd ../.. didn't work when connecting to a ssh_sftpd server.

+

Own Id: OTP-6727

+ + +
+
+ +
+ Ssh 0.9.9.1 + +
+ Minor Makefile changes + + +

Removed use of from Makefile.

+

Own Id: OTP-6689

+ + +
+
+ +
+ Ssh 0.9.9 + +
+ Fixed Bugs and Malfunctions + + +

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.

+

Own Id: OTP-6379 Aux Id: seq10523

+ + +
+
+ +
+ Ssh 0.9.8 + +
+ Fixed Bugs and Malfunctions + + +

Corrected minor bugs and removed dead code found by + dialyzer.

+

Own Id: OTP-6524

+ + +
+
+ +
+ Ssh 0.9.7 + +
+ Fixed Bugs and Malfunctions + + +

[sftp] - The function ssh_sftp:make_symlink/3 was not + fully implemented.

+

Own Id: OTP-6446

+ + +

[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.

+

Own Id: OTP-6450

+ + +

A pattern matching was missing "/binary" resulting in + that the internal function ssh_xfer:decode_acl/2 did not + work as expected.

+

Own Id: OTP-6458

+ + +

[sftp] - read_link/2 did not return the documented value

+

Own Id: OTP-6471

+ + +

Removed debugg printouts from ssh_cli.erl

+

Own Id: OTP-6483

+ + +

[sftp, ssh] - The connection timeout was overridden by an + internal gen_server default timeout.

+

Own Id: OTP-6488 Aux Id: seq10569

+ + +
+
+ +
+ Ssh 0.9.6 + +
+ Fixed Bugs and Malfunctions + + +

Removed debug printout from production code.

+

Own Id: OTP-6348 Aux Id: seq10510

+ + +

[sftpd] - When the sftp client ends the session the + server will now behave correctly and not leave the client + hanging.

+

Own Id: OTP-6349 Aux Id: seq10510

+ + +

[sftpd] - No longer used files were not closed until the + session was ended.

+

Own Id: OTP-6350 Aux Id: seq10514

+ + +

[sftpd] - File rename requests sent by sftp version 3 + clients were not handled.

+

Own Id: OTP-6352 Aux Id: seq10513

+ + +

[sftpd] - Request that did not fit into one ssh message + were not handled.

+

Own Id: OTP-6353 Aux Id: seq10515

+ + +

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.

+

Own Id: OTP-6414

+ + +
+ +
+ Improvements and New Features + + +

[sftpd] - Added new option to specify a callback module + for the sftpd-server file handling. The default callback + module uses file and filelib.

+

Own Id: OTP-6356 Aux Id: seq10519

+ + +
+
+ +
+ Ssh 0.9.5 + +
+ Fixed Bugs and Malfunctions + + +

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.

+

Own Id: OTP-6231

+ + +
+
+ +
+ SSH 0.9.4 + +
+ Reported Fixed Bugs and Malfunctions + + +

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 + ssh module.

+

Also changed some error reports to info reports.

+

Own Id: OTP-6183

+

Aux Id: Seq 10383

+ + +
+
+ +
+ SSH 0.9.3 + +
+ Improvements and New Features + + +

Added way for cli to get peer name

+

Own Id: OTP-6138

+ + +
+
+ +
+ SSH 0.9.2 + +
+ Improvements and New Features + + +

Added some options to listen

+

Own Id: OTP-6070

+ + +
+
+ +
+ SSH 0.9.1 +
Ssh 0.9.9.4 + +
Improvements and New Features + + +

+ [sftpd] - Root parameter now behaves as expected, + instead of making sftpd malfunction.

+

+ Own Id: OTP-7057 Aux Id: seq10830

+ + +
+
+ +
Ssh 0.9.9.3 + +
Fixed Bugs and Malfunctions + + +

+ 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.

+

+ Own Id: OTP-6854 Aux Id: seq10740

+ + +

+ Fixed bugs in prompting in ssl_cli. Prompts like \003> + were written as \300>. Also, newlines and returns was + removed.

+

+ Own Id: OTP-6917 Aux Id: seq10773

+ + +
+ +
Improvements and New Features + + +

+ [sftpd] - New option "root" to set the root of the + sftp-server and the callback module for file handling now + has a state parameter.

+

+ Own Id: OTP-7075 Aux Id: seq10675

+ + +
+
+ +
+ Ssh 0.9.9.2 +
+ Better error-handling in ssh_sshd:listen + + +

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.

+

Own Id: OTP-6727

+ + +
+ +
+ Fix in ssh_sftpd + + +

Cd ../.. didn't work when connecting to a ssh_sftpd server.

+

Own Id: OTP-6727

+ + +
+
+ +
+ Ssh 0.9.9.1 + +
+ Minor Makefile changes + + +

Removed use of from Makefile.

+

Own Id: OTP-6689

+ + +
+
+ +
+ Ssh 0.9.9 + +
+ Fixed Bugs and Malfunctions + + +

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.

+

Own Id: OTP-6379 Aux Id: seq10523

+ + +
+
+ +
+ Ssh 0.9.8 + +
+ Fixed Bugs and Malfunctions + + +

Corrected minor bugs and removed dead code found by + dialyzer.

+

Own Id: OTP-6524

+ + +
+
+ +
+ Ssh 0.9.7 + +
+ Fixed Bugs and Malfunctions + + +

[sftp] - The function ssh_sftp:make_symlink/3 was not + fully implemented.

+

Own Id: OTP-6446

+ + +

[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.

+

Own Id: OTP-6450

+ + +

A pattern matching was missing "/binary" resulting in + that the internal function ssh_xfer:decode_acl/2 did not + work as expected.

+

Own Id: OTP-6458

+ + +

[sftp] - read_link/2 did not return the documented value

+

Own Id: OTP-6471

+ + +

Removed debugg printouts from ssh_cli.erl

+

Own Id: OTP-6483

+ + +

[sftp, ssh] - The connection timeout was overridden by an + internal gen_server default timeout.

+

Own Id: OTP-6488 Aux Id: seq10569

+ + +
+
+ +
+ Ssh 0.9.6 + +
+ Fixed Bugs and Malfunctions + + +

Removed debug printout from production code.

+

Own Id: OTP-6348 Aux Id: seq10510

+ + +

[sftpd] - When the sftp client ends the session the + server will now behave correctly and not leave the client + hanging.

+

Own Id: OTP-6349 Aux Id: seq10510

+ + +

[sftpd] - No longer used files were not closed until the + session was ended.

+

Own Id: OTP-6350 Aux Id: seq10514

+ + +

[sftpd] - File rename requests sent by sftp version 3 + clients were not handled.

+

Own Id: OTP-6352 Aux Id: seq10513

+ + +

[sftpd] - Request that did not fit into one ssh message + were not handled.

+

Own Id: OTP-6353 Aux Id: seq10515

+ + +

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.

+

Own Id: OTP-6414

+ + +
+ +
+ Improvements and New Features + + +

[sftpd] - Added new option to specify a callback module + for the sftpd-server file handling. The default callback + module uses file and filelib.

+

Own Id: OTP-6356 Aux Id: seq10519

+ + +
+
+ +
+ Ssh 0.9.5 + +
+ Fixed Bugs and Malfunctions + + +

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.

+

Own Id: OTP-6231

+ + +
+
+ +
+ SSH 0.9.4 + +
+ Reported Fixed Bugs and Malfunctions + + +

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 + ssh module.

+

Also changed some error reports to info reports.

+

Own Id: OTP-6183

+

Aux Id: Seq 10383

+ + +
+
+ +
+ SSH 0.9.3 + +
+ Improvements and New Features + + +

Added way for cli to get peer name

+

Own Id: OTP-6138

+ + +
+
+ +
+ SSH 0.9.2 + +
+ Improvements and New Features + + +

Added some options to listen

+

Own Id: OTP-6070

+ + +
+
+ +
+ SSH 0.9.1 + +
+ Improvements and New Features + + +

Fixes in ssh_sftp, changes of timeout handling, + expand_fun moved to io:setopts

+

Own Id: OTP-5877 Aux Id: OTP-5781

+ + +
+
+ +
+ SSH 0.9 + +
+ Improvements and New Features + + +

The previously undocumented and UNSUPPORTED + application has been updated and documented. This release + of the 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.

+

Also, more cryptographic algorithms have been added to + the application.

+

*** POTENTIAL INCOMPATIBILITY ***

+

Own Id: OTP-5631

+ + +
+
+
+ + + + 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 @@ + + + + +
+ + 20042009 + Ericsson AB. 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. + + + + SSH Release Notes + Jakob Cederlund + + + %VSN% + part_notes.sgml +
+ +

This document describes the changes made to the SSH application. +

+

For information about older versions see + release notes history.

 + + + 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 @@ + + + + +
+ + 2004 + 2007 + Ericsson AB, 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. + + The Initial Developer of the Original Code is Ericsson AB. + + + Ssh + Ingela Anderton Andin + + + + part_notes.xml +
+ + + + 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 @@ + + + + +
+ + 20042009 + Ericsson AB. 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. + + + + SSH Reference Manual + Jakob Cederlund + + 2007-10-06 + %VSN% + application.sgml +
+ +

The SSH application is an erlang implementation of the + secure shell protocol.

+ + + + + + + + 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 @@ + + + + +
+ + 20042009 + Ericsson AB. 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. + + + + ssh + Ingela Anderton Andin + Håkan Mattsson + + Håkan Mattsson + + 2007-10-06 + PA1 +
+ ssh + Main API of the SSH application + +

Interface module for the SSH application

+ + + +
+ COMMON DATA TYPES +

Type definitions that are used more than once in + this module:

+

boolean() = true | false

+

string() = list of ASCII characters

+

ssh_daemon_ref() - opaque to the user + returned by ssh:daemon/[1,2,3]

+

ssh_connection_ref() - opaque to the user + returned by ssh:connect/3

+

ip_address() - {N1,N2,N3,N4} % IPv4 | + {K1,K2,K3,K4,K5,K6,K7,K8} % IPv6

+

subsystem_spec() = {subsystem_name(), {channel_callback(), channel_init_args()}}

+

subsystem_name() = string()

+

channel_callback() = atom() - Name of the erlang module + implementing the subsystem using the ssh_channel behavior see + ssh_channel(3)

+

channel_init_args() = list()

+
+ + + + + close(ConnectionRef) -> ok + Closes a ssh connection + + ConnectionRef = ssh_connection_ref() + +

Closes a ssh connection.

+ + + + + connect(Host, Port, Options) -> + connect(Host, Port, Options, Timeout) -> {ok, ssh_connection_ref()} + | {error, Reason} + Connect to an ssh server. + + Host = string() + Port = integer() + The default is , the registered port for SSH. + Options = [{Option, Value}] + Timeout = infinity | integer(milliseconds) + + +

Connects to an SSH server. No channel is started this is done + by calling ssh_connect:session_channel/2.

+

Options are:

+ + + +

Sets the user directory e.i. the directory containing + ssh configuration files for the user such as + , and + . Defaults to the directory normally + referred to as

+ + + +

When true hosts are added to the + file without asking the user. + Defaults to false. +

+ + + +

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 known_hosts 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.

+ + + +

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 first.

+ + + +

Sets a timeout on the transport layer connection. Defaults to infinity.

+ + + +

Provide a user name. If this option is not given, ssh + reads from the environment ( or + on unix, + on Windows).

+ + + +

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.

+ + + +

Provide a fun for password authentication. The fun + will be called as and + should return or .

+ + + +

Provide a special call-back module for key handling. + The call-back module should be modeled after the + module. The functions that must + be exported are: + , + , + and + . This is considered + somewhat experimental and will be better documented later on.

+ + + +

Allow an existing file-descriptor to be used + (simply passed on to the transport protocol).

 + + + + + + connection_info(ConnectionRef, [Option]) ->[{Option, Value}] + Retrieves information about a connection. + + Option = client_version | server_version | peer + Value = term() + + +

Retrieves information about a connection. +

+ + + + + daemon(Port) -> + daemon(Port, Options) -> + daemon(HostAddress, Port, Options) -> ssh_daemon_ref() + Starts a server listening for SSH connections + on the given port. + + Port = integer() + HostAddress = ip_address() | any + Options = [{Option, Value}] + Option = atom() + Value = term() + + +

Starts a server listening for SSH connections on the given port.

+ +

Options are:

+ + + + 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 [ssh_sftd:subsystem_spec([])] 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. + + pid() | + fun(string() = User, ip_address() = PeerAddr) -> pid()}]]> + + Defines the read-eval-print loop used when a shell is requested + by the client. Example use the + erlang shell: which is + the default behavior. + + + + 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 shell which is much less work than implementing + your own cli channel. + + + +

Sets the system directory, containing the host files + that identifies the host for ssh. The default is + , note that SSH normally + requires the host files there to be readable only by + root.

+ + + +

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. +

+ + + +

Provide a global password that will authenticate any + user. From a security perspective this option makes + the server very vulnerable.

+ + + +

Provide a function for password validation. This is called + with user and password as strings, and should return + if the password is valid and + otherwise.

+ + + +

Allow an existing file-descriptor to be used + (simply passed on to the transport protocol).

 + + + + + + shell(Host) -> + shell(Host, Option) -> + shell(Host, Port, Option) -> _ + + + Host = string() + Port = integer() + Options - see ssh:connect/3 + + +

Starts an interactive shell to an SSH server on the + given Host. The function waits for user input, + and will not return until the remote shell is ended (e.g. on + exit from the shell). +

+ + + + + start() -> + start(Type) -> ok | {error, Reason} + Starts the Ssh application. + + Type = permanent | transient | temporary + Reason = term() + + +

Starts the Ssh application. Default type + is temporary. See also + application(3) + Requires that the crypto application has been started. +

+ + + + + stop() -> ok + Stops the Ssh application. + +

Stops the Ssh application. See also + application(3)

+ + + + + stop_daemon(DaemonRef) -> + stop_daemon(Address, Port) -> ok + Stops the listener and all connections started by + the listener. + + DaemonRef = ssh_daemon_ref() + Address = ip_address() + Port = integer() + + +

Stops the listener and all connections started by + the listener.

+ + + + + stop_listener(DaemonRef) -> + stop_listener(Address, Port) -> ok + Stops the listener, but leaves existing connections started + by the listener up and running. + + DaemonRef = ssh_daemon_ref() + Address = ip_address() + Port = integer() + + +

Stops the listener, but leaves existing connections started + by the listener up and running.

+ + + + + 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 @@ + + + + +
+ + 2009 + 2009 + Ericsson AB, 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. + + The Initial Developer of the Original Code is Ericsson AB. + + + ssh_channel + Ingela Anderton Andin + + + + + + +
+ ssh_channel + Generic Ssh Channel Behavior + + +

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. +

+ + +
+ COMMON DATA TYPES + +

Type definitions that are used more than once in this module + and/or abstractions to indicate the intended use of the data + type:

+ +

boolean() = true | false

+

string() = list of ASCII characters

+

timeout() = infinity | integer() - in milliseconds.

+

ssh_connection_ref() - opaque to the user returned by + ssh:connect/3 or sent to a ssh channel process

+

ssh_channel_id() = integer()

+

ssh_data_type_code() = 1 ("stderr") | 0 ("normal") are + currently valid values see RFC 4254 section 5.2.

+
+ + + + call(ChannelRef, Msg) -> + call(ChannelRef, Msg, Timeout) -> Reply | {error, Reason} + Makes a synchronous call to a channel. + + ChannelRef = pid() + As returned by start_link/4 + Msg = term() + Timeout = timeout() + Reply = term() + Reason = closed | timeout + + +

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 + CallbackModule:handle_call/3 to handle the message. + If the channel process does not exist {error, closed} is returned. +

+ + + + + cast(ChannelRef, Msg) -> ok + Sends an asynchronous message to the channel + ChannelRef and returns ok. + + ChannelRef = pid() + As returned by start_link/4 + Msg = term() + + +

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 + CallbackModule:handle_cast/2 to handle the message. +

+ + + + + enter_loop(State) -> _ + Makes an existing process into a ssh_channel process. + + State = term() - as returned by ssh_channel:init/1 + + +

Makes an existing process into a ssh_channel + process. Does not return, instead the calling process will + enter the ssh_channel process receive loop and become a + ssh_channel process. The process must have been started using + one of the start functions in proc_lib, see proc_lib(3). The + user is responsible for any initialization of the process + and needs to call ssh_channel:init/1. +

+ + + + + init(Options) -> {ok, State} | {ok, State, Timeout} | {stop, Reason} + Initiates a ssh_channel process. + + Options = [{Option, Value}] + + +

+ The following options must be present: +

+ + + The module that implements the channel behavior. + + + The list of arguments to the callback modules + init function. + + + Reference to the ssh connection. + + + Id of the ssh channel. + + + +

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 proc_lib instead calling + ssh_channel:start/4 or ssh_channel:start_link/4

+ + + + + + reply(Client, Reply) -> _ + Send a reply to a client. + + Client - opaque to the user, see explanation below + Reply = term() + + +

This function can be used by a channel to explicitly send a + reply to a client that called call/[2,3] when the reply + cannot be defined in the return value of + CallbackModule:handle_call/3.

+

Client must be the From argument provided to + the callback function handle_call/3. + Reply is an arbitrary term, + which will be given back to the client as the return value of + ssh_channel:call/[2,3].

+ + + + + start(SshConnection, ChannelId, ChannelCb, CbInitArgs) -> + start_link(SshConnection, ChannelId, ChannelCb, CbInitArgs) -> + {ok, ChannelRef} | {error, Reason} + Starts a processes that handles a ssh channel. + + SshConnection = ssh_connection_ref() + ChannelId = ssh_channel_id() + As returned by ssh_connection:session_channel/[2,4] + ChannelCb = atom() + The name of the module implementing the service specific parts + of the channel. + CbInitArgs = [term()] + Argument list for the init function in the callback module. + ChannelRef = pid() + + +

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. +

+ + + + + +
+ CALLBACK FUNCTIONS + +

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 + ssh:daemon/[2, 3]. The + handle_call/3, handle_cast/2 code_change/3 and enter_loop/1 + functions are only relevant when implementing a client side + channel.

+
+ +
+ + CALLBACK TIMEOUTS +

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 Timeout milliseconds. A timeout + is represented by the atom timeout which should be handled + by the handle_msg/2 + callback function. The atom infinity can be used to wait + indefinitely, this is the default value.

+
+ + + + CallbackModule:code_change(OldVsn, State, Extra) -> {ok, + NewState} + Converts process state when code is changed. + + Converts process state when code is changed. + + +

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 + {update,Module,Change,...} where + Change={advanced,Extra} is given in the appup + file. See OTP + Design Principles 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. +

+ +

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.

 + +

In the case of an upgrade, OldVsn is Vsn, and + in the case of a downgrade, OldVsn is + {down,Vsn}. Vsn is defined by the vsn + attribute(s) of the old version of the callback module + Module. If no such attribute is defined, the version + is the checksum of the BEAM file.

+

State is the internal state of the channel.

+

Extra is passed as-is from the {advanced,Extra} + part of the update instruction.

+

The function should return the updated internal state.

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

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

+

For more detailed information on timeouts see the section + CALLBACK TIMEOUTS.

+ + + + + CallbackModule:handle_call(Msg, From, State) -> Result + Handles messages sent by calling + ssh_channel:call/[2,3] + + Msg = term() + From = opaque to the user should be used as argument to + ssh_channel:reply/2 + State = term() + Result = {reply, Reply, NewState} | {reply, Reply, NewState, Timeout} + | {noreply, NewState} | {noreply , NewState, Timeout} + | {stop, Reason, Reply, NewState} | {stop, Reason, NewState} + Reply = term() - will be the return value of ssh_channel:call/[2,3] + Timeout = timeout() + NewState = term() - a possible updated version of State + Reason = term() + + +

Handles messages sent by calling + ssh_channel:call/[2,3] +

+

For more detailed information on timeouts see the section + CALLBACK TIMEOUTS.

+ + + + + CallbackModule:handle_cast(Msg, State) -> Result + Handles messages sent by calling + ssh_channel:cact/2 + + Msg = term() + State = term() + Result = {noreply, NewState} | {noreply, NewState, Timeout} + | {stop, Reason, NewState} + NewState = term() - a possible updated version of State + Timeout = timeout() + Reason = term() + + +

Handles messages sent by calling + ssh_channel:cast/2 +

+

For more detailed information on timeouts see the section + CALLBACK TIMEOUTS.

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

Handle other messages than ssh connection protocol, call or + cast messages sent to the channel. +

+ +

Possible erlang 'EXIT'-messages should be handled by this + function and all channels should handle the following message.

+ + + + 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}. + + + + + + + CallbackModule:handle_ssh_msg(Msg, State) -> {ok, State} | {stop, + ssh_channel_id(), State} + Handles ssh connection protocol messages. + + Msg = {ssh_cm, ssh_connection_ref(), SshMsg} + SshMsg = tuple() - see message list below + State = term() + + +

Handles ssh connection protocol messages that may need + service specific attention. +

+ +

All channels should handle the following messages. For + channels implementing subsystems the handle_ssh_msg-callback + will not be called for any other messages.

+ + + + Data has arrived on the channel. When the callback + for this message returns the channel behavior will adjust + the ssh flow control window. + + + Indicteas that the other side will not send any more + data. + + + 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. + + + 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 + + + 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. + + +

Channels implementing a shell and command execution on the server side + should also handle the following messages.

+ + + + 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 + WantReply as the second argument. + + + + 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 + WantReply as the second argument. + + + 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 Opcode in the + TerminalModes 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 OP code: 53, mnemonic name ECHO erlang atom: + echo. Note that before the callback returns it should + call the function ssh_connection:reply_request/4 with the + boolean value of WantReply as the second + argument. + + + 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 + WantReply as the second argument. + + + + 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. + + +

The following message is completely taken care of by the + ssh channel behavior

+ + + + 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. + + + + + + CallbackModule:terminate(Reason, State) -> _ + + + Reason = term() + State = term() + + +

This function is called by a channel process when it is + about to terminate. Before this function is called ssh_connection:close/2 + will be called if it has not been called earlier. + This function should be the opposite of CallbackModule:init/1 + and do any necessary cleaning up. When it returns, the + channel process terminates with reason Reason. The return value is + ignored. +

+ + + + + + diff --git a/lib/ssh/doc/src/ssh_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 @@ + + + + +
+ + 2008 + 2008 + Ericsson AB, 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. + + The Initial Developer of the Original Code is Ericsson AB. + + + ssh_connection + Ingela Anderton Andin + + + + + + +
+ ssh_connection + This module provides an API to the ssh connection protocol. + + +

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.

+ + +
+ COMMON DATA TYPES +

Type definitions that are used more than once in this module and/or + abstractions to indicate the intended use of the data type:

+ +

boolean() = true | false

+

string() = list of ASCII characters

+

timeout() = infinity | integer() - in milliseconds.

+

ssh_connection_ref() - opaque to the user returned by + ssh:connect/3 or sent to a ssh channel processes

+

ssh_channel_id() = integer()

+

ssh_data_type_code() = 1 ("stderr") | 0 ("normal") are + currently valid values see RFC 4254 section 5.2.

+

ssh_request_status() = success | failure

+
+ +
+ MESSAGES SENT TO CHANNEL PROCESSES + +

As a result of the ssh connection protocol messages on the form + + 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 handle_ssh_msg/2

+
+ + + + + adjust_window(ConnectionRef, ChannelId, NumOfBytes) -> ok + Adjusts the ssh flowcontrol window. + + ConnectionRef = ssh_connection_ref() + ChannelId = ssh_channel_id() + NumOfBytes = integer() + + +

Adjusts the ssh flowcontrol window.

+ +

This will be taken care of by the ssh_channel + behavior when the callback + handle_ssh_msg/2 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.

 + + + + + close(ConnectionRef, ChannelId) -> ok + Sends a close message on the channel ChannelId. + + ConnectionRef = ssh_connection_ref() + ChannelId = ssh_channel_id() + + +

Sends a close message on the channel ChannelId +

+ +

This function will be called by the ssh channel + behavior when the channel is terminated see ssh_channel(3) and should + normally not be called explicitly.

 + + + + + exec(ConnectionRef, ChannelId, Command, TimeOut) -> ssh_request_status() + Will request that the server start the + execution of the given command. + + ConnectionRef = ssh_connection_ref() + ChannelId = ssh_channel_id() + Command = string() + Timeout = timeout() + + +

Will request that the server start the execution of the + given command, the result will be received as:

+ + + N X {ssh_cm, + ssh_connection_ref(), {data, ssh_channel_id(), ssh_data_type_code(), + binary() = Data}} + The result of executing the command may be only one line + or thousands of lines depending on the command. + + 1 X {ssh_cm, ssh_connection_ref(), {eof, ssh_channel_id()}} + Indicates that no more data will be sent. + + 0 or 1 X {ssh_cm, + ssh_connection_ref(), {exit_signal, + ssh_channel_id(), string() = ExitSignal, string() = ErrorMsg, string() = LanguageString}} + Not all systems send signals. For details on valid string + values see RFC 4254 section 6.10 + + 0 or 1 X {ssh_cm, ssh_connection_ref(), {exit_status, + ssh_channel_id(), integer() = ExitStatus}} + It is recommended by the ssh connection protocol that this + message shall be sent, but that may not always be the case. + + 1 X {ssh_cm, ssh_connection_ref(), + {closed, ssh_channel_id()}} + Indicates that the ssh channel started for the + execution of the command has now been shutdown. + + +

These message should be handled by the + client. The ssh channel + behavior can be used when writing a client. +

+ + + + + + exit_status(ConnectionRef, ChannelId, Status) -> ok + Sends the exit status of a command to the client. + + ConnectionRef = ssh_connection_ref() + ChannelId = ssh_channel_id() + Status = integer() + + +

Sends the exit status of a command to the client.

+ + + + + reply_request(ConnectionRef, WantReply, Status, CannelId) -> ok + Send status replies to requests that want such replies. + + ConnectionRef = ssh_connection_ref() + WantReply = boolean() + Status = ssh_request_status() + ChannelId = ssh_channel_id() + + +

Sends status replies to requests where the requester has + stated that they want a status report e.i . WantReply = true, + if WantReply is false calling this function will be a + "noop". Should be called after handling an ssh connection + protocol message containing a WantReply boolean + value. See the ssh_channel behavior callback handle_ssh_msg/2 +

+ + + + + send(ConnectionRef, ChannelId, Data) -> + send(ConnectionRef, ChannelId, Data, Timeout) -> + send(ConnectionRef, ChannelId, Type, Data) -> + send(ConnectionRef, ChannelId, Type, Data, TimeOut) -> + ok | {error, timeout} + Sends channel data + + ConnectionRef = ssh_connection_ref() + ChannelId = ssh_channel_id() + Data = binary() + Type = ssh_data_type_code() + Timeout = timeout() + + +

Sends channel data. +

+ + + + + send_eof(ConnectionRef, ChannelId) -> ok + Sends eof on the channel ChannelId. + + ConnectionRef = ssh_connection_ref() + ChannelId = ssh_channel_id() + + +

Sends eof on the channel ChannelId. +

+ + + + + session_channel(ConnectionRef, Timeout) -> + session_channel(ConnectionRef, InitialWindowSize, + MaxPacketSize, Timeout) -> {ok, ssh_channel_id()} | {error, Reason} + 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. + + ConnectionRef = ssh_connection_ref() + InitialWindowSize = integer() + MaxPacketSize = integer() + Timeout = timeout() + Reason = term() + + +

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. +

+ + + + + setenv(ConnectionRef, ChannelId, Var, Value, TimeOut) -> ssh_request_status() + Environment variables may be passed to the + shell/command to be started later. + + ConnectionRef = ssh_connection_ref() + ChannelId = ssh_channel_id() + Var = string() + Value = string() + Timeout = timeout() + + +

Environment variables may be passed to the shell/command to be + started later. +

+ + + + + shell(ConnectionRef, ChannelId) -> ssh_request_status() + + Will request that the user's default shell (typically + defined in /etc/passwd in UNIX systems) be started at the other + end. + + ConnectionRef = ssh_connection_ref() + ChannelId = ssh_channel_id() + + +

Will request that the user's default shell (typically + defined in /etc/passwd in UNIX systems) be started at the + other end. +

+ + + + + subsystem(ConnectionRef, ChannelId, Subsystem, Timeout) -> ssh_request_status() + + + ConnectionRef = ssh_connection_ref() + ChannelId = ssh_channel_id() + Subsystem = string() + Timeout = timeout() + + +

Sends a request to execute a predefined subsystem. +

+ + + + + + 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 @@ + + + + +
+ + 20052009 + Ericsson AB. 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. + + + + ssh_sftp + Jakob Cederlund + + 1 + + + 2005-09-22 + PA1 + ssh_sftp.sgml +
+ ssh_sftp + SFTP client. + +

This module implements an SFTP (SSH FTP) client. SFTP is a + secure, encrypted file transfer service available for + SSH.

+ + +
+ COMMON DATA TYPES +

Type definitions that are used more than once in this module + and/or abstractions to indicate the intended use of the data type: +

+

ssh_connection_ref() - opaque to the user + returned by ssh:connect/3

+

timeout() = infinity | integer() - in milliseconds.

+
+ +
+ TIMEOUTS +

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.

+
+ + + + start_channel(ConnectionRef) -> + start_channel(ConnectionRef, Options) -> + start_channel(Host, Options) -> + start_channel(Host, Port, Options) -> {ok, Pid} | {ok, Pid, ConnectionRef} | + {error, Reason} + Starts a sftp client + + Host = string() + ConnectionRef = ssh_connection_ref() + Port = integer() + Options = [{Option, Value}] + Reason = term() + + +

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.

+ +

Options are:

+ + + +

The timeout is passed to the ssh_channel start function, + and defaults to infinity.

+ + +

All other options are directly passed to + ssh:connect/3 or ignored if a + connection is already provided.

+ + + + + stop_channel(ChannelPid) -> ok + Stops the sftp client channel. + + ChannelPid = pid() + + +

Stops a sftp channel. If the ssh connection should be closed + call ssh:close/1.

+ + + + + read_file(ChannelPid, File) -> + read_file(ChannelPid, File, Timeout) -> {ok, Data} | {error, Reason} + Read a file + + ChannelPid = pid() + File = string() + Data = binary() + Timeout = timeout() + Reason = term() + + +

Reads a file from the server, and returns the data in a binary, + like .

+ + + + write_file(ChannelPid, File, Iolist) -> + write_file(ChannelPid, File, Iolist, Timeout) -> ok | {error, Reason} + Write a file + + ChannelPid = pid() + File = string() + Iolist = iolist() + Timeout = timeout() + Reason = term() + + +

Writes a file to the server, like . + The file is created if it's not there.

+ + + + list_dir(ChannelPid, Path) -> + list_dir(ChannelPid, Path, Timeout) -> {ok, Filenames} | {error, Reason} + List directory + + ChannelPid = pid() + Path = string() + Filenames = [Filename] + Filename = string() + Timeout = timeout() + Reason = term() + + +

Lists the given directory on the server, returning the + filenames as a list of strings.

+ + + + open(ChannelPid, File, Mode) -> + open(ChannelPid, File, Mode, Timeout) -> {ok, Handle} | {error, Reason} + Open a file and return a handle + + ChannelPid = pid() + File = string() + Mode = [Modeflag] + Modeflag = read | write | creat | trunc | append | binary + Timeout = timeout() + Handle = term() + Reason = term() + + +

Opens a file on the server, and returns a handle that + is used for reading or writing.

+ + + + opendir(ChannelPid, Path) -> + opendir(ChannelPid, Path, Timeout) -> {ok, Handle} | {error, Reason} + Open a directory and return a handle + + ChannelPid = pid() + Path = string() + Timeout = timeout() + Reason = term() + + +

Opens a handle to a directory on the server, the handle + is used for reading directory contents.

+ + + + close(ChannelPid, Handle) -> + close(ChannelPid, Handle, Timeout) -> ok | {error, Reason} + Close an open handle + + ChannelPid = pid() + Handle = term() + Timeout = timeout() + Reason = term() + + +

Closes a handle to an open file or directory on the server.

+ + + + read(ChannelPid, Handle, Len) -> + read(ChannelPid, Handle, Len, Timeout) -> {ok, Data} | eof | {error, Error} + pread(ChannelPid, Handle, Position, Len) -> + pread(ChannelPid, Handle, Position, Len, Timeout) -> {ok, Data} | eof | {error, Error} + Read from an open file + + ChannelPid = pid() + Handle = term() + Position = integer() + Len = integer() + Timeout = timeout() + Data = string() | binary() + Reason = term() + + +

Reads bytes from the file referenced by + . Returns , or , or + . If the file is opened with , + is a binary, otherwise it is a string.

+

If the file is read past eof, only the remaining bytes + will be read and returned. If no bytes are read, + is returned.

+

The function reads from a specified position, + combining the and functions.

+ + + + aread(ChannelPid, Handle, Len) -> {async, N} | {error, Error} + apread(ChannelPid, Handle, Position, Len) -> {async, N} | {error, Error} + Read asynchronously from an open file + + ChannelPid = pid() + Handle = term() + Position = integer() + Len = integer() + N = term() + Reason = term() + + +

Reads from an open file, without waiting for the result. If the + handle is valid, the function returns , where N + is a term guaranteed to be unique between calls of . + The actual data is sent as a message to the calling process. This + message has the form , where + is the result from the read, either , + or , or .

+

The function reads from a specified position, + combining the and functions.

+ + + + write(ChannelPid, Handle, Data) -> + write(ChannelPid, Handle, Data, Timeout) -> ok | {error, Error} + pwrite(ChannelPid, Handle, Position, Data) -> ok + pwrite(ChannelPid, Handle, Position, Data, Timeout) -> ok | {error, Error} + Write to an open file + + ChannelPid = pid() + Handle = term() + Position = integer() + Data = iolist() + Timeout = timeout() + Reason = term() + + +

Write to the file referenced by . + The file should be opened with or + flag. Returns if successful and + otherwise.

+

Typical error reasons are:

+ + + +

The file is not opened for writing.

+ + + +

There is a no space left on the device.

+ + + + + + awrite(ChannelPid, Handle, Data) -> ok | {error, Reason} + apwrite(ChannelPid, Handle, Position, Data) -> ok | {error, Reason} + Write asynchronously to an open file + + ChannelPid = pid() + Handle = term() + Position = integer() + Len = integer() + Data = binary() + Timeout = timeout() + Reason = term() + + +

Writes to an open file, without waiting for the result. If the + handle is valid, the function returns , where N + is a term guaranteed to be unique between calls of + . The result of the operation is sent + as a message to the calling process. This message has the form + , where is the result + from the write, either , or .

+

The writes on a specified position, combining + the and operations.

+ + + + position(ChannelPid, Handle, Location) -> + position(ChannelPid, Handle, Location, Timeout) -> {ok, NewPosition | {error, Error} + Seek position in open file + + ChannelPid = pid() + Handle = term() + Location = Offset | {bof, Offset} | {cur, Offset} | {eof, Offset} | bof | cur | eof + Offset = int() + Timeout = timeout() + NewPosition = integer() + Reason = term() + + +

Sets the file position of the file referenced by . + Returns (as an absolute offset) if + successful, otherwise . is + one of the following:

+ + + +

The same as .

+ + + +

Absolute offset.

+ + + +

Offset from the current position.

+ + + +

Offset from the end of file.

+ + + +

The same as above with 0.

+ + + + + + read_file_info(ChannelPid, Name) -> + read_file_info(ChannelPid, Name, Timeout) -> {ok, FileInfo} | {error, Reason} + Get information about a file + + ChannelPid = pid() + Name = string() + Handle = term() + Timeout = timeout() + FileInfo = record() + Reason = term() + + +

Returns a record from the file specified by + or , like .

+ + + + read_link_info(ChannelPid, Name) -> {ok, FileInfo} | {error, Reason} + read_link_info(ChannelPid, Name, Timeout) -> {ok, FileInfo} | {error, Reason} + Get information about a symbolic link + + ChannelPid = pid() + Name = string() + Handle = term() + Timeout = timeout() + FileInfo = record() + Reason = term() + + +

Returns a record from the symbolic + link specified by or , like + .

+ + + + write_file_info(ChannelPid, Name, Info) -> + write_file_info(ChannelPid, Name, Info, Timeout) -> ok | {error, Reason} + Write information for a file + + ChannelPid = pid() + Name = string() + Info = record() + Timeout = timeout() + Reason = term() + + +

Writes file information from a record to the + file specified by , like .

+ + + + read_link(ChannelPid, Name) -> + read_link(ChannelPid, Name, Timeout) -> {ok, Target} | {error, Reason} + Read symbolic link + + ChannelPid = pid() + Name = string() + Target = string() + Reason = term() + + +

Read the link target from the symbolic link specified + by , like .

+ + + + make_symlink(ChannelPid, Name, Target) -> + make_symlink(ChannelPid, Name, Target, Timeout) -> ok | {error, Reason} + Create symbolic link + + ChannelPid = pid() + Name = string() + Target = string() + Reason = term() + + +

Creates a symbolic link pointing to with the + name , like .

+ + + + rename(ChannelPid, OldName, NewName) -> + rename(ChannelPid, OldName, NewName, Timeout) -> ok | {error, Reason} + Rename a file + + ChannelPid = pid() + OldName = string() + NewName = string() + Timeout = timeout() + Reason = term() + + +

Renames a file named , and gives it the name + , like

+ + + + delete(ChannelPid, Name) -> + delete(ChannelPid, Name, Timeout) -> ok | {error, Reason} + Delete a file + + ChannelPid = pid() + Name = string() + Timeout = timeout() + Reason = term() + + +

Deletes the file specified by , like +

+ + + + make_dir(ChannelPid, Name) -> + make_dir(ChannelPid, Name, Timeout) -> ok | {error, Reason} + Create a directory + + ChannelPid = pid() + Name = string() + Timeout = timeout() + Reason = term() + + +

Creates a directory specified by . should + be a full path to a new directory. The directory can only be + created in an existing directory.

+ + + + del_dir(ChannelPid, Name) -> + del_dir(ChannelPid, Name, Timeout) -> ok | {error, Reason} + Delete an empty directory + + ChannelPid = pid() + Name = string() + Timeout = timeout() + Reason = term() + + +

Deletes a directory specified by . The directory + should be empty.

+ + + + + + + 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 @@ + + + + +
+ + 20052009 + Ericsson AB. 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. + + + + ssh_sftpd + Ingela Anderton Andin + + 1 + + + 2005-09-22 + PA1 + ssh_sftpd.sgml +
+ ssh_sftpd + Specifies a channel process to handle a sftp subsystem. + +

Specifies a channel process to handle a sftp subsystem.

+ + +
+ COMMON DATA TYPES +

subsystem_spec() = {subsystem_name(), {channel_callback(), channel_init_args()}}

+

subsystem_name() = "sftp"

+

channel_callback() = atom() - Name of the erlang module implementing the + subsystem using the ssh_channel behavior see + ssh_channel(3)

+

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

+
+ + + subsystem_spec(Options) -> subsystem_spec() + Returns the subsystem specification that allows an ssh daemon to handle the subsystem "sftp". + + Options = [{Option, Value}] + + +

Should be used together with ssh:daemon/[1,2,3]

+

Options are:

+ + + +

Sets the initial current working directory for the + server.

+ + + +

Determines which module to call for communicating with + the file server. Default value is ssh_sftpd_file 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.

+ + + +

The default value is 0, which means that there is no upper limit. + If supplied, the number of filenames returned to the sftp client per READDIR + request, is limited to at most the given value.

+ + + +

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 /tmp the user will see this + directory as / and if the user does cd /etc + the user will end up in /tmp/etc. +

+ + + + + + + diff --git a/lib/ssh/doc/src/user_guide.gif b/lib/ssh/doc/src/user_guide.gif new file mode 100644 index 0000000000..e6275a803d Binary files /dev/null and b/lib/ssh/doc/src/user_guide.gif differ -- cgit v1.2.3