README.md in vagrant-sshfs-0.0.8 vs README.md in vagrant-sshfs-1.0.0

@@ -1,69 +1,151 @@
 # vagrant-sshfs
 
-A Vagrant plugin to mount a folder from the box to the host using sshfs.
+This is a vagrant plugin that adds synced folder support for mounting
+folders from the Vagrant host into the Vagrant guest via
+[SSHFS](https://github.com/libfuse/sshfs). It does this by executing
+the `SSHFS` client software within the guest, which creates and SSH
+connection from the Vagrant guest back to the Vagrant host. 
 
-## Why
+The benefits of this approach:
+- Works on any host platform and hypervisor type
+    - Windows, Linux, Mac OS X
+    - Virtualbox, Libvirt, Hyper-V, VMWare
 
-Common solutions for sharing folders with Vagrant include synced folder, which is pretty slow when dealing with many files, and NFS. NFS didn't work for me because of encrypted disk restrictions. An alternative was to mount a folder in the host machine pointing to a folder in the box with sshfs.
+The drawbacks with this approach:
+- Performance is worse than an implementation like NFS
+- There must be an SSH daemon running on the Vagrant host 
+- The Vagrant guest must be able to SSH to the Vagrant host and authenticate.
 
-## Installation
+Running an SSH daemon on the host is mainly only a problem on the
+Windows platform. [Here](http://docs.oracle.com/cd/E24628_01/install.121/e22624/preinstall_req_cygwin_ssh.htm#EMBSC150) 
+is a guide for intalling the cygwin SSH daemon on Windows.
 
-`vagrant plugin install vagrant-sshfs`
+In order to authenticate back to the host daemon you must either
+provide your password or use SSH keys and agent forwarding.
 
-## Usage
+## History
 
-In the `Vagrantfile`, add a configuration like this:
+The inspiration for this plugin came from [Fabio Kreusch](https://github.com/fabiokr)
+and his [code](https://github.com/fabiokr/vagrant-sshfs) for the original 
+vagrant-sshfs Vagrant plugin. The goal of this plugin (as opposed to
+the old implementation) is to implement SSHFS as a synced folder
+plugin just like the other synced folder plugins (NFS/RSYNC/SMB/VirtualBox).
 
-`config.sshfs.paths = { "src" => "mountpoint" }`
+This plugin was developed mainly by copying the code from the NFS synced 
+folder plugin from the Vagrant core code and molding it to fit SSHFS.
 
-`src` is the source absolute path to the folder in the box, `mountpoint` is the folder in the host machine. `mountpoint` can be an absolute path, or relative to the `Vagrantfile`.
+## Getting Started
 
-By default it will use the Vagrant ssh username. You can change that with the following:
+In order to use this synced folder implementation perform the
+following steps:
 
-`config.sshfs.username = "theusername"`
+### Install plugin
 
-The plugin is enabled by default, so it will run everytime the machine starts. In case that is not desired, you can disabled that with the following configuration:
+In order to install the plugin simply run the following command:
 
-`config.sshfs.enabled = false`
+```
+# vagrant plugin install vagrant-sshfs
+```
 
-The plugin creates missing folder by default, if you want to be prompted, you can disable it with the following configuration:
+### Add SSHFS synced folder in Vagrantfile
 
-`config.sshfs.prompt_create_folders = false`
+Edit your Vagrantfile to specify a folder to mount from the host into
+the guest:
 
-The plugin is creating folders using sudo by default, In case that is not desired, you can disable that with the following configuration:
+```
+config.vm.synced_folder "/path/on/host", "/path/on/guest", type: "sshfs"
+```
 
-`config.sshfs.sudo = false`
+For more options that you can add see the [Options](#options) section.
 
-To manually run it, you can use the `sshfs` command. Please check `vagrant -h`.
+### Recommended: Using Keys and Forwarding SSH Agent
 
-## Issues
 
-### Connection reset by peer
+If you want a completely non-interactive experience you can either
+hard code your password in the Vagrantfile or you can use SSH keys.
 
-In case you are getting "Connection reset by peer" errors, it might be the case that you already have a host configuration under your `~/.ssh/know_hosts` for the given ip, and you are using the same ip with a different machine. If that is the case, you can set a `StrictHostKeyChecking no` under that ip to skip the check:
+If `key1` is a key that is authorized to log in to the Vagrant host
+,meaning there is an entry for `key1` in the `~/.ssh/authorized_keys` 
+file, then you should be able to do the following to have a
+non-interactive experience with SSH keys and agent forwarding:
 
+Modify the Vagrantfile to forward your SSH agent:
+
 ```
-Host 127.0.0.1
-StrictHostKeyChecking no
+config.ssh.forward_agent = 'true'
 ```
 
-### Mounting on guest (box)
+Now set up your agent and add your key to the agent:
 
-You need to have `sshfs` installed on guest machine and ssh server on host.
+```
+# eval $(ssh-agent)
+# ssh-add /path/to/key1
+```
 
-To mount a host folder on guest machine add a configuration like this:
+And finally bring up your Vagrant guest:
 
-    config.sshfs.mount_on_guest = true
-    config.sshfs.paths = { "src" => "mountpoint" }
-    config.sshfs.host_addr = '10.0.2.2'
+```
+# vagrant up
+```
 
-`src` is the source absolute path to the folder in the host machine, `mountpoint` is the folder in the guest. `src` can be an absolute path, or relative to the `Vagrantfile`.
-`host_addr` is the host machine IP accessible from guest.
+## Executing the `vagrant sshfs` command
 
-## Contributing
+The Vagrant SSHFS plugin also supports execution of the `vagrant sshfs`
+command from the command line. Executing this command will
+iterate through the Vagrant file and attempt to mount (via SSHFS) any
+folders that aren't already mounted in the Vagrant guest that is
+associated with the current directory.
 
-If you have issues or ideas, please contribute! You can create an issue throught Github, or send a Pull Request.
+```
+vagrant sshfs
+```
 
+## Options
+
+The SSHFS synced folder plugin supports a few options that can be
+provided on the command line. They are described below:
+
+- `ssh_host`
+    - The host to connect to via SSH. If not provided this will be 
+      detected as the Vagrant host that is running the Vagrant guest.
+- `ssh_port`
+    - The port to use when connecting. Defaults to port 22.
+- `ssh_username` 
+    - The username to use when connecting. If not provided it is
+    detected as the current user who is interacting with Vagrant.
+- `ssh_password` - NOT RECOMMENDED
+    - The password to use when connecting. If not provided and the
+      user is not using SSH keys, then the user will be prompted for
+      the password. Please use SSH keys and don't use this option!
+- `prompt_for_password`
+    - The user can force Vagrant to interactively prompt the user for
+      a password by setting this to 'true'. Alternatively the user can
+      deny Vagrant from ever prompting for the password by setting
+      this to 'false'.
+- `disabled`
+    - If set to 'true', ignore this folder and don't mount it.
+
+Here is an example of how to use the options:
+
+```
+config.vm.synced_folder "/path/on/host", "/path/on/guest", 
+    type: "sshfs",
+    ssh_username: "user1",
+    ssh_port: "22"
+```
+
 ## Development
 
-To try this out, you can run `bundle exec vagrant up` from the source code checkout.
+For local development of this plugin here is an example of how to build 
+and install this plugin on your local machine:
+
+```
+$ rake build
+vagrant-sshfs 0.1.0 built to pkg/vagrant-sshfs-0.1.0.gem.
+$ mkdir -p /tmp/gems/gems
+$ cp pkg/vagrant-sshfs-0.1.0.gem /tmp/gems/gems/                                                                                                          
+$ pushd /tmp/gems/
+$ gem generate_index
+$ popd
+$ vagrant plugin install vagrant-sshfs --plugin-source file:///tmp/gems/
+```