From 730e268d20aa376cec52bb06ced9a65ee22b29d4 Mon Sep 17 00:00:00 2001
From: Mitchell Hashimoto <mitchell.hashimoto@gmail.com>
Date: Thu, 27 Feb 2014 15:00:37 -0800
Subject: [PATCH] website/docs: document vagrant share functionality

---
 website/docs/source/layouts/layout.erb        | 12 ++++
 website/docs/source/v2/cli/connect.html.md    | 30 ++++++++++
 website/docs/source/v2/cli/share.html.md      | 46 +++++++++++++++
 website/docs/source/v2/share/connect.html.md  | 50 +++++++++++++++++
 website/docs/source/v2/share/http.html.md     | 48 ++++++++++++++++
 website/docs/source/v2/share/index.html.md    | 37 ++++++++++++
 website/docs/source/v2/share/security.html.md | 56 +++++++++++++++++++
 website/docs/source/v2/share/ssh.html.md      | 50 +++++++++++++++++
 8 files changed, 329 insertions(+)
 create mode 100644 website/docs/source/v2/cli/connect.html.md
 create mode 100644 website/docs/source/v2/cli/share.html.md
 create mode 100644 website/docs/source/v2/share/connect.html.md
 create mode 100644 website/docs/source/v2/share/http.html.md
 create mode 100644 website/docs/source/v2/share/index.html.md
 create mode 100644 website/docs/source/v2/share/security.html.md
 create mode 100644 website/docs/source/v2/share/ssh.html.md

diff --git a/website/docs/source/layouts/layout.erb b/website/docs/source/layouts/layout.erb
index b31f9119e..ef784bbd2 100644
--- a/website/docs/source/layouts/layout.erb
+++ b/website/docs/source/layouts/layout.erb
@@ -106,6 +106,7 @@
 								<% if sidebar_section == "cli" %>
 								<ul class="sub unstyled nocap">
 									<li<%= sidebar_current("cli-box") %>><a href="/v2/cli/box.html">box</a></li>
+									<li<%= sidebar_current("cli-connect") %>><a href="/v2/cli/connect.html">connect</a></li>
 									<li<%= sidebar_current("cli-destroy") %>><a href="/v2/cli/destroy.html">destroy</a></li>
 									<li<%= sidebar_current("cli-halt") %>><a href="/v2/cli/halt.html">halt</a></li>
 									<li<%= sidebar_current("cli-init") %>><a href="/v2/cli/init.html">init</a></li>
@@ -114,6 +115,7 @@
 									<li<%= sidebar_current("cli-provision") %>><a href="/v2/cli/provision.html">provision</a></li>
 									<li<%= sidebar_current("cli-reload") %>><a href="/v2/cli/reload.html">reload</a></li>
 									<li<%= sidebar_current("cli-resume") %>><a href="/v2/cli/resume.html">resume</a></li>
+									<li<%= sidebar_current("cli-share") %>><a href="/v2/cli/share.html">share</a></li>
 									<li<%= sidebar_current("cli-ssh") %>><a href="/v2/cli/ssh.html">ssh</a></li>
 									<li<%= sidebar_current("cli-ssh_config") %>><a href="/v2/cli/ssh_config.html">ssh-config</a></li>
 									<li<%= sidebar_current("cli-status") %>><a href="/v2/cli/status.html">status</a></li>
@@ -124,6 +126,16 @@
 								</ul>
 								<% end %>
 
+								<li <%= sidebar_current("share") %>><a href="/v2/share/index.html">Vagrant Share</a></li>
+								<% if sidebar_section == "share" %>
+								<ul class="sub unstyled">
+									<li<%= sidebar_current("share-http") %>><a href="/v2/share/http.html">HTTP Sharing</a></li>
+									<li<%= sidebar_current("share-ssh") %>><a href="/v2/share/ssh.html">SSH Sharing</a></li>
+									<li<%= sidebar_current("share-connect") %>><a href="/v2/share/connect.html">vagrant connect</a></li>
+									<li<%= sidebar_current("share-security") %>><a href="/v2/share/security.html">Security</a></li>
+								</ul>
+								<% end %>
+
 								<li <%= sidebar_current("vagrantfile") %>><a href="/v2/vagrantfile/index.html">Vagrantfile</a></li>
 								<% if sidebar_section == "vagrantfile" %>
 								<ul class="sub unstyled">
