From f41cc8d6b3140165a3e96bc00bf0caaa37f60c4b Mon Sep 17 00:00:00 2001 From: Chris Roberts Date: Tue, 20 Feb 2018 11:56:40 -0800 Subject: [PATCH 1/3] Update vmware provider documentation --- website/config.rb | 3 + .../source/docs/vmware/configuration.html.md | 88 ++++++++------ .../source/docs/vmware/installation.html.md | 59 +++------ .../source/docs/vmware/known-issues.html.md | 13 +- website/source/docs/vmware/usage.html.md | 22 +--- .../vmware/vagrant-vmware-utility.html.md.erb | 115 ++++++++++++++++++ website/source/layouts/docs.erb | 1 + website/source/vmware/downloads.html.erb | 60 +++++++++ 8 files changed, 263 insertions(+), 98 deletions(-) create mode 100644 website/source/docs/vmware/vagrant-vmware-utility.html.md.erb create mode 100644 website/source/vmware/downloads.html.erb diff --git a/website/config.rb b/website/config.rb index d97dd0839..52536a432 100644 --- a/website/config.rb +++ b/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" diff --git a/website/source/docs/vmware/configuration.html.md b/website/source/docs/vmware/configuration.html.md index d4555bf6a..7211c4d3a 100644 --- a/website/source/docs/vmware/configuration.html.md +++ b/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 -"~/Applications." If you put your applications in some other place, you will -have to manually tell Vagrant where VMware Fusion is. - -This can be done with the `VAGRANT_VMWARE_FUSION_APP` environmental variable. - -For example, if you put your applications in an "/Apps" directory, you -would configure Vagrant like this: - -``` -$ export VAGRANT_VMWARE_FUSION_APP="/Apps/VMware Fusion.app" -$ vagrant up --provider=vmware_fusion +```ruby +Vagrant.configure("2") do |config| + config.vm.box = "my-box" + config.vm.provider "vmware_desktop" do |v| + v.gui = true + end +end ``` -## 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 - -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 +### 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 diff --git a/website/source/docs/vmware/installation.html.md b/website/source/docs/vmware/installation.html.md index 4af167216..a1edb254d 100644 --- a/website/source/docs/vmware/installation.html.md +++ b/website/source/docs/vmware/installation.html.md @@ -9,23 +9,22 @@ description: |- # Installation -The Vagrant VMware provider can be installed using the standard plugin -installation procedure. VMware Fusion users should run: +Installation of the Vagrant VMware provider requires two steps. First the +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). -```text -$ vagrant plugin install vagrant-vmware-fusion -``` +Next, install the Vagrant VMware provider plugin using the standard plugin +installation procedure: -VMware Workstation users should run: - -```text -$ vagrant plugin install vagrant-vmware-workstation +```shell +$ 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 +37,11 @@ this file and save it to a temporary location on your computer. requiring their own license. -After installing the correct Vagrant VMware product plugin for your system, you -will need to install the license. For VMware Fusion users: +After installing the Vagrant VMware Desktop plugin for your system, you +will need to install the license: -```text -$ vagrant plugin license vagrant-vmware-fusion ~/license.lic -``` - -For VMware Workstation users: - -```text -$ vagrant plugin license vagrant-vmware-workstation ~/license.lic +```shell +$ vagrant plugin license vagrant-vmware-desktop ~/license.lic ``` The first parameter is the name of the plugin, and the second parameter is the @@ -58,13 +51,12 @@ After you have installed the plugin license, you may remove the temporary file. To verify the license installation, run: -```text -$ vagrant plugin list +```shell +$ 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?**
@@ -90,7 +82,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 +94,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?**
-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?**
You can update the Vagrant VMware plugin to the latest version by re-running the -install command. For VMware Fusion: +install command: -```text -$ vagrant plugin install vagrant-vmware-fusion +```shell +$ 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 diff --git a/website/source/docs/vmware/known-issues.html.md b/website/source/docs/vmware/known-issues.html.md index abf50ddea..9ed4c8099 100644 --- a/website/source/docs/vmware/known-issues.html.md +++ b/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 diff --git a/website/source/docs/vmware/usage.html.md b/website/source/docs/vmware/usage.html.md index 5ede22e82..71a98a7f6 100644 --- a/website/source/docs/vmware/usage.html.md +++ b/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 -``` - -VMware Workstation users should then run: - -```shell -$ vagrant up --provider vmware_workstation +$ vagrant up --provider vmware_desktop ``` This will download and bring up a new VMware Fusion/Workstation virtual machine in Vagrant. - -
- Note: 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. -
diff --git a/website/source/docs/vmware/vagrant-vmware-utility.html.md.erb b/website/source/docs/vmware/vagrant-vmware-utility.html.md.erb new file mode 100644 index 000000000..fb878400d --- /dev/null +++ b/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. + +
+Download <%= vmware_utility_version %> +
+ +## 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 +``` diff --git a/website/source/layouts/docs.erb b/website/source/layouts/docs.erb index 3bee5f94f..d83386004 100644 --- a/website/source/layouts/docs.erb +++ b/website/source/layouts/docs.erb @@ -149,6 +149,7 @@ VMware