WIP: docs update for d4mac, d4win, Hyper-V driver and other virtualization factors, swarm mode

more updates to Machine docs for creating local VMsM

added details and example on using hyper-v driver, formatted headings for other driver docs

copyedits

incorporated Nathan's copyedits

Signed-off-by: Victoria Bialas <victoria.bialas@docker.com>

docs/drivers/aws.md

@@ -74,7 +74,7 @@ You can use environment variables:
 -   `--amazonec2-retries`:  Set retry count for recoverable failures (use -1 to disable)
 
 
-Environment variables and default values:
+#### Environment variables and default values:
 
 | CLI option                               | Environment variable    | Default          |
 | ---------------------------------------- | ----------------------- | ---------------- |

docs/drivers/azure.md

@@ -57,7 +57,8 @@ Optional:
 - `--azure-resource-group`: Azure Resource Group name to create the resources in.
 - `--azure-size`: Size for Azure Virtual Machine. [[?][vm-size]]
 - `--azure-ssh-user`: Username for SSH login.
-- `--azure-vnet`: Azure Virtual Network name to connect the virtual machine. [[?][vnet]]
+- `--azure-vnet`: Azure Virtual Network name to connect the virtual machine.
+  [[?][vnet]] To specify a Virtual Network from another resource group, use `resourcegroup:vnet-name` format.
 - `--azure-subnet`: Azure Subnet Name to be used within the Virtual Network.
 - `--azure-subnet-prefix`: Private CIDR block. Used to create subnet if it does not exist. Must match in the case that the subnet does exist.
 - `--azure-availability-set`: Azure Availability Set to place the virtual machine into. [[?][av-set]]
@@ -75,7 +76,7 @@ Optional:
 [vnet]:     https://azure.microsoft.com/en-us/documentation/articles/virtual-networks-overview/
 [av-set]:   https://azure.microsoft.com/en-us/documentation/articles/virtual-machines-manage-availability/
 
-Environment variables and default values:
+#### Environment variables and default values
 
 | CLI option                      | Environment variable          | Default            |
 | ------------------------------- | ----------------------------- | ------------------ |

docs/drivers/digital-ocean.md