diff --git a/website/docs/source/v2/cli/connect.html.md b/website/docs/source/v2/cli/connect.html.md
new file mode 100644
index 000000000..6aad69df4
--- /dev/null
+++ b/website/docs/source/v2/cli/connect.html.md
@@ -0,0 +1,30 @@
+---
+page_title: "vagrant connect - Command-Line Interface"
+sidebar_current: "cli-connect"
+---
+
+# Connect
+
+**Command: `vagrant connect NAME`**
+
+The connect command compliments the
+[share command](/v2/cli/share.html) by enabling access to shared
+environments. You can learn about all the details of Vagrant Share in the
+[Vagrant Share section](/v2/share/index.html).
+
+The reference of available command-line flags to this command
+is available below.
+
+## Options
+
+* `--disable-static-ip` - The connect command will not spin up a small
+  virtual machine to create a static IP you can access. When this flag is
+  set, the only way to access the connection is to use the SOCKS proxy
+  address outputted.
+
+* `--static-ip IP` - Tells connect what static IP address to use for the virtual
+  machine. By default, Vagrant connect will use an IP address that looks
+  available in the 172.16.0.0/16 space.
+
+* `--ssh` - Connects via SSH to an environment shared with
+  `vagrant share --ssh`.
diff --git a/website/docs/source/v2/cli/share.html.md b/website/docs/source/v2/cli/share.html.md
new file mode 100644
index 000000000..7469dd1f1
--- /dev/null
+++ b/website/docs/source/v2/cli/share.html.md
@@ -0,0 +1,46 @@
+---
+page_title: "vagrant share - Command-Line Interface"
+sidebar_current: "cli-share"
+---
+
+# Share
+
+**Command: `vagrant share`**
+
+The share command initializes a Vagrant Share session, allowing you to
+share your Vagrant environment with anyone in the world, enabling collaboration
+directly in your Vagrant environment in almost any network environment.
+
+You can learn about all the details of Vagrant Share in the
+[Vagrant Share section](/v2/share/index.html).
+
+The reference of available command-line flags to this command
+is available below.
+
+## Options
+
+* `--disable-http` - Disables the creation of a publicly accessible
+  HTTP endpoint to your Vagrant environment. With this set, the only way
+  to access your share is with `vagrant connect`.
+
+* `--http PORT` - The port of the HTTP server running in the Vagrant
+  environment. By default, Vagrant will attempt to find this for you.
+  This has no effect if `--disable-http` is set.
+
+* `--https PORT` - The port of an HTTPS server running in the Vagrant
+  environment. By default, Vagrant will attempt to find this for you.
+  This has no effect if `--disable-http` is set.
+
+* `--ssh` - Enables SSH sharing (more information below). By default, this
+  is not enabled.
+
+* `--ssh-no-password` - Disables the encryption of the SSH keypair created
+  when SSH sharing is enabled.
+
+* `--ssh-port PORT` - The port of the SSH server running in the Vagrant
+  enviroment. By default, Vagrant will attempt to find this for you.
+
+* `--ssh-once` - Allows SSH access only once. After the first attempt to
+  connect via SSH to the Vagrant environment, the generated keypair is
+  destroyed.
+
diff --git a/website/docs/source/v2/share/connect.html.md b/website/docs/source/v2/share/connect.html.md
new file mode 100644
index 000000000..61c06dcf7
--- /dev/null
+++ b/website/docs/source/v2/share/connect.html.md
@@ -0,0 +1,50 @@
+---
+page_title: "Vagrant Connect - Vagrant Share"
+sidebar_current: "share-connect"
+---
+
+# Vagrant Connect
+
+Vagrant can share any or _every_ port to your Vagrant environment, not
+just SSH and HTTP. The `vagrant connect` command gives the connecting person
+a static IP they can use to communicate to the shared Vagrant environment.
+Any TCP/UDP traffic sent to this IP is sent to the shared Vagrant environment.
+
+## Usage
+
+Just call `vagrant share`. This will automatically share as many ports as
+possible for remote connections. If the Vagrant environment has a static IP or DNS address, then every port
+will be available. Otherwise, Vagrant will only expose forwarded ports on
+the machine.
+
+Note the share name at the end of calling `vagrant share`, and give this to
+the person who wants to connect to your machine. They simply have to call
+`vagrant connect NAME`. This will give them a static IP they can use to access
+your Vagrant environment.
+
+## How does it work?
+
+`vagrant connect` works by doing what Vagrant does best: managing virtual
+machines. `vagrant connect` creates a tiny virtual machine that takes up
+only around 20 MB in RAM, using VirtualBox or VMware (more provider support
+is coming soon).
+
+Any traffic sent to this tiny virtual machine is then proxies through to
+the shared Vagrant environment as if it were directed at it.
+
+## Beware: Vagrant Insecure Key
+
+If the Vagrant environment or box you're using is protected with the
+Vagrant insecure keypair (most public boxes are), then SSH will be easily
+available to anyone who connects.
+
+While hopefully you're sharing with someone you trust, in certain environments
+you might be sharing with a class, or a conference, and you don't want them
+to be able to SSH in.
+
+In this case, we recommend changing or removing the insecure key from
+the Vagrant machine.
+
+Finally, we want to note that we are working on making it so that when
+Vagrant share is used, the Vagrant private key is actively rejected unless
+explicitly allowed. This feature is not yet done, however.
diff --git a/website/docs/source/v2/share/http.html.md b/website/docs/source/v2/share/http.html.md
new file mode 100644
index 000000000..9c3a92d1c
--- /dev/null
+++ b/website/docs/source/v2/share/http.html.md
@@ -0,0 +1,48 @@
+---
+page_title: "HTTP Sharing - Vagrant Share"
+sidebar_current: "share-http"
+---
+
+# HTTP Sharing
+
+Vagrant Share can create a publicly accessible URL endpoint to access an
+HTTP server running in your Vagrant environment. This is known as "HTTP
+sharing," and is enabled by default when `vagrant share` is used.
+
+Because this mode of sharing creates a publicly accessible URL, the accessing
+party does not need to have Vagrant installed in order to view your environment.
+
+This has a number of useful use cases: you can test webooks by exposing
+your Vagrant environment to the internet, you can show your work to clients,
+teammates, or managers, etc.
+
+## Usage
+
+To use HTTP sharing, simply run `vagrant share`:
+
+```
+TODO
+```
+
+Vagrant detects where your HTTP server is running in your Vagrant environment
+and outputs the endpoint that can be used to access this share. Just give
+this URL to anyone you want to share it with, and they'll be able to access
+your Vagrant environment!
+
+If Vagrant has trouble detecting the port of your servers in your environment,
+use the `--http` and/or `--https` flags to be more explicit.
+
+The share will be accessible for the duration that `vagrant share` is running.
+Press `Ctrl-C` to quit the sharing session.
+
+<div class="alert alert-block alert-warn">
+<strong>Warning:</strong> This URL is accessible by <em>anyone</em>
+who knows it, so be careful if you're sharing sensitive information.
+</div>
+
+## Disabling
+
+If you want to disable the creation of the publicly accessible endpoint,
+run `vagrant share` with the `--disable-http` flag. This will share your
+environment using one of the other methods available, and will not create
+the URL endpoint.
diff --git a/website/docs/source/v2/share/index.html.md b/website/docs/source/v2/share/index.html.md
new file mode 100644
index 000000000..fe948ad4e
--- /dev/null
+++ b/website/docs/source/v2/share/index.html.md
@@ -0,0 +1,37 @@
+---
+page_title: "Vagrant Share"
+sidebar_current: "share"
+---
+
+# Vagrant Share
+
+Vagrant Share allows you to  share your Vagrant environment with anyone in
+the world, enabling collaboration directly in your Vagrant environment
+in almost any network environment with just a single command:
+`vagrant share`.
+
+Vagrant share has three primary modes or features. These features aren't
+mutually exclusive, meaning that any combination of them can be active
+at any given time:
+
+  * **HTTP sharing** will create a URL that you can give to anyone. This
+    URL will route directly into your Vagrant environment. The person using
+    this URL does not need Vagrant installed, so it can be shared with anyone.
+    This is useful for testing webhooks or showing your work to clients,
+    teammates, managers, etc.
+
+  * **SSH sharing** will allow instant SSH access to your Vagrant environment
+    by anyone by running `vagrant connect --ssh` on the remote side. This
+    is useful for pair programming, debugging ops problems, etc.
+
+  * **General sharing** allows anyone to access any exposed port of your
+    Vagrant environment by running `vagrant connect` on the remote side.
+    This is useful if the remote side wants to access your Vagrant
+    environment as if it were a computer on the LAN.
+
+The details of each are covered in their specific section in the sidebar
+to the left. We also have a section where we go into detail about the
+security implications of this feature.
+
+Vagrant Share requires an account with
+[Vagrant Cloud](http://www.vagrantcloud.com) to be used.
diff --git a/website/docs/source/v2/share/security.html.md b/website/docs/source/v2/share/security.html.md
new file mode 100644
index 000000000..6be70e620
--- /dev/null
+++ b/website/docs/source/v2/share/security.html.md
@@ -0,0 +1,56 @@
+---
+page_title: "Security - Vagrant Share"
+sidebar_current: "share-security"
+---
+
+# Security
+
+Sharing your Vagrant environment understandably raises a number of security
+concerns.
+
+The primary security mechanism for Vagrant
+Share is security through obscurity along with an encryption key for SSH.
+Additionally, there are several configuration options made available to
+help control access and manage security:
+
+  * `--disable-http` will not create a publicly accessible HTTP URL. When
+    this is set, the only way to access the share is with `vagrant connect`.
+
+  * `--ssh-once` will allow only one person to SSH into your shared environment.
+    After the first SSH access, the keypair is physically deleted and SSH
+    access won't be possible anymore.
+
+In addition to these options, there are other features we've built to help:
+
+  * Vagrant share uses end-to-end TLS connections. So even unencrypted TCP streams
+    are encrypted through the various proxies and only unencrypted during the final
+    local communication between the local proxy and the Vagrant environment.
+
+  * Share names, such as happy-panda-1234, are randoly chosen from a pool
+    of over 40,000,000 possible names. And we're routinely adding more
+    words to grow this pool. It is unlikely that anyone will guess your
+    share name.
+
+  * SSH keys are encrypted by default, using a password that is not transmitted
+    to our servers or across the network at all.
+
+  * SSH is not shared by default, it must explicitly be shared with the
+    `--ssh` flag.
+
+  * A web interface we've built shows share history and will show basic
+    access logs in the future.
+
+  * Share sessions expire after a short time (currently 1 hour), but
+    can also be expired manually by `ctrl-c` from the sharing machine
+    or via the web interface.
+
+Most importantly, you must understand that by running `vagrant share`,
+you are making your Vagrant environment accessible by anyone who knows
+the share name. When share is not running, it is not accessible.
+
+Later, we will be expanding the security of this feature by adding ACLs,
+so you're able to explicitly allow
+access to your share based on who is connecting.
+
+For maximum security, we will also allow you to run your own Vagrant
+Share server. This option isn't available yet.
diff --git a/website/docs/source/v2/share/ssh.html.md b/website/docs/source/v2/share/ssh.html.md
new file mode 100644
index 000000000..d695493a5
--- /dev/null
+++ b/website/docs/source/v2/share/ssh.html.md
@@ -0,0 +1,50 @@
+---
+page_title: "SSH Sharing - Vagrant Share"
+sidebar_current: "share-ssh"
+---
+
+# SSH Sharing
+
+Vagrant share makes it trivially easy to allow remote SSH access to your
+Vagrant environment by supplying the `--ssh` flag to `vagrant share`.
+
+Easy SSH sharing is incredibly useful if you want to give access to
+a colleague for troubleshooting ops issues. Additionally, it enables
+pair programming with a Vagrant environment, if you want!
+
+SSH sharing is disabled by default as a security measure. To enable
+SSH sharing, simply supply the `--ssh` flag when calling `vagrant share`.
+
+## Usage
+
+Just run `vagrant share --ssh`!
+
+When SSH sharing is enabled, Vagrant generates a brand new keypair for
+SSH access. The public key portion is automatically inserted
+into the Vagrant machine, and the private key portion is uploaded to the
+server managing the Vagrant shares. This private key is encrypted using
+a password that you will be prompted for. This password is _never_ transmitted
+across the network by Vagrant, and is an extra layer of security preventing
+us or anyone who may know your share name from easily accessing your machine.
+
+After running `vagrant share --ssh`, it will output the name of your share:
+
+```
+TODO
+```
+
+Anyone can then SSH directly to your Vagrant environment by running
+`vagrant connect --ssh NAME` where NAME is the name of the share outputted
+previously.
+
+```
+TODO
+```
+
+If the private key is encrypted (the default behavior), then the connecting
+person will be prompted for the password to decrypt the private key.
+
+Additional flags are available such as `--ssh-once` to add another layer
+of security to your SSH shared session. With this flag active, only one
+`vagrant connect --ssh` can be attempted before the keypair is destroyed,
+preventing any future connections.