This module delivers integration of the VFS Shell with Apache MINA SSHD. Apache MINA SSHD provides a Java implementation for an SSH Server and Client with support for SCP and SFTP.
This combination allows secure remote access to a VFS Shell using for example Putty, Cygwin or a *nix based ssh client.
Warning: the code is not yet tested enough to use in a production environment!
With the SCP and SFTP support you can use VFS SSHD server also for file transfers.
To use it, the mina sshd jars and all dependecies, the vfs jar and all its dependencies and all the vfs shell and vfs utils jars must be added to your classpath.
If you download the VFS SSHD server distribution you will have all you need to run the server. Additional VFS plugins and custom commands or scripts are easily added.
You can also just use the VFS enabled shell, SCP command or SFTP subsystem in your own custom server, see Components.
You can start the shell server using:
java org.vfsutils.shell.sshd.Server [--port=<port>] [--domain=<domain>] [--path=<path>] [--virtual] root java org.vfsutils.shell.sshd.Server --port=2222 --path=/$USER dctm://mydocbase
You can use the domain option if you need to specify the domain to login into your VFS. The path is the path within the root that you want the user to start in. You can use the $USER variable in the path; it will be replaced by the user name. If you specify the virtual flag then the root will act as the root of the file system even when it is not the real root; e.g. file:///d:/vfswork/root as virtual root would mean that the root the users see it as / and can not see file:///d:/vfswork or file:///d:/.
The VFS Shell that is started is a Boxed Shell which means that it does not allow the user to escape the configured file system. To achieve this not all commands are supported and some commands behave a little different. E.g. the 'open' command will not allow opening another VFS and the 'register' command only allows registering VFS scripts.
You can customize the engine in several ways. First of all, you can make changes on the Java level using a beanshell script that has access to the engine. See the documentation for the VFS Shell for this. The file that is read is called
vfs-server-custom-init.bsh
You can change the name of the script using an envionment variable:
-Dorg.dctmvfs.vfs.server.customscript=my-custom-init.bsh
If you set the environment variable to none then the script will be ignored.
-Dorg.dctmvfs.vfs.server.customscript=none
On a more functional level you can use a VFS script to set variables, to register additional commands or to unregister existing commands.
There are two of such scripts, the first one is read from the startup dir of the VFS Server and has access to the fully functional register command, this script is called
.vfsserverrc
The users working folder has not been set yet when this script is called, the working folder is the servers startup folder.
After the script has been executed the working directory will be set to the user root within the virtual file system.
Note: Scripts from another filesystem than the filesystem of the user must be registered as cached because these files can not be resolved within the session of the user.
The second script is read from within the users start directory in the virtual file system. Depending on your file system and startup options this script can be user specific, much like .bashrc etc. Since the idea is that users can change this script it has access to the 'boxed' register command that only allows registering VFS scripts, and no classes or Beanshell scripts. This script is called
.vfsshellrc
(Note: if you added a register command yourself in the engine customization script then it will be available for the second script, but the first script will temporarily use the default register command.)
You can change the name of the second script or avoid loading it by providing the environment variable:
-Dorg.dctmvfs.vfs.server.userscript=.vfsuserrc
If you set it to none then no script will be loaded.
-Dorg.dctmvfs.vfs.server.userscript=none
The different components of the project can be used independently.
The VfsPasswordAuthenticator will delegate authentication to a VFS provider. To create it you need to give it a VFS FileSystemManager, a root path (typically absolute, with scheme but without user name; e.g. ftp:///ftpservername or dctm://docbase) and a flag indicating whether the root must be a seen as a new virtual filesystem (typically for mounting a part of a local filesystem). If you want to have authentication the root path must point to a provider that supports it; if you pass file://d:/temp then any user name or password will do to login!
The VfsShellFactory creates shells based on the VFS Shell. To initialize it you must pass a VFS FileSystemManagerFactory. Optionally you can give a path as well. The behaviour will depend on whether a root and/or path are passed through the session attributes as well. If you pass a session attribute for the path then it will overwrite the path given to the VfsShellFactory. If you pass a session attribute for the root then the path will be resolved relative to the root; otherwise it will be interpreted as an absolute path.
In other words, when there is no root passed in the session, the path you give must be absolute (e.g. file://sshd_root; otherwise it must be relative.
If you create your own PasswordAuthenticator you can choose whether you want to pass these session attributes or not. You can then also specify the username and password in the rootpath if you want to run the shell under a fixed account.
The VfsPasswordAuthenticator will insert only the root attribute in the session. If you want the user to start in a certain directory other than the root then you should pass the relative path in the constructor.
The path that is given can contain a $USER token which will be replaced by the user name. With this you can make users start in their own home folder.
The VfsScpCommandFactory creates VfsScpCommands when "scp" is the requested command. It is based on the SSHD ScpCommandFactory. You must pass it a VFS FileSystemManagerFactory. Just as the VfsShellFactory it will look for the root attribute in the session. If your PasswordAuthenticator does not set it then you must give a path to the ScpCommandFactory that indicates the root from where the requested files will be resolved; it should be absolute including the scheme (e.g. file:///sshd_root)