@@ -15,9 +15,11 @@ Create Docker machines on [Digital Ocean](https://www.digitalocean.com/).
 You need to create a personal access token under "Apps & API" in the Digital Ocean
 Control Panel and pass that to `docker-machine create` with the `--digitalocean-access-token` option.
 
+## Usage
+
     $ docker-machine create --driver digitalocean --digitalocean-access-token=aa9399a2175a93b17b1c86c807e08d3fc4b79876545432a629602f61cf6ccd6b test-this
 
-Options:
+## Options
 
 -   `--digitalocean-access-token`: **required** Your personal access token for the Digital Ocean API.
 -   `--digitalocean-image`: The name of the Digital Ocean image to use.
@@ -33,7 +35,7 @@ Options:
 
 The DigitalOcean driver will use `ubuntu-15-10-x64` as the default image.
 
-Environment variables and default values:
+####  Environment variables and default values
 
 | CLI option                          | Environment variable              | Default            |
 | ----------------------------------- | --------------------------------- | ------------------ |

docs/drivers/exoscale.md

@@ -14,9 +14,11 @@ Create machines on [exoscale](https://www.exoscale.ch/).
 
 Get your API key and API secret key from [API details](https://portal.exoscale.ch/account/api) and pass them to `machine create` with the `--exoscale-api-key` and `--exoscale-api-secret-key` options.
 
+## Usage
+
     $ docker-machine create --driver exoscale --exoscale-api-key=API --exoscale-api-secret-key=SECRET vm
 
-Options:
+## Options
 
 -   `--exoscale-url`: Your API endpoint.
 -   `--exoscale-api-key`: **required** Your API key.
@@ -31,7 +33,9 @@ Options:
 
 If a custom security group is provided, you need to ensure that you allow TCP ports 22 and 2376 in an ingress rule. Moreover, if you want to use Swarm, also add TCP port 3376.
 
-Environment variables and default values:
+There is a limit to the number of docker machines that an anti-affinity group can have.  This can be worked around by specifying an additional anti-affinity group using `--exoscale-affinity-group=docker-machineX`
+
+#### Environment variables and default values
 
 | CLI option                      | Environment variable         | Default                           |
 | ------------------------------- | ---------------------------- | --------------------------------- |

docs/drivers/gce.md

@@ -58,7 +58,7 @@ list of image URLs run:
 
     gcloud compute images list --uri
 
-Environment variables and default values:
+#### Environment variables and default values
 
 | CLI option                 | Environment variable     | Default                              |
 | -------------------------- | ------------------------ | ------------------------------------ |

docs/drivers/generic.md

@@ -54,7 +54,7 @@ as a sudoer with `NOPASSWD`. See https://help.ubuntu.com/community/Sudoers.
 
 > **Note**: You must use a base operating system supported by Machine.
 
-Environment variables and default values:
+#### Environment variables and default values
 
 | CLI option                 | Environment variable | Default                   |
 | -------------------------- | -------------------- | ------------------------- |

docs/drivers/hyper-v.md

@@ -11,20 +11,30 @@ parent="smn_machine_drivers"
 # Microsoft Hyper-V
 
 Creates a Boot2Docker virtual machine locally on your Windows machine
-using Hyper-V. [See here](http://windows.microsoft.com/en-us/windows-8/hyper-v-run-virtual-machines)
+using Hyper-V.
-for instructions to enable Hyper-V. You will need to use an
-Administrator level account to create and manage Hyper-V machines.
 
-> **Note**: You will need an existing virtual switch to use the
+Hyper-V must be enabled on your desktop system. Docker for Windows automatically
+enables it upon install. See this article on the Microsoft developer network for
+[instructions on how to manually enable
+Hyper-V](https://msdn.microsoft.com/en-us/virtualization/hyperv_on_windows/quick_start/walkthrough_install).
+
+> **Notes**:
+>
+> * You will need to use an Administrator level account to create and manage Hyper-V machines.
+>
+>* You will need an existing virtual switch to use the
 > driver. Hyper-V can share an external network interface (aka
 > bridging), see [this blog](http://blogs.technet.com/b/canitpro/archive/2014/03/11/step-by-step-enabling-hyper-v-for-use-on-windows-8-1.aspx).
 > If you would like to use NAT, create an internal network, and use
-> [Internet Connection
+> [Internet Connection  Sharing](http://www.packet6.com/allowing-windows-8-1-hyper-v-vm-to-work-with-wifi/).
-> Sharing](http://www.packet6.com/allowing-windows-8-1-hyper-v-vm-to-work-with-wifi/).
+>
+> * This reference page includes an [example](#example) that shows how to use an elelvated (Administrator-level) PowerShell and how to create and use an external network switch.
+
+## Usage
 
     $ docker-machine create --driver hyperv vm
 
-Options:
+## Options
 
 -   `--hyperv-boot2docker-url`: The URL of the boot2docker ISO.
 -   `--hyperv-virtual-switch`: Name of the virtual switch to use.
@@ -34,7 +44,7 @@ Options:
 -   `--hyperv-static-macaddress`: Hyper-V network adapter's static MAC address.
 -   `--hyperv-vlan-id`: Hyper-V network adapter's VLAN ID if any.
 
-Environment variables and default values:
+## Environment variables and default values
 
 | CLI option                   | Environment variable       | Default                  |
 | ---------------------------- | -------------------------- | ------------------------ |
@@ -45,3 +55,85 @@ Environment variables and default values:
 | `--hyperv-cpu-count`         | `HYPERV_CPU_COUNT`         | `1`                      |
 | `--hyperv-static-macaddress` | `HYPERV_STATIC_MACADDRESS` | _undefined_              |
 | `--hyperv-cpu-count`         | `HYPERV_VLAN_ID`           | _undefined_              |
+
+## Example
+
+#### 1. Make sure Hyper-V is enabled
+
+  Hyper-V is automatically enabled on a Docker for Windows install. To enable it manually, see [instructions on how to manually enable Hyper-V](https://msdn.microsoft.com/en-us/virtualization/hyperv_on_windows/quick_start/walkthrough_install) on the Microsoft developer network.
+
+#### 2. Set up a new external network switch
+
+Make sure you have Ethernet connectivity while you are doing this.
+
+Open the **Hyper-V Manager**. (On Windows 10, just search for the Hyper-V Manager in the search field in the lower left search field.)
+
+Select the Virtual Switch Manager on the left-side **Actions** panel.
+
+![Hyper-V manager](../img/hyperv-manager.png)
+
+Set up a new external network switch to use instad of DockerNAT network switch (for Moby), which is set up by default when you install Docker for Windows. (Or if you already have another network switch set up, you can use that one.)
+
+For this example, we created a virtual switch called `Primary Virtual Switch`.
+
+![Defining a new virtual switch](../img/hyperv-network-switch.png)
+
+#### 3. Reboot
+
+  See [this issue on virtualbox: Hangs on Waiting for VM to start #986](https://github.com/docker/machine/issues/986).
+
+  A reboot of your desktop system clears out any problems with the routing tables. Without a reboot first, `docker-machine create ...` might get hung up on `Waiting for VM to start`.
+
+#### 4. Create the nodes with Docker Machine and the Microsoft Hyper-V driver
+
+* Start an "elevated" PowerShell (i.e., running as administrator). To do this, search for PowerShell, right-click, and choose Run as administrator.
+
+* Run the `docker-machine create` commands to create machines.
+
+    For example, if you follow along with the [Swarm mode
+tutorial](/engine/swarm/swarm-tutorial/index.md) which asks you to create [three
+networked host
+machines](/engine/swarm/swarm-tutorial/index.md#three-networked-host-machines),
+you can create these swarm nodes: `manager1`, `worker1`, `worker2`.
+
+* Use the Microsoft Hyper-V driver and reference the new virtual switch you created.
+
+        docker-machine create -d hyperv --hyperv-virtual-switch "<NameOfVirtualSwitch>" <nameOfNode>
+
+    Here is an example of creating `manager1` node:
+
+      ```shell
+      PS C:\WINDOWS\system32>  docker-machine create -d hyperv --hyperv-virtual-switch "Primary Virtual Switch" manager1
+      Running pre-create checks...
+      Creating machine...
+      (manager1) Copying C:\Users\Vicky\.docker\machine\cache\boot2docker.iso to C:\Users\Vicky\.docker\machine\machines\manag
+      er1\boot2docker.iso...
+      (manager1) Creating SSH key...
+      (manager1) Creating VM...
+      (manager1) Using switch "Primary Virtual Switch"
+      (manager1) Creating VHD
+      (manager1) Starting VM...
+      (manager1) Waiting for host to start...
+      Waiting for machine to be running, this may take a few minutes...
+      Detecting operating system of created instance...
+      Waiting for SSH to be available...
+      Detecting the provisioner...
+      Provisioning with boot2docker...
+      Copying certs to the local machine directory...
+      Copying certs to the remote machine...
+      Setting Docker configuration on the remote daemon...
+      Checking connection to Docker...
+      Docker is up and running!
+      To see how to connect your Docker Client to the Docker Engine running on this virtual machine, run: C:\Program Files\Doc
+      ker\Docker\Resources\bin\docker-machine.exe env manager1
+      PS C:\WINDOWS\system32>
+      ```
+
+* Use the same process, driver and network switch to create the other nodes.
+
+    For our example, the commands will look like this:
+
+    ```shell
+    docker-machine create -d hyperv --hyperv-virtual-switch "Primary Virtual Switch" worker1
+    docker-machine create -d hyperv --hyperv-virtual-switch "Primary Virtual Switch" worker2
+    ```

docs/drivers/openstack.md

@@ -18,10 +18,11 @@ Mandatory:
 -   `--openstack-flavor-id` or `--openstack-flavor-name`: Identify the flavor that will be used for the machine.
 -   `--openstack-image-id` or `--openstack-image-name`: Identify the image that will be used for the machine.
 
+## Usage
 
     $ docker-machine create --driver openstack vm
 
-Options:
+## Options
 
 -   `--openstack-active-timeout`: The timeout in seconds until the OpenStack instance must be active.
 -   `--openstack-availability-zone`: The availability zone in which to launch the server.
@@ -45,7 +46,7 @@ Options:
 -   `--openstack-ssh-user`: The username to use for SSH into the machine. If not provided `root` will be used.
 -   `--openstack-tenant-name` or `--openstack-tenant-id`: Identify the tenant in which the machine will be created.
 
-Environment variables and default values:
+#### Environment variables and default values
 
 | CLI option                      | Environment variable   | Default     |
 | ------------------------------- | ---------------------- | ----------- |

docs/drivers/rackspace.md

@@ -12,9 +12,11 @@ parent="smn_machine_drivers"
 
 Create machines on [Rackspace cloud](http://www.rackspace.com/cloud)
 
+## Usage
+
     $ docker-machine create --driver rackspace --rackspace-username=user --rackspace-api-key=KEY --rackspace-region=region vm
 
-Options:
+## Options
 
 -   `--rackspace-username`: **required** Rackspace account username.
 -   `--rackspace-api-key`: **required** Rackspace API key.
@@ -28,7 +30,7 @@ Options:
 
 The Rackspace driver will use `59a3fadd-93e7-4674-886a-64883e17115f` (Ubuntu 15.10) by default.
 
-Environment variables and default values:
+#### Environment variables and default values
 
 | CLI option                   | Environment variable | Default                                |
 | ---------------------------- | -------------------- | -------------------------------------- |

docs/drivers/soft-layer.md

@@ -15,9 +15,11 @@ Create machines on [Softlayer](http://softlayer.com).
 You need to generate an API key in the softlayer control panel.
 [Retrieve your API key](http://knowledgelayer.softlayer.com/procedure/retrieve-your-api-key)
 
+## Usage
+
     $ docker-machine create --driver softlayer --softlayer-user=user --softlayer-api-key=KEY --softlayer-domain=domain vm
 
-Options:
+## Options
 
 -   `--softlayer-memory`: Memory for host in MB.
 -   `--softlayer-disk-size`: A value of `0` will set the SoftLayer default.
@@ -37,7 +39,7 @@ Options:
 
 The SoftLayer driver will use `UBUNTU_LATEST` as the image type by default.
 
-Environment variables and default values:
+#### Environment variables and default values
 
 | CLI option                     | Environment variable        | Default                     |
 | ------------------------------ | --------------------------- | --------------------------- |

docs/drivers/virtualbox.md

@@ -15,6 +15,8 @@ This driver requires VirtualBox 5+ to be installed on your host.
 Using VirtualBox 4.3+ should work but will give you a warning. Older versions
 will refuse to work.
 
+## Usage
+
     $ docker-machine create --driver=virtualbox vbox-test
 
 You can create an entirely new machine or you can convert a Boot2Docker VM into
@@ -27,7 +29,7 @@ The size of the VM's disk can be configured this way:
 
     $ docker-machine create -d virtualbox --virtualbox-disk-size "100000" large
 
-Options:
+## Options
 
 -   `--virtualbox-memory`: Size of memory for the host in MB.
 -   `--virtualbox-cpu-count`: Number of CPUs to use to create the VM. Defaults to single CPU.
@@ -68,7 +70,7 @@ to `.254`.  For example, a specified CIDR of `192.168.24.1/24` would have a
 DHCP server between `192.168.24.2-25`, a lower bound of `192.168.24.100` and
 upper bound of `192.168.24.254`.
 
-Environment variables and default values:
+#### Environment variables and default values
 
 | CLI option                           | Environment variable               | Default                  |
 | ------------------------------------ | ---------------------------------- | ------------------------ |

docs/drivers/vm-cloud.md

@@ -12,9 +12,11 @@ parent="smn_machine_drivers"
 
 Creates machines on [vCloud Air](http://vcloud.vmware.com) subscription service. You need an account within an existing subscription of vCloud Air VPC or Dedicated Cloud.
 
+## Usage
+
     $ docker-machine create --driver vmwarevcloudair --vmwarevcloudair-username=user --vmwarevcloudair-password=SECRET vm
 
-Options:
+## Options
 
 -   `--vmwarevcloudair-username`: **required** vCloud Air Username.
 -   `--vmwarevcloudair-password`: **required** vCloud Air Password.
@@ -33,7 +35,7 @@ Options:
 
 The VMware vCloud Air driver will use the `Ubuntu Server 12.04 LTS (amd64 20140927)` image by default.
 
-Environment variables and default values:
+#### Environment variables and default values
 
 | CLI option                        | Environment variable      | Default                                    |
 | --------------------------------- | ------------------------- | ------------------------------------------ |

docs/drivers/vm-fusion.md

@@ -12,9 +12,11 @@ parent="smn_machine_drivers"
 
 Creates machines locally on [VMware Fusion](http://www.vmware.com/products/fusion). Requires VMware Fusion to be installed.
 
+## Usage
+
     $ docker-machine create --driver vmwarefusion vm
 
-Options:
+## Options
 
 -   `--vmwarefusion-boot2docker-url`: URL for boot2docker image.
 -   `--vmwarefusion-cpu-count`: Number of CPUs for the machine (-1 to use the number of CPUs available)
@@ -25,7 +27,7 @@ Options:
 The VMware Fusion driver uses the latest boot2docker image.
 See [frapposelli/boot2docker](https://github.com/frapposelli/boot2docker/tree/vmware-64bit)
 
-Environment variables and default values:
+#### Environment variables and default values
 
 | CLI option                       | Environment variable     | Default                  |
 | -------------------------------- | ------------------------ | ------------------------ |

docs/drivers/vsphere.md

@@ -11,9 +11,12 @@ parent="smn_machine_drivers"
 # VMware vSphere
 
 Creates machines on a [VMware vSphere](http://www.vmware.com/products/vsphere) Virtual Infrastructure. The machine must have a working vSphere ESXi installation. You can use a paid license or free 60 day trial license. Your installation may also include an optional VCenter server.
+
+## Usage
+
     $ docker-machine create --driver vmwarevsphere --vmwarevsphere-username=user --vmwarevsphere-password=SECRET vm
 
-Options:
+## Options
 
 -   `--vmwarevsphere-username`: **required** vSphere Username.
 -   `--vmwarevsphere-password`: **required** vSphere Password.
@@ -31,7 +34,7 @@ Options:
 
 The VMware vSphere driver uses the latest boot2docker image.
 
-Environment variables and default values:
+#### Environment variables and default values
 
 | CLI option                        | Environment variable      | Default                  |
 | --------------------------------- | ------------------------- | ------------------------ |

docs/get-started.md

@@ -11,16 +11,84 @@ weight=-70
 
 # Get started with Docker Machine and a local VM
 
-Let's take a look at using `docker-machine` for creating, using, and managing a
+Let's take a look at using `docker-machine` to create, use and manage a
-Docker host inside of <a href=
+Docker host inside of a local virtual machine.
-"https://www.virtualbox.org/" target="_blank">VirtualBox</a>.
 
-## Prerequisites
+## Prerequisite Information
 
-* Make sure  you have <a href="https://www.virtualbox.org/wiki/Downloads" target="_blank">the latest VirtualBox</a> correctly installed
+With the advent of [Docker for Mac](/docker-for-mac/index.md) and [Docker for
-on your system. If you used <a href="https://www.docker.com/products/docker-toolbox" target="_blank">Toolbox</a> for <a href="https://docs.docker.com/engine/installation/mac/" target="_blank">Mac</a> or <a href="https://docs.docker.com/engine/installation/windows/" target="_blank">Windows</a> to install Docker Machine, VirtualBox is automatically installed.
+Windows](/docker-for-windows/index.md) as replacements for [Docker
+Toolbox](/toolbox/overview.md), we recommend that you use these for your primary
+Docker workflows.
 
-* If you used the Quickstart Terminal to launch your first machine and set your terminal environment to point to it, a default machine was automatically created. If this is the case, you can still follow along with these steps, but create another machine and name it something other than "default" (e.g., staging or sandbox).
+However, Docker Machine is still available to create and manage machines for
+power users or multi-node experimentation. Both Docker for Mac and Docker for
+Windows include the newest version of Docker Machine, so when you install either
+of these, you get `docker-machine`.
+
+The new solutions come with their own native virtualization solutions rather
+than using Oracle VirtualBox, so there are new considerations to keep in mind
+when using Machine to create local VMs. Docker for Mac allows for the creation
+of additional `docker-machine` based `virtualbox` machines without issue, but in
+the case of Docker for Windows, you will need to use the `hyperv` driver
+instead.
+
+
+#### If you are using Docker for Windows
+
+Docker for Windows uses [Microsoft
+Hyper-V](https://msdn.microsoft.com/en-us/virtualization/hyperv_on_windows/windows_welcome)
+for virtualization, and Hyper-V and Oracle VirtualBox are incompatible.
+Therefore, you cannot run the two solutions simultaneously. But you can still
+use `docker-machine` to create local VMs by using the Microsoft Hyper-V driver.
+
+* If you are using Docker for Windows, the only prequisite is to have Docker for Windows installed. You will use the Microsoft `hyperv` driver to create
+local machines. (See the [Docker Machine driver for Microsoft
+Hyper-V](drivers/hyper-v.md).)
+
+#### If you are using Docker for Mac
+
+Docker for Mac uses [HyperKit](https://github.com/docker/HyperKit/), a
+lightweight OS X virtualization solution built on top of the
+[Hypervisor.framework](https://developer.apple.com/reference/hypervisor) in OS X
+10.10 Yosemite and higher.
+
+Currently, there is no `docker-machine create` driver for HyperKit, so you will
+use `virtualbox` driver to create local machines. (See the [Docker Machine
+driver for Oracle VirtualBox](drivers/virtualbox.md).) Note that you can run
+both HyperKit and Oracle VirtualBox on the same system. To learn more, see
+[Docker for Mac vs. Docker Toolbox](/docker-for-mac/docker-toolbox/).
+
+* Make sure you have <a href="https://www.virtualbox.org/wiki/Downloads" target="_blank">the latest VirtualBox</a> correctly installed on your system
+(either as part of an earlier Toolbox install, or manual install).
+
+#### If you are using Docker Toolbox
+
+Docker for Mac and Docker for Windows both require newer versions of their
+respective operating systems, so users with older OS versions must use Docker
+Toolbox.
+
+* If you are using Docker Toolbox on either Mac or an older version Windows system (without Hyper-V), you will use the `virtualbox` driver to create
+a local machine based on Oracle <a href= "https://www.virtualbox.org/"
+target="_blank">VirtualBox</a>. (See the [Docker Machine driver for Oracle
+VirtualBox](drivers/virtualbox.md) )
+<br />
+* If you are using Docker Toolbox on a Windows system that has Hyper-V but cannot run Docker for Windows (for example Windows 8 Pro), you must use the
+`hyperv` driver to create local machines. (See the [Docker Machine driver for
+Microsoft Hyper-V](drivers/hyper-v.md).)
+<br />
+* Make sure you have <a href="https://www.virtualbox.org/wiki/Downloads" target="_blank">the latest VirtualBox</a> correctly installed on your system. If
+you used <a href="https://www.docker.com/products/docker-toolbox"
+target="_blank">Toolbox</a> for <a
+href="https://docs.docker.com/engine/installation/mac/" target="_blank">Mac</a>
+or <a href="https://docs.docker.com/engine/installation/windows/"
+target="_blank">Windows</a> to install Docker Machine, VirtualBox is
+automatically installed.
+<br />
+* If you used the Quickstart Terminal to launch your first machine and set your terminal environment to point to it, a default machine was automatically
+created. If this is the case, you can still follow along with these steps, but
+create another machine and name it something other than "default" (e.g., staging
+or sandbox).
 
 ##  Use Machine to run Docker containers
 
@@ -49,30 +117,36 @@ The examples here show how to create and start a machine, run Docker commands, a
 
 3. Create a machine.
 
-    Run the `docker-machine create` command, passing the string `virtualbox` to the `--driver` flag. The final argument is the name of the machine. If this is your first machine, name it `default`. If you already have a "default" machine, choose another name for this new machine.
+    Run the `docker-machine create` command, pass the appropriate driver to the
+`--driver` flag and provide a machine name. If this is your first machine, name
+it `default` as shown in the example. If you already have a "default" machine,
+choose another name for this new machine.
 
-        $ docker-machine create --driver virtualbox default
+    * If you are using Toolbox on Mac, Toolbox on older Windows systems without Hyper-V, or Docker for Mac, use `virtualbox` as the driver, as shown in this example. (The Docker Machine VirtualBox driver reference is [here](drivers/virtualbox.md).) (See [prerequisites](#prerequisite-information) above to learn more.)
-        Running pre-create checks...
-        Creating machine...
-        (staging) Copying /Users/ripley/.docker/machine/cache/boot2docker.iso to /Users/ripley/.docker/machine/machines/default/boot2docker.iso...
-        (staging) Creating VirtualBox VM...
-        (staging) Creating SSH key...
-        (staging) Starting the VM...
-        (staging) Waiting for an IP...
-        Waiting for machine to be running, this may take a few minutes...
-        Machine is running, waiting for SSH to be available...
-        Detecting operating system of created instance...
-        Detecting the provisioner...
-        Provisioning with boot2docker...
-        Copying certs to the local machine directory...
-        Copying certs to the remote machine...
-        Setting Docker configuration on the remote daemon...
-        Checking connection to Docker...
-        Docker is up and running!
-        To see how to connect Docker to this machine, run: docker-machine env default
 
-      This command downloads a lightweight Linux distribution
+    * On Docker for Windows systems that support Hyper-V, use the `hyperv` driver as shown in the [Docker Machine Microsoft Hyper-V driver reference](drivers/hyper-v.md). (See [prerequisites](#prerequisite-information) above to learn more.)
-(<a href="https://github.com/boot2docker/boot2docker" target="_blank">boot2docker</a>) with the Docker daemon installed, and creates and starts a VirtualBox VM with Docker running.
+
+            $ docker-machine create --driver virtualbox default
+            Running pre-create checks...
+            Creating machine...
+            (staging) Copying /Users/ripley/.docker/machine/cache/boot2docker.iso to /Users/ripley/.docker/machine/machines/default/boot2docker.iso...
+            (staging) Creating VirtualBox VM...
+            (staging) Creating SSH key...
+            (staging) Starting the VM...
+            (staging) Waiting for an IP...
+            Waiting for machine to be running, this may take a few minutes...
+            Machine is running, waiting for SSH to be available...
+            Detecting operating system of created instance...
+            Detecting the provisioner...
+            Provisioning with boot2docker...
+            Copying certs to the local machine directory...
+            Copying certs to the remote machine...
+            Setting Docker configuration on the remote daemon...
+            Checking connection to Docker...
+            Docker is up and running!
+            To see how to connect Docker to this machine, run: docker-machine env default
+
+      This command downloads a lightweight Linux distribution (<a href="https://github.com/boot2docker/boot2docker" target="_blank">boot2docker</a>) with the Docker daemon installed, and creates and starts a VirtualBox VM with Docker running.
 
 4. List available machines again to see your newly minted machine.
 
@@ -211,7 +285,11 @@ For machines other than `default`, and commands other than those listed above, y
 
 ## Start local machines on startup
 
-In order to ensure that the Docker client is automatically configured at the start of each shell session, some users like to embed `eval $(docker-machine env default)` in their shell profiles (e.g., the `~/.bash_profile` file). However, this fails if the `default` machine is not running. If desired, you can configure your system to start the `default` machine automatically.
+In order to ensure that the Docker client is automatically configured at the
+start of each shell session, some users like to embed `eval $(docker-machine env
+default)` in their shell profiles (e.g., the `~/.bash_profile` file). However,
+this fails if the `default` machine is not running. If desired, you can
+configure your system to start the `default` machine automatically.
 
 Here is an example of how to configure this on OS X.
 
@@ -247,5 +325,7 @@ You can change the `default` string above to make this `LaunchAgent` start any
 
 -   Provision multiple Docker hosts [on your cloud provider](get-started-cloud.md)
 -   [Understand Machine concepts](concepts.md)
--   <a href="https://docs.docker.com/machine/drivers/" target="_blank">Docker Machine driver reference</a>
+- [Docker Machine list of reference pages for all supported drivers](/machine/drivers/index.md)
--   <a href="https://docs.docker.com/machine/reference/" target="_blank">Docker Machine subcommand reference</a>
+- [Docker Machine driver for Oracle VirtualBox](drivers/virtualbox.md)
+- [Docker Machine driver for Microsoft Hyper-V](drivers/hyper-v.md)
+- [`docker-machine` command line reference](reference/index.md)

docs/install-machine.md

@@ -66,7 +66,7 @@ You can find additional documentation in the comments at the <a href="https://gi
 ## Where to go next
 
 -   [Docker Machine overview](overview.md)
--   Create and run a Docker host on your [local system using VirtualBox](get-started.md)
+-   Create and run a Docker host on your [local system using virtualization](get-started.md)
 -   Provision multiple Docker hosts [on your cloud provider](get-started-cloud.md)
 -   <a href="https://docs.docker.com/machine/drivers/" target="_blank">Docker Machine driver reference</a>
 -   <a href="https://docs.docker.com/machine/reference/" target="_blank">Docker Machine subcommand reference</a>