svn commit: r762955 - /synapse/trunk/java/src/site/apt/transports.apt

[ve...@apache.org]

Author: veithen
Date: Tue Apr  7 20:47:56 2009
New Revision: 762955

URL: http://svn.apache.org/viewvc?rev=762955&view=rev
Log:
Added some more documentation about the VFS transport.

Modified:
    synapse/trunk/java/src/site/apt/transports.apt

Modified: synapse/trunk/java/src/site/apt/transports.apt
URL: http://svn.apache.org/viewvc/synapse/trunk/java/src/site/apt/transports.apt?rev=762955&r1=762954&r2=762955&view=diff
==============================================================================
--- synapse/trunk/java/src/site/apt/transports.apt (original)
+++ synapse/trunk/java/src/site/apt/transports.apt Tue Apr  7 20:47:56 2009
@@ -182,7 +182,10 @@
   The VFS transport listener receives messages dropped in a given local or remote file system
   location. The location is specified by a URL that either identifies a single file or a directory.
   The transport listener will periodically poll the specified location and process any file(s)
-  found. After a file has been processed it will be deleted or moved to another location.
+  found. After a file has been processed it will be deleted or moved to another location. Note that
+  this is absolutely mandatory to prevent the listener from processing files multiple times.
+  Therefore the VFS transport listener can only be used in situations where it has write access to
+  the file system location and where deleting or moving the dropped files is acceptable.
 
   The transport is based on {{{http://commons.apache.org/vfs/}Apache Commons VFS}} and supports any
   protocol for which a VFS provider is available. The transport is preconfigured with providers
@@ -211,6 +214,11 @@
 </proxy>
 +-------------------------------------+  
 
+  In this example the file system location <<<file:///var/spool/synapse/in>>> is explicitly bound
+  to <<<MyVFSService>>>, i.e. any message dropped in that location will be predispatched to that
+  service, bypassing any other configured dispatch mechanisms that would apply to messages received
+  through HTTP.
+  
   The VFS transport recognizes the following service parameters:
 
   [<<<transport.vfs.FileURI>>> (Required)]
@@ -340,7 +348,43 @@
 +-------------------------------------+  
 <property action="set" name="OUT_ONLY" value="true"/>
 +-------------------------------------+  
+
+* {Using SFTP}
+
+  To avoid man-in-the-middle attacks, SSH clients will only connect to hosts with a known
+  host key. When connecting for the first time to an SSH server, a typical command line SSH client
+  would request confirmation from the user to add the server and its fingerprint to the list of known
+  hosts.
+  
+  The VFS transports supports SFTP through the {{{http://www.jcraft.com/jsch/}JSch}} library
+  and this library also requires a list of known hosts. Since Synapse is not an interactive
+  process, it can't request confirmation from the user and is therefore unable to automatically add
+  a host to the list. This implies that the list of known hosts must be set up manually before the
+  transport can connect.
+
+  Jsch loads the list of known hosts from a file called <<<known_hosts>>> in the <<<.ssh>>>
+  subdirectory of the user's home directory, i.e. <<<$HOME/.ssh>>> in Unix and
+  <<<%HOMEPATH%\\.ssh>>> in Windows. The location and format of this file are compatible with
+  the {{{http://www.openssh.com/}OpenSSH}} client.
+
+  Since the file not only contains a list of hostnames but also the fingerprints of their host keys,
+  the easiest way to add a new host to that file is to simply use the OpenSSH client to open an SSH
+  session on the target host. The client will then ask to add the credentials to the
+  <<<known_hosts>>> file. Note that if the SSH server is configured to only allow SFTP sessions,
+  but no interactive sessions, the connection will actually fail. Since this doesn't rollback
+  the change to the <<<known_hosts>>> file, this error can be ignored.
+
+* {Known issues}
+
+  The VFS listener will start reading a file as soon as it appears in the configured location.
+  To avoid processing half written files, the creation of these files should be made atomic.
+  On most platforms this can be achieved by writing the data to a temporary file and then
+  moving the file to the target location. Note however that a move operation is only atomic
+  if the source and destination are on the same physical file system. The location for the
+  temporary file should be chosen with that constraint in mind.
   
+  It should also be noted that the VFS transport sender doesn't create files atomically.
+
 {FIX transport}
 
   A general overview about the FIX transport can be found in the following articles: