website/docs: document vagrant share functionality
This commit is contained in:
Mitchell Hashimoto
parent
ac16f7a1fb
commit
730e268d20
|
|
@ -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">
|
||||
|
|
|
|||
|
|
@ -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`.
|
||||
|
|
@ -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.
|
||||
|
||||
|
|
@ -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.
|
||||
|
|
@ -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.
|
||||
|
|
@ -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.
|
||||
|
|
@ -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.
|
||||
|
|
@ -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.
|
||||
Loading…
Reference in New Issue