beckermj/vaguerent
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Update documentation in vmware provider

Browse Source
This commit is contained in:
Chris Roberts 2020-10-01 16:09:01 -07:00
parent c34fcc5a54
commit ea4b3365c5
8 changed files with 160 additions and 139 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

2
website/data/docs-navigation.js
View File

@ -146,7 +146,7 @@ export default [
'boxes',
'configuration',
'known-issues',
'kernel-upgrade',
'faq',
],
},
{

8
website/pages/docs/providers/vmware/boxes.mdx
View File

@ -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
```

33
website/pages/docs/providers/vmware/configuration.mdx
View File

@ -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

69
website/pages/docs/providers/vmware/faq.mdx Normal file
View File

@ -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.

62
website/pages/docs/providers/vmware/installation.mdx
View File

@ -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

61
website/pages/docs/providers/vmware/kernel-upgrade.mdx
View File

@ -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 = <<SCRIPT
sed -i.bak 's/answer AUTO_KMODS_ENABLED_ANSWER no/answer AUTO_KMODS_ENABLED_ANSWER yes/g' /etc/vmware-tools/locations
sed -i 's/answer AUTO_KMODS_ENABLED no/answer AUTO_KMODS_ENABLED yes/g' /etc/vmware-tools/locations
SCRIPT
Vagrant.configure("2") do |config|
# ...
config.vm.provision "shell", inline: $fix_vmware_tools_script
end
```
Note that this does not work for every OS, so `vagrant up` with the above
settings, do a kernel upgrade, and do a `vagrant reload`. If HGFS (synced
folders) and everything appears to be working, great! If not, then read on...
## Manually Reinstalling VMware Tools
At this point, you will have to manually reinstall VMware tools. The best
source of information for how to do this is the
[VMware documentation](https://kb.vmware.com/selfservice/microsites/search.do?language=en_US&cmd=displayKC&externalId=1018414).
There are some gotchas:
- Make sure you have the kernel headers properly installed. This varies
by distro but is generally a package available via the package manager.
- Watch the installation output carefully. Even if HGFS (synced folders)
support failed to build, the installer will output that installing VMware
tools was successful. Read the output to find any error messages.

5
website/pages/docs/providers/vmware/known-issues.mdx
View File

@ -23,6 +23,11 @@ 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.
Please note that this issue is resolved when using VMware Workstation 15 or
VMware Fusion 11 with a professional license. Due to advanced networking
tools not being available when using a standard VMWare license, this behavior
is still experienced when using a standard license.
## Forwarded Ports Failing in Workstation on Windows
VMware Workstation has a bug on Windows where forwarded ports do not work

59
website/pages/docs/providers/vmware/vagrant-vmware-utility.mdx
View File

@ -68,7 +68,7 @@ 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:
On POSIX-style platforms these certificates can be found at:
```text
/opt/vagrant-vmware-desktop/certificates
@ -116,3 +116,60 @@ $ sudo /etc/init.d/vagrant-vmware-utility start
```shell-session
$ sudo sv start vagrant-vmware-utility
```
## Utility Service Configuration
When installing the Vagrant VMware utility service, a configuration file is generated
that is used when the process is started. On windows, this can be found at:
```text
C:\ProgramData\HashiCorp\vagrant-vmware-desktop\config\service.hcl
```
On POSIX-style systems, it can be found at:
```text
/opt/vagrant-vmware-desktop/config/service.hcl
```
The configuration file uses the [HCL](https://github.com/hashicorp/hcl) configuration
language. It supports a subset of the options provided by the CLI. An example configuration
file looks like:
```hcl
core {
level = "info"
}
api {
port = 9922
driver = "advanced"
license_override = "standard"
}
```
### Core options
- `level` (string) - Output level of the logger
- `log_file` (string) - Store logs to file at given path
- `log_append` (bool) - Append log output to existing file
### API options
- `port` (int) - Port to bind the API (changes require changes to [Vagrant configuration](/docs/providers/vmware/configuration#utility_port))
- `driver` (string) - Internal driver to use (utility will auto-detect correct driver)
- `license_override` (string) - Override the detected VMware license (standard or professional)
### macOS service configuration
The Vagrant VMware utility service configuration on macOS is slightly different
than other platforms. If the `port` option is updated in the configuration file,
it will not be applied after restarting the service. This is due to the port
being defined directly within the service file so it properly matches the service
socket information. To update the port on macOS, it is easier to uninstall the
service and then install it again:
```shell-session
$ /opt/vagrant-vmware-desktop/bin/vagrant-vmware-utility service uninstall
$ /opt/vagrant-vmware-desktop/bin/vagrant-vmware-utility service install -port=9999
```