Merge pull request #9620 from chrisroberts/e-docs-vmware

Documentation update

website/config.rb

@@ -1,5 +1,8 @@
 set :base_url, "https://www.vagrantup.com/"
 
+set :vmware_utility_name, "vagrant-vmware-utility"
+set :vmware_utility_version, "1.0.0"
+
 activate :hashicorp do |h|
   h.name         = "vagrant"
   h.version      = "2.0.3"

website/source/assets/javascripts/_vmware.js

@@ -27,10 +27,8 @@ var HashiVMware = function() {
     }
 
     var productId = "";
-    if (selectedProduct == "fusion") {
+    if (selectedProduct == "desktop") {
-      productId = "279661674";
+      productId = "549797756979";
-    } else if (selectedProduct == "workstation") {
-      productId = "302167489";
     } else {
       alert("Unknown product selected. Please refresh and try again.");
       return;

website/source/docs/vmware/configuration.html.md

@@ -10,27 +10,56 @@ description: |-
 
 # Configuration
 
-While Vagrant VMware providers are a drop-in replacement for VirtualBox, there
+While Vagrant VMware Desktop provider is a drop-in replacement for VirtualBox, there
 are some additional features that are exposed that allow you to more finely
 configure VMware-specific aspects of your machines.
 
-## "VMware Fusion.app" Location
+Configuration settings for the provider are set in the Vagrantfile:
 
-The provider by default looks for VMware Fusion in "/Applications" and
+```ruby
-"~/Applications." If you put your applications in some other place, you will
+Vagrant.configure("2") do |config|
-have to manually tell Vagrant where VMware Fusion is.
+  config.vm.box = "my-box"
-
+  config.vm.provider "vmware_desktop" do |v|
-This can be done with the `VAGRANT_VMWARE_FUSION_APP` environmental variable.
+    v.gui = true
-
+  end
-For example, if you put your applications in an "/Apps" directory, you
+end
-would configure Vagrant like this:
-
-```
-$ export VAGRANT_VMWARE_FUSION_APP="/Apps/VMware Fusion.app"
-$ vagrant up --provider=vmware_fusion
 ```
 
-## VM Clone Directory
+## Provider settings
+
+* `clone_directory` (string) - Path for storing VMware clones. This value can
+  also be set using the `VAGRANT_VMWARE_CLONE_DIRECTORY` environment variable.
+  This defaults to `./.vagrant`
+* `enable_vmrun_ip_lookup` (bool) - Use vmrun to discover guest IP address.
+  This defaults to `true`
+* `functional_hgfs` (bool) - HGFS is functional within the guest.
+  This defaults to detected capability of the guest
+* `unmount_default_hgfs` (bool) - Unmount the default HGFS mount point within the guest.
+  This defaults to `false`
+* `gui` (bool) - Launch guest with a GUI.
+  This defaults to `false`
+* `ssh_info_public` (bool) - Use the public IP address for SSH connections to guest.
+  This defaults to `false`
+* `verify_vmnet` (bool) - Verify vmnet devices health before usage.
+  This defaults to `true`
+* `linked_clone` (bool) - Use linked clones instead of full copy clones.
+  This defaults to `true`
+* `vmx` (hash) - VMX key/value pairs to set or unset. If the value is `nil`, the key will
+  be deleted.
+* `whitelist_verified` (bool, symbol) - Flag that VMware box has been properly configured
+  for whitelisted VMX settings. `true` if verified, `false` if unverified, `:disable_warning`
+  to silence whitelist warnings.
+* `port_forward_network_pause` - Number of seconds to pause after applying port forwarding
+  configuration. This allows guest time to acquire DHCP address if previous address is
+  dropped when VMware network services are restarted.
+  This defaults to `0`
+* `utility_port` (integer) - Listen port of the Vagrant VMware Utility service.
+  This defaults to `9922`
+* `utility_certificate_path` (string) - Path to the Vagrant VMware Utility service
+  certificates directory.
+  The default value is dependent on the host
+
+### VM Clone Directory
 
 By default, the VMware provider will clone the VMware VM in the box
 to the ".vagrant" folder relative to the folder where the Vagrantfile is.
@@ -44,8 +73,7 @@ variable. This does not need to be unique per project. Each project will
 get a different sub-directory within this folder. Therefore, it is safe to
 set this systemwide.
 
-
+### Linked Clones
-## Linked Clones
 
 By default new machines are created using a linked clone to the base
 box. This reduces the time and required disk space incurred by directly
@@ -57,41 +85,23 @@ differencing disk images are created where the parent disk image belongs to
 the master VM. To disable linked clones:
 
 ```ruby
-config.vm.provider "vmware_fusion" do |v|
+config.vm.provider "vmware_desktop" do |v|
   v.linked_clone = false
 end
 ```
 
-## Virtual Machine GUI
+### VMX Customization
-
-The VMware provider generally starts the virtual machines
-in headless mode. If you would like to see the UI because you are running
-a desktop within the VM, or if you need to debug potential boot issues
-with the VM, you can configure the VMware provider to boot with the
-GUI:
-
-```ruby
-config.vm.provider "vmware_fusion" do |v|
-  v.gui = true
-end
-```
-
-Use "vmware_workstation" if you are using VMware workstation.
-
-## VMX Customization
 
 If you want to add or remove specific keys from the VMX file, you can do
 that:
 
 ```ruby
-config.vm.provider "vmware_fusion" do |v|
+config.vm.provider "vmware_desktop" do |v|
   v.vmx["custom-key"]  = "value"
   v.vmx["another-key"] = nil
 end
 ```
 
-Use "vmware_workstation" if you are using VMware workstation.
-
 In the example above, the "custom-key" key will be set to "value" and the
 "another-key" key will be removed from the VMX file.
 
@@ -107,7 +117,7 @@ The most common keys people look for are setting memory and CPUs.
 The example below sets both:
 
 ```ruby
-config.vm.provider "vmware_fusion" do |v|
+config.vm.provider "vmware_desktop" do |v|
   v.vmx["memsize"] = "1024"
   v.vmx["numvcpus"] = "2"
 end

website/source/docs/vmware/installation.html.md

@@ -9,23 +9,26 @@ description: |-
 
 # Installation
 
-The Vagrant VMware provider can be installed using the standard plugin
+If you are upgrading from the Vagrant VMware Workstation or Vagrant
-installation procedure. VMware Fusion users should run:
+VMware Fusion plugins, please halt or destroy all VMware VMs currently
+being managed by Vagrant. Then continue with the instructions below.
 
-```text
+Installation of the Vagrant VMware provider requires two steps. First the
-$ vagrant plugin install vagrant-vmware-fusion
+Vagrant VMware Utility must be installed. This can be done by downloading
-```
+and installing the correct system package from the [Vagrant VMware Utility
+downloads page](/vmware/downloads.html).
 
-VMware Workstation users should run:
+Next, install the Vagrant VMware provider plugin using the standard plugin
+installation procedure:
 
-```text
+```shell
-$ vagrant plugin install vagrant-vmware-workstation
+$ vagrant plugin install vagrant-vmware-desktop
 ```
 
 For more information on plugin installation, please see the
 [Vagrant plugin usage documentation](/docs/plugins/usage.html).
 
-The Vagrant VMware plugins are commercial products provided by
+The Vagrant VMware plugin is a commercial product provided by
 [HashiCorp](https://www.hashicorp.com) and **require the purchase of a license**
 to operate. To purchase a license, please visit the
 [Vagrant VMware provider](/vmware#buy-now) page. Upon
@@ -38,17 +41,11 @@ this file and save it to a temporary location on your computer.
   requiring their own license.
 </div>
 
-After installing the correct Vagrant VMware product plugin for your system, you
+After installing the Vagrant VMware Desktop plugin for your system, you
-will need to install the license. For VMware Fusion users:
+will need to install the license:
 
-```text
+```shell
-$ vagrant plugin license vagrant-vmware-fusion ~/license.lic
+$ vagrant plugin license vagrant-vmware-desktop ~/license.lic
-```
-
-For VMware Workstation users:
-
-```text
-$ vagrant plugin license vagrant-vmware-workstation ~/license.lic
 ```
 
 The first parameter is the name of the plugin, and the second parameter is the
@@ -58,13 +55,12 @@ After you have installed the plugin license, you may remove the temporary file.
 
 To verify the license installation, run:
 
-```text
+```shell
-$ vagrant plugin list
+$ vagrant
 ```
 
 If the license is not installed correctly, you will see an error message.
 
-
 ## Frequently Asked Questions
 
 **Q: I purchased a Vagrant VMware plugin license, but I did not receive an email?**<br>
@@ -90,7 +86,7 @@ versions at the time of purchase. When new versions of VMware products are
 released, significant changes to the plugin code are often required to support
 this new version. For this reason, you may need to upgrade your current license
 to work with the new version of the VMware product. Customers can check their
-license upgrade eligibility by visiting the [License Upgrade Center](https://license.hashicorp.com/upgrade/vmware2015)
+license upgrade eligibility by visiting the [License Upgrade Center](https://license.hashicorp.com/upgrade/vmware)
 and entering the email address with which they made the original purchase.
 
 Your existing license will continue to work with all previous versions of the
@@ -102,27 +98,14 @@ The Vagrant VMware Fusion and Vagrant VMware Workstation plugins are not
 compatible with trial versions of the VMware products. We apologize for the
 inconvenience.
 
-**Q: I accidentally bought the wrong Vagrant VMware plugin, can I switch?**<br>
-Sure! Even though the Vagrant VMware Fusion plugin and the Vagrant VMware
-Workstation plugin are different products, they are the same price and fall
-under the same EULA. As such, we can transfer the license for you. Please
-[contact support](mailto:support@hashicorp.com?subject=Transfer License).
-
 **Q: How do I upgrade my currently installed Vagrant VMware plugin?**<br>
 You can update the Vagrant VMware plugin to the latest version by re-running the
-install command. For VMware Fusion:
+install command:
 
-```text
+```shell
-$ vagrant plugin install vagrant-vmware-fusion
+$ vagrant plugin install vagrant-vmware-desktop
 ```
 
-For VMWare Workstation:
-
-```text
-$ vagrant plugin install vagrant-vmware-workstation
-```
-
-
 ## Support
 If you have any issues purchasing, installing, or using the Vagrant VMware
 plugins, please [contact support](mailto:support@hashicorp.com). To

website/source/docs/vmware/known-issues.html.md

@@ -3,17 +3,26 @@ layout: "docs"
 page_title: "Known Issues - VMware Provider"
 sidebar_current: "providers-vmware-known-issues"
 description: |-
-  This page tracks some known issues or limitations of the VMware providers.
+  This page tracks some known issues or limitations of the VMware provider.
   Note that none of these are generally blockers to using the provider, but
   are good to know.
 ---
 
 # Known Issues
 
-This page tracks some known issues or limitations of the VMware providers.
+This page tracks some known issues or limitations of the VMware provider.
 Note that none of these are generally blockers to using the provider, but
 are good to know.
 
+## Network disconnect
+
+When Vagrant applies port forwarding rules while bring up a guest instance,
+other running VMware VMs may experience a loss of network connectivity. The
+cause of this connectivity issue is the restarting of the VMware NAT service
+to apply new port forwarding rules. Since new rules cannot be applied to the
+NAT service while it is running, it is required to restart the service, which
+results in the loss of connectivity.
+
 ## Forwarded Ports Failing in Workstation on Windows
 
 VMware Workstation has a bug on Windows where forwarded ports do not work

website/source/docs/vmware/usage.html.md

@@ -9,11 +9,12 @@ description: |-
 
 # Usage
 
-The Vagrant VMware providers are used just like any other provider. Please
+The Vagrant VMware provider is used just like any other provider. Please
 read the general [basic usage](/docs/providers/basic_usage.html) page for
 providers.
 
-The value to use for the `--provider` flag is `vmware_fusion` for VMware
+The value to use for the `--provider` flag is `vmware_desktop`. For compatibility
+with older versions of the plugin, `vmware_fusion` can be used for VMware
 Fusion, and `vmware_workstation` for VMware Workstation.
 
 The Vagrant VMware provider does not support parallel execution at this time.
@@ -28,24 +29,11 @@ Vagrant.configure("2") do |config|
 end
 ```
 
-VMware Fusion users should then run:
+Then run:
 
 ```shell
-$ vagrant up --provider vmware_fusion
+$ vagrant up --provider vmware_desktop
-```
-
-VMware Workstation users should then run:
-
-```shell
-$ vagrant up --provider vmware_workstation
 ```
 
 This will download and bring up a new VMware Fusion/Workstation virtual machine
 in Vagrant.
-
-<div class="alert alert-info">
-  <strong>Note:</strong> At some point in the future, the providers
-  will probably be merged into a single `vagrant-vmware` plugin. For now,
-  the Workstation and Fusion codebases are different enough that they
-  are separate plugins.
-</div>

website/source/docs/vmware/vagrant-vmware-utility.html.md.erb

@@ -0,0 +1,115 @@
+---
+layout: "docs"
+page_title: "Installation - VMware Provider"
+sidebar_current: "providers-vmware-utility"
+description: |-
+  The Vagrant VMware Utility works with the Vagrant VMware Provider to
+  interact with the system VMware installation.
+---
+
+# Vagrant VMware Utility Installation
+
+## System Packages
+
+The Vagrant VMware Utility is provided as a system package. To install the
+utility, download and install the correct system package from the downloads
+page.
+
+<center>
+<a class="button" href="/vmware/downloads.html">Download <%= vmware_utility_version %></a>
+</center>
+
+## Manual Installation
+
+If there is no officially supported system package of the utility available,
+it may be possible to manually install utility. This applies to Linux platforms
+only. First, download the latest zip package from the releases page.
+
+Next create a directory for the executable and unpack the executable as
+root.
+
+```shell
+sudo mkdir /opt/vagrant-vmware-utility/bin
+sudo unzip -d /opt/vagrant-vmware-utility/bin vagrant-vmware-utility_1.0.0_x86_64.zip
+```
+
+After the executable has been installed, the utility setup tasks must be run. First,
+generate the required certificates:
+
+```shell
+sudo /opt/vagrant-vmware-utility/bin/vagrant-vmware-utility certificate generate
+```
+
+The path provided from this command can be used to set the [`utility_certificate_path`]
+(/docs/vmware/configuration.html#utility_certificate_path) in the Vagrantfile
+configuration if installing to a non-standard path.
+
+Finally, install the service. This will also enable the service.
+
+```shell
+sudo /usr/local/vagrant-vmware-utility/vagrant-vmware-utility service install
+```
+
+# Usage
+
+The Vagrant VMware Utility provides the Vagrant VMware provider plugin access
+to various VMware functionalities. The Vagrant VMware Utility is required by
+the Vagrant VMware Desktop provider plugin.
+
+## Vagrant VMware Utility Access
+
+The Vagrant VMware Utility provides support for all users on the system using
+the Vagrant VMware Desktop plugin. If access restrictions to the Utility need
+to be applied to users on the system, this can be accomplished by restricting
+user access to the certificates used for connecting to the service.
+
+On Windows platforms these certificates can be found at:
+
+* C:\ProgramData\HashiCorp\vagrant-vmware-desktop\certificates
+
+On POSIX platforms these certificates can be found at:
+
+* /opt/vagrant-vmware-desktop/certificates
+
+## Vagrant VMware Utility Service
+
+The Vagrant VMware Utility consists of a small service which runs on the
+host platform. When the utility installer package is installed, the service
+is configured to automatically start. If the plugin reports errors communicating
+with the service, it may have stopped for some reason. The most common cause of
+the service not being in a running state is the VMware application not being
+installed. The service can be started again by using the proper command below:
+
+### Windows
+
+On Windows platforms a service is created called `vagrant-vmware-utility`. The
+service can be manually started using the services GUI (`services.msc`) or by
+running the following command from a `cmd.exe` in administrator mode:
+
+```shell
+> net.exe start vagrant-vmware-utility
+```
+
+### macOS
+
+```shell
+> sudo launchctl load -w /Library/LaunchDaemons/com.vagrant.vagrant-vmware-utility.plist
+```
+
+### Linux systemd
+
+```shell
+> sudo systemctl start vagrant-vmware-utility
+```
+
+### Linux SysVinit
+
+```shell
+> sudo /etc/init.d/vagrant-vmware-utility start
+```
+
+### Linux runit
+
+```shell
+> sudo sv start vagrant-vmware-utility
+```

website/source/layouts/docs.erb

@@ -149,6 +149,7 @@
             <a href="/docs/vmware/">VMware</a>
             <ul class="nav">
               <li<%= sidebar_current("providers-vmware-installation") %>><a href="/docs/vmware/installation.html">Installation</a></li>
+              <li<%= sidebar_current("providers-vmware-utility") %>><a href="/docs/vmware/vagrant-vmware-utility.html">VMware Utility</a></li>
               <li<%= sidebar_current("providers-vmware-usage") %>><a href="/docs/vmware/usage.html">Usage</a></li>
               <li<%= sidebar_current("providers-vmware-boxes") %>><a href="/docs/vmware/boxes.html">Boxes</a></li>
               <li<%= sidebar_current("providers-vmware-configuration") %>><a href="/docs/vmware/configuration.html">Configuration</a></li>

website/source/vmware/downloads.html.erb

@@ -0,0 +1,60 @@
+---
+layout: "downloads"
+sidebar_current: "vmware"
+page_title: "Vagrant VMware Utility Download"
+description: |-
+  This page lists all the available downloads for the Vagrant VMware Utility.
+---
+
+<h1>Download Vagrant VMware Utility</h1>
+
+<div class="downloads">
+  <div class="description row">
+    <div class="col-md-12">
+      <p>
+        Below are the available downloads for the latest version of the Vagrant
+        VMware Utility (<%= vmware_utility_version %>). Please download the proper package
+        for your operating system and architecture.
+      </p>
+      <p>
+        You can find the
+        <a href="https://releases.hashicorp.com/vagrant-vmware-utility/<%= vmware_utility_version %>/vagrant-vmware-utility_<%= vmware_utility_version %>_SHA256SUMS">
+          SHA256 checksums for the Vagrant VMware Utility <%= vmware_utility_version %>
+        </a>
+        online and you can
+        <a href="https://releases.hashicorp.com/vagrant-vmware-utility/<%= vmware_utility_version %>/vagrant-vmware-utility_<%= vmware_utility_version %>_SHA256SUMS.sig">
+          verify the checksum's signature file
+        </a>,
+        which has been signed using <a href="https://www.hashicorp.com/security.html" target="_blank" rel="nofollow noopener noreferrer">HashiCorp's GPG key</a>.
+        You can also <a href="https://releases.hashicorp.com/vagrant-vmware-utility/" target="_blank" rel="nofollow noopener noreferrer">download older versions of
+        the Vagrant VMware utility</a> from the releases service.
+      </p>
+    </div>
+  </div>
+
+  <% Middleman::HashiCorp::Releases.fetch(vmware_utility_name, vmware_utility_version).each do |os, arches| %>
+    <% next if os == "web" %>
+    <div class="row">
+      <div class="col-md-12 download">
+        <div class="icon pull-left"><%= system_icon(os) %></div>
+        <div class="details">
+          <h2 class="os-name"><%= pretty_os(os) %></h2>
+          <ul>
+            <% arches.each do |arch, url| %>
+              <li><a href="<%= url %>"><%= pretty_arch(arch) %></a></li>
+            <% end %>
+          </ul>
+          <div class="clearfix"></div>
+        </div>
+      </div>
+    </div>
+  <% end %>
+
+  <div class="row">
+    <div class="col-md-12 poweredby">
+      <a href="https://www.fastly.com?utm_source=hashicorp" target="_blank" rel="nofollow noopener noreferrer">
+        <%= inline_svg "fastly.svg", height: 50 %>
+      </a>
+    </div>
+  </div>
+</div>

website/source/vmware/index.html.erb

@@ -124,21 +124,16 @@ description: |-
           require an upgrade fee.
         </p>
         <p>
-          Choose the provider you want below and enter the number of seats
+          Enter the number of seats you wish to purchase below. Then,
-          you wish to purchase. Then, click the buy button and complete the
+          click the buy button and complete the order. Instructions to
-          flow and instructions to install and download the software will
+          install and download the software will be emailed to you.
-          be emailed to you.
         </p>
 
         <div class="form">
           <div class="products">
             <label class="radio">
-              <input type="radio" name="product" value="fusion" checked>
+              <input type="radio" name="product" value="desktop" checked>
-              VMware Fusion 10 or lower (Mac OS X)
+              VMware Fusion 10 / VMware Workstation 14 or lower
-            </label>
-            <label class="radio">
-              <input type="radio" name="product" value="workstation">
-              VMware Workstation 14 or lower (Linux and Windows)
             </label>
           </div>
           <div class="inputs">
@@ -160,7 +155,7 @@ description: |-
         <div class="subtext">
           Previous plugin versions may not support the latest VMware products.
           Please visit <a
-          href="http://license.hashicorp.com/upgrade/vmware2015">the license
+          href="http://license.hashicorp.com/upgrade/vmware">the license
           upgrade center</a> to check if your license requires an upgrade before
           you upgrade your VMware products.
         </div>
@@ -214,7 +209,7 @@ description: |-
         <h3>I already own a license, am I eligible for an upgrade?</h3>
         <p>
           Existing license holders may check their upgrade eligibility by
-          visiting <a href="http://license.hashicorp.com/upgrade/vmware2015">the license upgrade center</a>.
+          visiting <a href="http://license.hashicorp.com/upgrade/vmware">the license upgrade center</a>.
           If you are eligible for an upgrade, the system will generate a
           unique discount code that may be used when purchasing the new
           license.
@@ -232,7 +227,7 @@ description: |-
           may need to upgrade your current license to work with the new
           version of the VMware product. Customers can check their license
           upgrade eligibility by visiting the
-          <a href="http://license.hashicorp.com/upgrade/vmware2015">License Upgrade Center</a>
+          <a href="http://license.hashicorp.com/upgrade/vmware">License Upgrade Center</a>
           and entering the email address with which they made the original
           purchase.
         </p>
@@ -273,39 +268,6 @@ description: |-
         </p>
       </div>
     </div>
-    <div class="row">
-      <div class="col-md-12">
-        <h3>Since each license comes with two "seats", can I use one seat for the Vagrant VMware Fusion plugin and one seat for the Vagrant VMware Workstation plugin?</h3>
-        <p>
-          Unfortunately this is not possible at this time. The Vagrant VMware
-          Fusion plugin and the Vagrant VMware Workstation plugin are separate
-          products and cannot be shared in this manner. We apologize for the
-          inconvenience.
-        </p>
-        <p>
-          We do offer a 50% discount off the purchase of the other Vagrant
-          plugin for individual users and qualified candidates. Certain
-          restrictions do apply. Please <a href="mailto:support@hashicorp.com?subject=Multi-discount">email support</a>
-          to find out if you qualify. Unfortunately we cannot retroactively
-          apply this discount, so please email support before making your
-          purchase.
-        </p>
-      </div>
-    </div>
-    <div class="row">
-      <div class="col-md-12">
-        <h3>I accidentally bought the wrong Vagrant VMware plugin, can I switch?</h3>
-        <p>
-          Sure! Even though the Vagrant VMware Fusion plugin and the Vagrant
-          VMware Workstation plugin are different products, they are the same
-          price and fall under the same EULA. As such, we can transfer the
-          license for you. Please <a href="mailto:support@hashicorp.com?subject=Transfer License">contact support</a>
-          for assistance. Be sure to include your original order number. You
-          may be asked to confirm details your purchase to verify the
-          authenticity of your request.
-        </p>
-      </div>
-    </div>
     <div class="row">
       <div class="col-md-12">
         <h3>Does this include the VMware software?</h3>