From ea4b3365c58cd94c7e23cd8f275b5d2365f181a5 Mon Sep 17 00:00:00 2001 From: Chris Roberts Date: Thu, 1 Oct 2020 16:09:01 -0700 Subject: [PATCH] Update documentation in vmware provider --- website/data/docs-navigation.js | 2 +- website/pages/docs/providers/vmware/boxes.mdx | 8 +-- .../docs/providers/vmware/configuration.mdx | 33 +++++---- website/pages/docs/providers/vmware/faq.mdx | 69 +++++++++++++++++++ .../docs/providers/vmware/installation.mdx | 62 +---------------- .../docs/providers/vmware/kernel-upgrade.mdx | 61 ---------------- .../docs/providers/vmware/known-issues.mdx | 5 ++ .../vmware/vagrant-vmware-utility.mdx | 59 +++++++++++++++- 8 files changed, 160 insertions(+), 139 deletions(-) create mode 100644 website/pages/docs/providers/vmware/faq.mdx delete mode 100644 website/pages/docs/providers/vmware/kernel-upgrade.mdx diff --git a/website/data/docs-navigation.js b/website/data/docs-navigation.js index 53006f8c8..e87a4edc1 100644 --- a/website/data/docs-navigation.js +++ b/website/data/docs-navigation.js @@ -146,7 +146,7 @@ export default [ 'boxes', 'configuration', 'known-issues', - 'kernel-upgrade', + 'faq', ], }, { diff --git a/website/pages/docs/providers/vmware/boxes.mdx b/website/pages/docs/providers/vmware/boxes.mdx index f7b546291..f2596dbfa 100644 --- a/website/pages/docs/providers/vmware/boxes.mdx +++ b/website/pages/docs/providers/vmware/boxes.mdx @@ -63,7 +63,7 @@ in the box into a privately managed "vmwarevm" folder, and uses the first of Vagrant do not support linked clones. For more information on linked clones, please see the documentation. -## VMX Whitelisting +## VMX Allowlisting Settings in the VMX file control the behavior of the VMware virtual machine when it is booted. In the past Vagrant has removed the configured network @@ -74,14 +74,14 @@ While some boxes that use the predictable network interface names are configured to handle the VMX modifications Vagrant makes, it is better if Vagrant does not make the modification at all. -Vagrant will now warn if a whitelisted setting is detected within a Vagrant +Vagrant will now warn if a allowlisted setting is detected within a Vagrant box VMX file. If it is detected, a warning will be shown alerting the user and providing a configuration snippet. The configuration snippet can be used in the Vagrantfile if Vagrant fails to start the virtual machine. ### Making compatible boxes -These are the VMX settings the whitelisting applies to: +These are the VMX settings the allowlisting applies to: - `ethernet*.pcislotnumber` @@ -92,7 +92,7 @@ by adding a Vagrantfile to the box with the following content: ```ruby Vagrant.configure("2") do |config| config.vm.provider "vmware_desktop" do |vmware| - vmware.whitelist_verified = true + vmware.allowlist_verified = true end end ``` diff --git a/website/pages/docs/providers/vmware/configuration.mdx b/website/pages/docs/providers/vmware/configuration.mdx index da0f17f2a..698295beb 100644 --- a/website/pages/docs/providers/vmware/configuration.mdx +++ b/website/pages/docs/providers/vmware/configuration.mdx @@ -1,6 +1,6 @@ --- layout: docs -page_title: Configuration- VMware Provider +page_title: Configuration - VMware Provider sidebar_title: Configuration description: |- While Vagrant VMware providers are a drop-in replacement for VirtualBox, there @@ -27,6 +27,12 @@ end ## Provider settings +- `allowlist_verified` (bool, symbol) - Flag that VMware box has been properly configured + for allow list VMX settings. `true` if verified, `false` if unverified, `:disable_warning` + to silence allowlist warnings. +- `base_address` (string) - Address to be reserved from the DHCP server. This option + requires the `base_mac` option to be set as well. +- `base_mac` (string) - Custom MAC address to be used for the default NAT interface device - `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` @@ -34,30 +40,29 @@ end 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. + This defaults to `true` if linked clones are functional based on VMware installation. +- `nat_device` (string) - The host vmnet device to use for the default NAT interface. By + default this will be automatically detected with a fallback to `vmnet8`. - `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` +- `ssh_info_public` (bool) - Use the public IP address for SSH connections to guest. + This defaults to `false` +- `unmount_default_hgfs` (bool) - Unmount the default HGFS mount point within the guest. + This defaults to `false` - `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 +- `verify_vmnet` (bool) - Verify vmnet devices health before usage. + This defaults to `true` +- `vmx` (hash) - VMX key/value pairs to set or unset. If the value is `nil`, the key will + be deleted. ### VM Clone Directory @@ -122,3 +127,5 @@ config.vm.provider "vmware_desktop" do |v| v.vmx["numvcpus"] = "2" end ``` + +### VMware License Edition diff --git a/website/pages/docs/providers/vmware/faq.mdx b/website/pages/docs/providers/vmware/faq.mdx new file mode 100644 index 000000000..34d43cc58 --- /dev/null +++ b/website/pages/docs/providers/vmware/faq.mdx @@ -0,0 +1,69 @@ +--- +layout: docs +page_title: Frequently Asked Questions - VMware Provider +sidebar_title: FAQ +description: |- + Frequently asked questions related to using Vagrant with VMware + Workstation and VMware Fusion +--- + +# Frequently Asked Questions + +## Q: Can Vagrant VMware Plugin work without internet? + +No, Vagrant VMware plugin requires a new license every 6 weeks. Vagrant will try to renew the +license automatically. If you are on an environment without internet, after 4 weeks Vagrant will emit a warning, +and after 6 weeks, the VMware plugin will stop working. You can install a new license to reactive vagrant. + +## Q: I purchased a Vagrant VMware plugin license, but I did not receive an email? + +First, please check your JUNK or SPAM folders. Since the license comes from an +automated system, it might have been flagged as spam by your email provider. If +you do not see the email there, please [contact support](mailto:support@hashicorp.com?subject=License Not Received) +and include the original order number. + +## Q: Do I need to keep the Vagrant VMware plugin license file on disk? + +After you have installed the Vagrant VMware plugin license, it is safe to remove +your copy from disk. Vagrant copies the license into its structure for reference +on boot. + +## Q: Do I need to purchase a separate license for VMware Fusion/Workstation + +Yes. The Vagrant VMware desktop plugin license is only valid the for the Vagrant +plugin and cannot be used to license the VMware Fusion or VMware Workstation +application. + +## Q: I lost my original email, where can I download my Vagrant VMware plugin license again? + +Please [contact support](mailto:support@hashicorp.com?subject=Lost My License&body=Hello support! I seem to have misplaced my Vagrant VMware license. Could you please send it to me? Thanks!). **Note:** +please contact support using the email address with which you made the +original purchase. If you use an alternate email, you will be asked to verify +that you are the owner of the requested license. + +## Q: I upgraded my VMware product and now my license is invalid? + +The Vagrant VMware plugin licenses are valid for specific VMware product +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/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 +VMware products. If you do not wish to update at this time, you can rollback +your VMware installation to an older version. + +## 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: + +```shell-session +$ vagrant plugin install vagrant-vmware-desktop +``` + +To upgrade the Vagrant VMware utility, download the latest version from the +[Vagrant VMware utility downloads page](/vmware/downloads) and install the +system package to your local system. diff --git a/website/pages/docs/providers/vmware/installation.mdx b/website/pages/docs/providers/vmware/installation.mdx index 75b257f80..36fe3624a 100644 --- a/website/pages/docs/providers/vmware/installation.mdx +++ b/website/pages/docs/providers/vmware/installation.mdx @@ -3,8 +3,8 @@ layout: docs page_title: Installation - VMware Provider sidebar_title: Installation description: |- - The Vagrant VMware provider can be installed using the standard plugin - installation procedure. + The Vagrant VMware provider requires a two step installation + process which includes a system package and a Vagrant plugin. --- # Installation @@ -29,7 +29,7 @@ For more information on plugin installation, please see the [Vagrant plugin usage documentation](/docs/plugins/usage). The Vagrant VMware plugin is a commercial product provided by -[HashiCorp](https://www.hashicorp.com) and **require the purchase of a license** +[HashiCorp](https://www.hashicorp.com) and **requires the purchase of a license** to operate. To purchase a license, please visit the [Vagrant VMware provider](/vmware#buy-now) page. Upon purchasing a license, you will receive a license file in your inbox. Download @@ -95,62 +95,6 @@ Desktop plugin: $ vagrant plugin update vagrant-vmware-desktop ``` -## Frequently Asked Questions - -**Q: Can Vagrant VMware Plugin work without internet?** - -No, Vagrant VMware plugin requires a new license every 6 weeks. Vagrant will try to renew the -license automatically. If you are on an environment without internet, after 4 weeks Vagrant will emit a warning, -and after 6 weeks, the VMware plugin will stop working. You can install a new license to reactive vagrant. - -**Q: I purchased a Vagrant VMware plugin license, but I did not receive an email?** - -First, please check your JUNK or SPAM folders. Since the license comes from an -automated system, it might have been flagged as spam by your email provider. If -you do not see the email there, please [contact support](mailto:support@hashicorp.com?subject=License Not Received) -and include the original order number. - -**Q: Do I need to keep the Vagrant VMware plugin license file on disk?** - -After you have installed the Vagrant VMware plugin license, it is safe to remove -your copy from disk. Vagrant copies the license into its structure for reference -on boot. - -**Q: I lost my original email, where can I download my Vagrant VMware plugin license again?** - -Please [contact support](mailto:support@hashicorp.com?subject=Lost My License&body=Hello support! I seem to have misplaced my Vagrant VMware license. Could you please send it to me? Thanks!). **Note:** -please contact support using the email address with which you made the -original purchase. If you use an alternate email, you will be asked to verify -that you are the owner of the requested license. - -**Q: I upgraded my VMware product and now my license is invalid?** - -The Vagrant VMware plugin licenses are valid for specific VMware product -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/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 -VMware products. If you do not wish to update at this time, you can rollback -your VMware installation to an older version. - -**Q: Why is the Vagrant VMware plugin not working with my trial version of VMware Fusion/Workstation?** - -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: 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: - -```shell-session -$ vagrant plugin install vagrant-vmware-desktop -``` ## Support diff --git a/website/pages/docs/providers/vmware/kernel-upgrade.mdx b/website/pages/docs/providers/vmware/kernel-upgrade.mdx deleted file mode 100644 index 0f9662a3d..000000000 --- a/website/pages/docs/providers/vmware/kernel-upgrade.mdx +++ /dev/null @@ -1,61 +0,0 @@ ---- -layout: docs -page_title: Kernel Upgrade - VMware Provider -sidebar_title: Kernel Upgrade -description: |- - If as part of running your Vagrant environment with VMware, you perform - a kernel upgrade, it is likely that the VMware guest tools will stop working. - This breaks features of Vagrant such as synced folders and sometimes - networking as well. ---- - -# Kernel Upgrade - -If as part of running your Vagrant environment with VMware, you perform -a kernel upgrade, it is likely that the VMware guest tools will stop working. -This breaks features of Vagrant such as synced folders and sometimes -networking as well. - -This page documents how to upgrade your kernel and keep your guest tools -functioning. If you are not planning to upgrade your kernel, then you can safely -skip this page. - -## Enable Auto-Upgrade of VMware Tools - -If you are running a common OS, VMware tools can often auto-upgrade themselves. -This setting is disabled by default. The Vagrantfile settings below will -enable auto-upgrading: - -```ruby -# Ensure that VMware Tools recompiles kernel modules -# when we update the linux images -$fix_vmware_tools_script = <