From 3daf2b8db9ebbc04e224963d9609ce55eae0737f Mon Sep 17 00:00:00 2001 From: Jeff Escalante Date: Tue, 5 May 2020 18:11:12 -0400 Subject: [PATCH] port in raw content --- website/next.config.js | 4 +- website/pages/docs/boxes.html.md | 83 + website/pages/docs/boxes/base.html.md | 307 ++++ website/pages/docs/boxes/format.html.md | 123 ++ website/pages/docs/boxes/info.html.md | 42 + website/pages/docs/boxes/versioning.html.md | 107 ++ website/pages/docs/cli/aliases.html.md | 74 + website/pages/docs/cli/box.html.md | 216 +++ website/pages/docs/cli/cloud.html.md | 338 ++++ website/pages/docs/cli/connect.html.md | 34 + website/pages/docs/cli/destroy.html.md | 42 + website/pages/docs/cli/global-status.html.md | 39 + website/pages/docs/cli/halt.html.md | 29 + website/pages/docs/cli/index.html.md | 32 + website/pages/docs/cli/init.html.md | 71 + website/pages/docs/cli/login.html.md | 62 + .../pages/docs/cli/machine-readable.html.md | 162 ++ website/pages/docs/cli/non-primary.html.md | 34 + website/pages/docs/cli/package.html.md | 44 + website/pages/docs/cli/plugin.html.md | 165 ++ website/pages/docs/cli/port.html.md | 39 + website/pages/docs/cli/powershell.html.md | 23 + website/pages/docs/cli/provision.html.md | 28 + website/pages/docs/cli/rdp.html.md | 42 + website/pages/docs/cli/reload.html.md | 31 + website/pages/docs/cli/resume.html.md | 28 + website/pages/docs/cli/rsync-auto.html.md | 56 + website/pages/docs/cli/rsync.html.md | 24 + website/pages/docs/cli/share.html.md | 49 + website/pages/docs/cli/snapshot.html.md | 98 ++ website/pages/docs/cli/ssh.html.md | 140 ++ website/pages/docs/cli/ssh_config.html.md | 20 + website/pages/docs/cli/status.html.md | 18 + website/pages/docs/cli/suspend.html.md | 23 + website/pages/docs/cli/up.html.md | 48 + website/pages/docs/cli/upload.html.md | 30 + website/pages/docs/cli/validate.html.md | 24 + website/pages/docs/cli/version.html.md | 19 + website/pages/docs/cli/winrm.html.md | 26 + website/pages/docs/cli/winrm_config.html.md | 20 + .../pages/docs/disks/configuration.html.md | 112 ++ website/pages/docs/disks/index.html.md | 29 + website/pages/docs/disks/usage.html.md | 104 ++ .../disks/virtualbox/common-issues.html.md | 42 + .../pages/docs/disks/virtualbox/index.html.md | 43 + .../pages/docs/disks/virtualbox/usage.html.md | 35 + website/pages/docs/docker/basics.html.md | 128 ++ website/pages/docs/docker/boxes.html.md | 20 + website/pages/docs/docker/commands.html.md | 113 ++ .../pages/docs/docker/configuration.html.md | 123 ++ website/pages/docs/docker/index.html.md | 27 + website/pages/docs/docker/networking.html.md | 290 ++++ website/pages/docs/experimental/index.html.md | 56 + website/pages/docs/hyperv/boxes.html.md | 103 ++ .../pages/docs/hyperv/configuration.html.md | 57 + website/pages/docs/hyperv/index.html.md | 37 + website/pages/docs/hyperv/limitations.html.md | 35 + website/pages/docs/hyperv/usage.html.md | 25 + website/pages/docs/index.html.md | 24 + .../backwards-compatibility.html.md | 41 + website/pages/docs/installation/index.html.md | 96 + .../pages/docs/installation/source.html.md | 80 + .../docs/installation/uninstallation.html.md | 61 + .../installation/upgrading-from-1-0.html.md | 33 + .../pages/docs/installation/upgrading.html.md | 35 + .../pages/docs/multi-machine/index.html.md | 153 ++ .../pages/docs/networking/basic_usage.html.md | 48 + .../docs/networking/forwarded_ports.html.md | 122 ++ website/pages/docs/networking/index.html.md | 42 + .../docs/networking/private_network.html.md | 126 ++ .../docs/networking/public_network.html.md | 162 ++ website/pages/docs/other/debugging.html.md | 70 + .../other/environmental-variables.html.md | 321 ++++ website/pages/docs/other/index.html.md | 16 + .../pages/docs/other/macos-catalina.html.md | 32 + website/pages/docs/other/wsl.html.md | 135 ++ .../pages/docs/plugins/action-hooks.html.md | 83 + website/pages/docs/plugins/commands.html.md | 135 ++ .../pages/docs/plugins/configuration.html.md | 208 +++ .../docs/plugins/development-basics.html.md | 181 ++ .../docs/plugins/guest-capabilities.html.md | 104 ++ website/pages/docs/plugins/guests.html.md | 102 ++ .../docs/plugins/host-capabilities.html.md | 64 + website/pages/docs/plugins/hosts.html.md | 99 ++ website/pages/docs/plugins/index.html.md | 27 + website/pages/docs/plugins/packaging.html.md | 114 ++ website/pages/docs/plugins/providers.html.md | 237 +++ .../pages/docs/plugins/provisioners.html.md | 68 + website/pages/docs/plugins/usage.html.md | 74 + .../pages/docs/providers/basic_usage.html.md | 111 ++ .../docs/providers/configuration.html.md | 91 + website/pages/docs/providers/custom.html.md | 13 + website/pages/docs/providers/default.html.md | 29 + website/pages/docs/providers/index.html.md | 28 + .../pages/docs/providers/installation.html.md | 16 + .../pages/docs/provisioning/ansible.html.md | 151 ++ .../docs/provisioning/ansible_common.html.md | 210 +++ .../docs/provisioning/ansible_intro.html.md | 260 +++ .../docs/provisioning/ansible_local.html.md | 247 +++ .../docs/provisioning/basic_usage.html.md | 367 ++++ .../pages/docs/provisioning/cfengine.html.md | 173 ++ .../docs/provisioning/chef_apply.html.md | 104 ++ .../docs/provisioning/chef_client.html.md | 123 ++ .../docs/provisioning/chef_common.html.md | 136 ++ .../pages/docs/provisioning/chef_solo.html.md | 202 +++ .../pages/docs/provisioning/chef_zero.html.md | 91 + .../pages/docs/provisioning/docker.html.md | 208 +++ website/pages/docs/provisioning/file.html.md | 134 ++ website/pages/docs/provisioning/index.html.md | 49 + .../pages/docs/provisioning/podman.html.md | 176 ++ .../docs/provisioning/puppet_agent.html.md | 101 ++ .../docs/provisioning/puppet_apply.html.md | 238 +++ website/pages/docs/provisioning/salt.html.md | 203 +++ website/pages/docs/provisioning/shell.html.md | 250 +++ website/pages/docs/push/ftp.html.md | 63 + website/pages/docs/push/heroku.html.md | 61 + website/pages/docs/push/index.html.md | 59 + website/pages/docs/push/local-exec.html.md | 80 + website/pages/docs/share/connect.html.md | 54 + website/pages/docs/share/http.html.md | 88 + website/pages/docs/share/index.html.md | 51 + website/pages/docs/share/provider.html.md | 28 + website/pages/docs/share/security.html.md | 37 + website/pages/docs/share/ssh.html.md | 101 ++ .../docs/synced-folders/basic_usage.html.md | 128 ++ .../pages/docs/synced-folders/index.html.md | 23 + website/pages/docs/synced-folders/nfs.html.md | 233 +++ .../pages/docs/synced-folders/rsync.html.md | 106 ++ website/pages/docs/synced-folders/smb.html.md | 131 ++ .../docs/synced-folders/virtualbox.html.md | 43 + .../pages/docs/triggers/configuration.html.md | 208 +++ website/pages/docs/triggers/index.html.md | 93 + website/pages/docs/triggers/usage.html.md | 200 +++ .../pages/docs/vagrant-cloud/api.html.md.erb | 1538 +++++++++++++++++ .../docs/vagrant-cloud/boxes/catalog.html.md | 47 + .../boxes/create-version.html.md | 37 + .../docs/vagrant-cloud/boxes/create.html.md | 80 + .../vagrant-cloud/boxes/distributing.html.md | 59 + .../docs/vagrant-cloud/boxes/index.html.md | 32 + .../vagrant-cloud/boxes/lifecycle.html.md | 47 + .../docs/vagrant-cloud/boxes/private.html.md | 44 + .../boxes/release-workflow.html.md | 24 + .../docs/vagrant-cloud/boxes/using.html.md | 21 + .../pages/docs/vagrant-cloud/index.html.md | 25 + .../authentication-policy.html.md | 29 + .../organizations/create.html.md | 15 + .../vagrant-cloud/organizations/index.html.md | 14 + .../organizations/migrate.html.md | 26 + .../docs/vagrant-cloud/request-limits.html.md | 34 + .../pages/docs/vagrant-cloud/support.html.md | 47 + .../users/authentication.html.md | 56 + .../docs/vagrant-cloud/users/index.html.md | 11 + .../docs/vagrant-cloud/users/recovery.html.md | 13 + website/pages/docs/vagrantfile/index.html.md | 87 + .../docs/vagrantfile/machine_settings.html.md | 143 ++ .../docs/vagrantfile/ssh_settings.html.md | 146 ++ website/pages/docs/vagrantfile/tips.html.md | 72 + .../docs/vagrantfile/vagrant_settings.html.md | 63 + .../docs/vagrantfile/vagrant_version.html.md | 33 + .../pages/docs/vagrantfile/version.html.md | 64 + .../docs/vagrantfile/winrm_settings.html.md | 79 + .../docs/vagrantfile/winssh_settings.html.md | 78 + website/pages/docs/virtualbox/boxes.html.md | 165 ++ .../docs/virtualbox/common-issues.html.md | 33 + .../docs/virtualbox/configuration.html.md | 125 ++ website/pages/docs/virtualbox/index.html.md | 26 + .../pages/docs/virtualbox/networking.html.md | 74 + website/pages/docs/virtualbox/usage.html.md | 19 + website/pages/docs/vmware/boxes.html.md | 146 ++ .../pages/docs/vmware/configuration.html.md | 124 ++ website/pages/docs/vmware/index.html.md | 37 + .../pages/docs/vmware/installation.html.md | 156 ++ .../pages/docs/vmware/kernel-upgrade.html.md | 61 + .../pages/docs/vmware/known-issues.html.md | 35 + website/pages/docs/vmware/usage.html.md | 39 + .../vmware/vagrant-vmware-utility.html.md.erb | 115 ++ .../pages/intro/getting-started/boxes.html.md | 119 ++ .../pages/intro/getting-started/index.html.md | 61 + .../intro/getting-started/install.html.md | 55 + .../intro/getting-started/networking.html.md | 59 + .../getting-started/project_setup.html.md | 46 + .../intro/getting-started/providers.html.md | 45 + .../getting-started/provisioning.html.md | 106 ++ .../intro/getting-started/rebuild.html.md | 26 + .../pages/intro/getting-started/share.html.md | 63 + .../getting-started/synced_folders.html.md | 64 + .../intro/getting-started/teardown.html.md | 53 + .../pages/intro/getting-started/up.html.md | 55 + website/pages/intro/index.html.md | 73 + website/pages/intro/vs/cli-tools.md | 38 + website/pages/intro/vs/docker.html.md | 33 + website/pages/intro/vs/index.html.md | 21 + website/pages/intro/vs/terraform.html.md | 37 + website/pages/vmware/downloads.html.erb | 60 + website/pages/vmware/eula.html.md | 31 + website/pages/vmware/index.html.erb | 329 ++++ website/pages/vmware/privacy-policy.html.md | 78 + website/pages/vmware/reseller.html.md | 87 + website/pages/vmware/terms-of-service.html.md | 56 + website/public/favicon.ico | Bin 15086 -> 15086 bytes website/public/files/press-kit.zip | Bin 97652 -> 105319 bytes website/public/img/customers.png | Bin 0 -> 16370 bytes .../img/favicons/android-chrome-192x192.png | Bin 0 -> 11930 bytes .../img/favicons/android-chrome-512x512.png | Bin 0 -> 38331 bytes .../public/img/favicons/apple-touch-icon.png | Bin 0 -> 5510 bytes website/public/img/favicons/favicon-16x16.png | Bin 0 -> 1137 bytes website/public/img/favicons/favicon-32x32.png | Bin 0 -> 1990 bytes website/public/img/favicons/favicon.ico | Bin 0 -> 15086 bytes .../public/img/favicons/mstile-150x150.png | Bin 0 -> 3611 bytes .../public/img/favicons/safari-pinned-tab.svg | 116 ++ website/public/img/logo-hashicorp.svg | 5 + website/public/img/logo-text.svg | 5 + website/public/img/og-image.png | Bin 0 -> 11900 bytes website/public/img/parity.svg | 46 + website/public/img/systems/apple.svg | 3 + website/public/img/systems/linux.svg | 4 + website/public/img/systems/windows.svg | 3 + website/public/img/vmware.svg | 33 + 218 files changed, 18691 insertions(+), 2 deletions(-) create mode 100644 website/pages/docs/boxes.html.md create mode 100644 website/pages/docs/boxes/base.html.md create mode 100644 website/pages/docs/boxes/format.html.md create mode 100644 website/pages/docs/boxes/info.html.md create mode 100644 website/pages/docs/boxes/versioning.html.md create mode 100644 website/pages/docs/cli/aliases.html.md create mode 100644 website/pages/docs/cli/box.html.md create mode 100644 website/pages/docs/cli/cloud.html.md create mode 100644 website/pages/docs/cli/connect.html.md create mode 100644 website/pages/docs/cli/destroy.html.md create mode 100644 website/pages/docs/cli/global-status.html.md create mode 100644 website/pages/docs/cli/halt.html.md create mode 100644 website/pages/docs/cli/index.html.md create mode 100644 website/pages/docs/cli/init.html.md create mode 100644 website/pages/docs/cli/login.html.md create mode 100644 website/pages/docs/cli/machine-readable.html.md create mode 100644 website/pages/docs/cli/non-primary.html.md create mode 100644 website/pages/docs/cli/package.html.md create mode 100644 website/pages/docs/cli/plugin.html.md create mode 100644 website/pages/docs/cli/port.html.md create mode 100644 website/pages/docs/cli/powershell.html.md create mode 100644 website/pages/docs/cli/provision.html.md create mode 100644 website/pages/docs/cli/rdp.html.md create mode 100644 website/pages/docs/cli/reload.html.md create mode 100644 website/pages/docs/cli/resume.html.md create mode 100644 website/pages/docs/cli/rsync-auto.html.md create mode 100644 website/pages/docs/cli/rsync.html.md create mode 100644 website/pages/docs/cli/share.html.md create mode 100644 website/pages/docs/cli/snapshot.html.md create mode 100644 website/pages/docs/cli/ssh.html.md create mode 100644 website/pages/docs/cli/ssh_config.html.md create mode 100644 website/pages/docs/cli/status.html.md create mode 100644 website/pages/docs/cli/suspend.html.md create mode 100644 website/pages/docs/cli/up.html.md create mode 100644 website/pages/docs/cli/upload.html.md create mode 100644 website/pages/docs/cli/validate.html.md create mode 100644 website/pages/docs/cli/version.html.md create mode 100644 website/pages/docs/cli/winrm.html.md create mode 100644 website/pages/docs/cli/winrm_config.html.md create mode 100644 website/pages/docs/disks/configuration.html.md create mode 100644 website/pages/docs/disks/index.html.md create mode 100644 website/pages/docs/disks/usage.html.md create mode 100644 website/pages/docs/disks/virtualbox/common-issues.html.md create mode 100644 website/pages/docs/disks/virtualbox/index.html.md create mode 100644 website/pages/docs/disks/virtualbox/usage.html.md create mode 100644 website/pages/docs/docker/basics.html.md create mode 100644 website/pages/docs/docker/boxes.html.md create mode 100644 website/pages/docs/docker/commands.html.md create mode 100644 website/pages/docs/docker/configuration.html.md create mode 100644 website/pages/docs/docker/index.html.md create mode 100644 website/pages/docs/docker/networking.html.md create mode 100644 website/pages/docs/experimental/index.html.md create mode 100644 website/pages/docs/hyperv/boxes.html.md create mode 100644 website/pages/docs/hyperv/configuration.html.md create mode 100644 website/pages/docs/hyperv/index.html.md create mode 100644 website/pages/docs/hyperv/limitations.html.md create mode 100644 website/pages/docs/hyperv/usage.html.md create mode 100644 website/pages/docs/index.html.md create mode 100644 website/pages/docs/installation/backwards-compatibility.html.md create mode 100644 website/pages/docs/installation/index.html.md create mode 100644 website/pages/docs/installation/source.html.md create mode 100644 website/pages/docs/installation/uninstallation.html.md create mode 100644 website/pages/docs/installation/upgrading-from-1-0.html.md create mode 100644 website/pages/docs/installation/upgrading.html.md create mode 100644 website/pages/docs/multi-machine/index.html.md create mode 100644 website/pages/docs/networking/basic_usage.html.md create mode 100644 website/pages/docs/networking/forwarded_ports.html.md create mode 100644 website/pages/docs/networking/index.html.md create mode 100644 website/pages/docs/networking/private_network.html.md create mode 100644 website/pages/docs/networking/public_network.html.md create mode 100644 website/pages/docs/other/debugging.html.md create mode 100644 website/pages/docs/other/environmental-variables.html.md create mode 100644 website/pages/docs/other/index.html.md create mode 100644 website/pages/docs/other/macos-catalina.html.md create mode 100644 website/pages/docs/other/wsl.html.md create mode 100644 website/pages/docs/plugins/action-hooks.html.md create mode 100644 website/pages/docs/plugins/commands.html.md create mode 100644 website/pages/docs/plugins/configuration.html.md create mode 100644 website/pages/docs/plugins/development-basics.html.md create mode 100644 website/pages/docs/plugins/guest-capabilities.html.md create mode 100644 website/pages/docs/plugins/guests.html.md create mode 100644 website/pages/docs/plugins/host-capabilities.html.md create mode 100644 website/pages/docs/plugins/hosts.html.md create mode 100644 website/pages/docs/plugins/index.html.md create mode 100644 website/pages/docs/plugins/packaging.html.md create mode 100644 website/pages/docs/plugins/providers.html.md create mode 100644 website/pages/docs/plugins/provisioners.html.md create mode 100644 website/pages/docs/plugins/usage.html.md create mode 100644 website/pages/docs/providers/basic_usage.html.md create mode 100644 website/pages/docs/providers/configuration.html.md create mode 100644 website/pages/docs/providers/custom.html.md create mode 100644 website/pages/docs/providers/default.html.md create mode 100644 website/pages/docs/providers/index.html.md create mode 100644 website/pages/docs/providers/installation.html.md create mode 100644 website/pages/docs/provisioning/ansible.html.md create mode 100644 website/pages/docs/provisioning/ansible_common.html.md create mode 100644 website/pages/docs/provisioning/ansible_intro.html.md create mode 100644 website/pages/docs/provisioning/ansible_local.html.md create mode 100644 website/pages/docs/provisioning/basic_usage.html.md create mode 100644 website/pages/docs/provisioning/cfengine.html.md create mode 100644 website/pages/docs/provisioning/chef_apply.html.md create mode 100644 website/pages/docs/provisioning/chef_client.html.md create mode 100644 website/pages/docs/provisioning/chef_common.html.md create mode 100644 website/pages/docs/provisioning/chef_solo.html.md create mode 100644 website/pages/docs/provisioning/chef_zero.html.md create mode 100644 website/pages/docs/provisioning/docker.html.md create mode 100644 website/pages/docs/provisioning/file.html.md create mode 100644 website/pages/docs/provisioning/index.html.md create mode 100644 website/pages/docs/provisioning/podman.html.md create mode 100644 website/pages/docs/provisioning/puppet_agent.html.md create mode 100644 website/pages/docs/provisioning/puppet_apply.html.md create mode 100644 website/pages/docs/provisioning/salt.html.md create mode 100644 website/pages/docs/provisioning/shell.html.md create mode 100644 website/pages/docs/push/ftp.html.md create mode 100644 website/pages/docs/push/heroku.html.md create mode 100644 website/pages/docs/push/index.html.md create mode 100644 website/pages/docs/push/local-exec.html.md create mode 100644 website/pages/docs/share/connect.html.md create mode 100644 website/pages/docs/share/http.html.md create mode 100644 website/pages/docs/share/index.html.md create mode 100644 website/pages/docs/share/provider.html.md create mode 100644 website/pages/docs/share/security.html.md create mode 100644 website/pages/docs/share/ssh.html.md create mode 100644 website/pages/docs/synced-folders/basic_usage.html.md create mode 100644 website/pages/docs/synced-folders/index.html.md create mode 100644 website/pages/docs/synced-folders/nfs.html.md create mode 100644 website/pages/docs/synced-folders/rsync.html.md create mode 100644 website/pages/docs/synced-folders/smb.html.md create mode 100644 website/pages/docs/synced-folders/virtualbox.html.md create mode 100644 website/pages/docs/triggers/configuration.html.md create mode 100644 website/pages/docs/triggers/index.html.md create mode 100644 website/pages/docs/triggers/usage.html.md create mode 100644 website/pages/docs/vagrant-cloud/api.html.md.erb create mode 100644 website/pages/docs/vagrant-cloud/boxes/catalog.html.md create mode 100644 website/pages/docs/vagrant-cloud/boxes/create-version.html.md create mode 100644 website/pages/docs/vagrant-cloud/boxes/create.html.md create mode 100644 website/pages/docs/vagrant-cloud/boxes/distributing.html.md create mode 100644 website/pages/docs/vagrant-cloud/boxes/index.html.md create mode 100644 website/pages/docs/vagrant-cloud/boxes/lifecycle.html.md create mode 100644 website/pages/docs/vagrant-cloud/boxes/private.html.md create mode 100644 website/pages/docs/vagrant-cloud/boxes/release-workflow.html.md create mode 100644 website/pages/docs/vagrant-cloud/boxes/using.html.md create mode 100644 website/pages/docs/vagrant-cloud/index.html.md create mode 100755 website/pages/docs/vagrant-cloud/organizations/authentication-policy.html.md create mode 100755 website/pages/docs/vagrant-cloud/organizations/create.html.md create mode 100755 website/pages/docs/vagrant-cloud/organizations/index.html.md create mode 100755 website/pages/docs/vagrant-cloud/organizations/migrate.html.md create mode 100644 website/pages/docs/vagrant-cloud/request-limits.html.md create mode 100755 website/pages/docs/vagrant-cloud/support.html.md create mode 100755 website/pages/docs/vagrant-cloud/users/authentication.html.md create mode 100755 website/pages/docs/vagrant-cloud/users/index.html.md create mode 100755 website/pages/docs/vagrant-cloud/users/recovery.html.md create mode 100644 website/pages/docs/vagrantfile/index.html.md create mode 100644 website/pages/docs/vagrantfile/machine_settings.html.md create mode 100644 website/pages/docs/vagrantfile/ssh_settings.html.md create mode 100644 website/pages/docs/vagrantfile/tips.html.md create mode 100644 website/pages/docs/vagrantfile/vagrant_settings.html.md create mode 100644 website/pages/docs/vagrantfile/vagrant_version.html.md create mode 100644 website/pages/docs/vagrantfile/version.html.md create mode 100644 website/pages/docs/vagrantfile/winrm_settings.html.md create mode 100644 website/pages/docs/vagrantfile/winssh_settings.html.md create mode 100644 website/pages/docs/virtualbox/boxes.html.md create mode 100644 website/pages/docs/virtualbox/common-issues.html.md create mode 100644 website/pages/docs/virtualbox/configuration.html.md create mode 100644 website/pages/docs/virtualbox/index.html.md create mode 100644 website/pages/docs/virtualbox/networking.html.md create mode 100644 website/pages/docs/virtualbox/usage.html.md create mode 100644 website/pages/docs/vmware/boxes.html.md create mode 100644 website/pages/docs/vmware/configuration.html.md create mode 100644 website/pages/docs/vmware/index.html.md create mode 100644 website/pages/docs/vmware/installation.html.md create mode 100644 website/pages/docs/vmware/kernel-upgrade.html.md create mode 100644 website/pages/docs/vmware/known-issues.html.md create mode 100644 website/pages/docs/vmware/usage.html.md create mode 100644 website/pages/docs/vmware/vagrant-vmware-utility.html.md.erb create mode 100644 website/pages/intro/getting-started/boxes.html.md create mode 100644 website/pages/intro/getting-started/index.html.md create mode 100644 website/pages/intro/getting-started/install.html.md create mode 100644 website/pages/intro/getting-started/networking.html.md create mode 100644 website/pages/intro/getting-started/project_setup.html.md create mode 100644 website/pages/intro/getting-started/providers.html.md create mode 100644 website/pages/intro/getting-started/provisioning.html.md create mode 100644 website/pages/intro/getting-started/rebuild.html.md create mode 100644 website/pages/intro/getting-started/share.html.md create mode 100644 website/pages/intro/getting-started/synced_folders.html.md create mode 100644 website/pages/intro/getting-started/teardown.html.md create mode 100644 website/pages/intro/getting-started/up.html.md create mode 100644 website/pages/intro/index.html.md create mode 100644 website/pages/intro/vs/cli-tools.md create mode 100644 website/pages/intro/vs/docker.html.md create mode 100644 website/pages/intro/vs/index.html.md create mode 100644 website/pages/intro/vs/terraform.html.md create mode 100644 website/pages/vmware/downloads.html.erb create mode 100644 website/pages/vmware/eula.html.md create mode 100644 website/pages/vmware/index.html.erb create mode 100644 website/pages/vmware/privacy-policy.html.md create mode 100644 website/pages/vmware/reseller.html.md create mode 100644 website/pages/vmware/terms-of-service.html.md create mode 100644 website/public/img/customers.png create mode 100644 website/public/img/favicons/android-chrome-192x192.png create mode 100644 website/public/img/favicons/android-chrome-512x512.png create mode 100644 website/public/img/favicons/apple-touch-icon.png create mode 100644 website/public/img/favicons/favicon-16x16.png create mode 100644 website/public/img/favicons/favicon-32x32.png create mode 100644 website/public/img/favicons/favicon.ico create mode 100644 website/public/img/favicons/mstile-150x150.png create mode 100644 website/public/img/favicons/safari-pinned-tab.svg create mode 100644 website/public/img/logo-hashicorp.svg create mode 100644 website/public/img/logo-text.svg create mode 100644 website/public/img/og-image.png create mode 100644 website/public/img/parity.svg create mode 100644 website/public/img/systems/apple.svg create mode 100644 website/public/img/systems/linux.svg create mode 100644 website/public/img/systems/windows.svg create mode 100644 website/public/img/vmware.svg diff --git a/website/next.config.js b/website/next.config.js index 816aedf06..8c0b4ce07 100644 --- a/website/next.config.js +++ b/website/next.config.js @@ -8,7 +8,7 @@ module.exports = withHashicorp({ env: { HASHI_ENV: process.env.HASHI_ENV || 'development', SEGMENT_WRITE_KEY: 'wFMyBE4PJCZttWfu0pNhYdWr7ygW0io4', - BUGSNAG_CLIENT_KEY: 'c1d6da7a26dc367253f39fae8d83fdac', - BUGSNAG_SERVER_KEY: 'c1d6da7a26dc367253f39fae8d83fdac', + BUGSNAG_CLIENT_KEY: '87a42e709789c35676b06b0d29a9075d', + BUGSNAG_SERVER_KEY: '4acc6140aaebfab35f535a3666674a07', }, }) diff --git a/website/pages/docs/boxes.html.md b/website/pages/docs/boxes.html.md new file mode 100644 index 000000000..d745618a4 --- /dev/null +++ b/website/pages/docs/boxes.html.md @@ -0,0 +1,83 @@ +--- +layout: 'docs' +page_title: 'Boxes' +sidebar_current: 'boxes' +description: |- + Boxes are the package format for Vagrant environments. A box can be used by + anyone on any platform that Vagrant supports to bring up an identical + working environment. +--- + +# Boxes + +Boxes are the package format for Vagrant environments. A box can be used by +anyone on any platform that Vagrant supports to bring up an identical +working environment. + +The `vagrant box` utility provides all the functionality for managing +boxes. You can read the documentation on the [vagrant box](/docs/cli/box.html) +command for more information. + +The easiest way to use a box is to add a box from the +[publicly available catalog of Vagrant boxes](https://vagrantcloud.com/boxes/search). +You can also add and share your own customized boxes on this website. + +Boxes also support versioning so that members of your team using Vagrant +can update the underlying box easily, and the people who create boxes +can push fixes and communicate these fixes efficiently. + +You can learn all about boxes by reading this page as well as the +sub-pages in the navigation to the left. + +## Discovering Boxes + +The easiest way to find boxes is to look on the +[public Vagrant box catalog](https://vagrantcloud.com/boxes/search) +for a box matching your use case. The catalog contains most major operating +systems as bases, as well as specialized boxes to get you up and running +quickly with LAMP stacks, Ruby, Python, etc. + +The boxes on the public catalog work with many different +[providers](/docs/providers/). Whether you are using Vagrant with +VirtualBox, VMware, AWS, etc. you should be able to find a box you need. + +Adding a box from the catalog is very easy. Each box shows you instructions +with how to add it, but they all follow the same format: + +``` +$ vagrant box add USER/BOX +``` + +For example: `vagrant box add hashicorp/bionic64`. You can also quickly +initialize a Vagrant environment with `vagrant init hashicorp/bionic64`. + +~> **Namespaces do not guarantee canonical boxes!** A common misconception is +that a namespace like "ubuntu" represents the canonical space for Ubuntu boxes. +This is untrue. Namespaces on Vagrant Cloud behave very similarly to namespaces on +GitHub, for example. Just as GitHub's support team is unable to assist with +issues in someone's repository, HashiCorp's support team is unable to assist +with third-party published boxes. + +## Official Boxes + +HashiCorp (the makers of Vagrant) publish a basic Ubuntu 18.04 64-bit box that is available for minimal use cases. It is highly optimized, small in size, and includes support for Virtualbox, Hyper-V, and VMware. You can use it like this: + +```shell +$ vagrant init hashicorp/bionic64 +``` + +or you can update your `Vagrantfile` as follows: + +```ruby +Vagrant.configure("2") do |config| + config.vm.box = "hashicorp/bionic64" +end +``` + +For other users, we recommend the [Bento boxes](https://vagrantcloud.com/bento). The Bento boxes are [open source](https://github.com/chef/bento) and built for a number of providers including VMware, Virtualbox, and Parallels. There are a variety of operating systems and versions available. + +These are the only two officially-recommended box sets. + +Special thanks to the Bento project for providing a solid base template for the `hashicorp/bionic64` box. + +~> **It is often a point of confusion**, but Canonical (the company that makes the Ubuntu operating system) publishes boxes under the "ubuntu" namespace on Vagrant Cloud. These boxes only support Virtualbox and do not provide an ideal experience for most users. If you encounter issues with these boxes, please try the Bento boxes instead. diff --git a/website/pages/docs/boxes/base.html.md b/website/pages/docs/boxes/base.html.md new file mode 100644 index 000000000..77ec3a2c5 --- /dev/null +++ b/website/pages/docs/boxes/base.html.md @@ -0,0 +1,307 @@ +--- +layout: 'docs' +page_title: 'Creating a Base Box' +sidebar_current: 'boxes-base' +description: |- + There are a special category of boxes known as "base boxes." These boxes + contain the bare minimum required for Vagrant to function, are generally + not made by repackaging an existing Vagrant environment (hence the "base" + in the "base box"). +--- + +# Creating a Base Box + +There are a special category of boxes known as "base boxes." These boxes +contain the bare minimum required for Vagrant to function, are generally +not made by repackaging an existing Vagrant environment (hence the "base" +in the "base box"). + +For example, the Ubuntu boxes provided by the Vagrant project (such as +"bionic64") are base boxes. They were created from a minimal Ubuntu install +from an ISO, rather than repackaging an existing environment. + +Base boxes are extremely useful for having a clean slate starting point from +which to build future development environments. The Vagrant project hopes +in the future to be able to provide base boxes for many more operating systems. +Until then, this page documents how you can create your own base box. + +
+ Advanced topic! Creating a base box can be a time consuming + and tedious process, and is not recommended for new Vagrant users. If you are + just getting started with Vagrant, we recommend trying to find existing + base boxes to use first. +
+ +## What's in a Base Box? + +A base box typically consists of only a bare minimum set of software +for Vagrant to function. As an example, a Linux box may contain only the +following: + +- Package manager +- SSH +- SSH user so Vagrant can connect +- Perhaps Chef, Puppet, etc. but not strictly required. + +In addition to this, each [provider](/docs/providers/) may require +additional software. For example, if you are making a base box for VirtualBox, +you will want to include the VirtualBox guest additions so that shared folders +work properly. But if you are making an AWS base box, this is not required. + +## Creating a Base Box + +Creating a base box is actually provider-specific. This means that depending +on if you are using VirtualBox, VMware, AWS, etc. the process for creating +a base box is different. Because of this, this one document cannot be a +full guide to creating a base box. + +This page will document some general guidelines for creating base boxes, +however, and will link to provider-specific guides for creating base +boxes. + +Provider-specific guides for creating base boxes are linked below: + +- [Docker Base Boxes](/docs/docker/boxes.html) +- [Hyper-V Base Boxes](/docs/hyperv/boxes.html) +- [VMware Base Boxes](/docs/vmware/boxes.html) +- [VirtualBox Base Boxes](/docs/virtualbox/boxes.html) + +### Packer and Vagrant Cloud + +We strongly recommend using [Packer](https://www.packer.io) to create reproducible +builds for your base boxes, as well as automating the builds. Read more about +[automating Vagrant box creation with Packer](https://www.packer.io/guides/packer-on-cicd/build-image-in-cicd.html) +in the Packer documentation. + +### Disk Space + +When creating a base box, make sure the user will have enough disk space +to do interesting things, without being annoying. For example, in VirtualBox, +you should create a dynamically resizing drive with a large maximum size. +This causes the actual footprint of the drive to be small initially, but +to dynamically grow towards the max size as disk space is needed, providing +the most flexibility for the end user. + +If you are creating an AWS base box, do not force the AMI to allocate +terabytes of EBS storage, for example, since the user can do that on their +own. But you should default to mounting ephemeral drives, because they're +free and provide a lot of disk space. + +### Memory + +Like disk space, finding the right balance of the default amount of memory +is important. For most providers, the user can modify the memory with +the Vagrantfile, so do not use too much by default. It would be a poor +user experience (and mildly shocking) if a `vagrant up` from a base box +instantly required many gigabytes of RAM. Instead, choose a value such +as 512MB, which is usually enough to play around and do interesting things +with a Vagrant machine, but can easily be increased when needed. + +### Peripherals (Audio, USB, etc.) + +Disable any non-necessary hardware in a base box such as audio and USB +controllers. These are generally unnecessary for Vagrant usage and, again, +can be easily added via the Vagrantfile in most cases. + +## Default User Settings + +Just about every aspect of Vagrant can be modified. However, Vagrant does +expect some defaults which will cause your base box to "just work" out +of the box. You should create these as defaults if you intend to publicly +distribute your box. + +If you are creating a base box for private use, you should try _not_ to +follow these, as they open up your base box to security risks (known +users, passwords, private keys, etc.). + +### "vagrant" User + +By default, Vagrant expects a "vagrant" user to SSH into the machine as. +This user should be setup with the +[insecure keypair](https://github.com/hashicorp/vagrant/tree/master/keys) +that Vagrant uses as a default to attempt to SSH. Also, even though +Vagrant uses key-based authentication by default, it is a general convention +to set the password for the "vagrant" user to "vagrant". This lets people +login as that user manually if they need to. + +To configure SSH access with the insecure keypair, place the public +key into the `~/.ssh/authorized_keys` file for the "vagrant" user. Note +that OpenSSH is very picky about file permissions. Therefore, make sure +that `~/.ssh` has `0700` permissions and the authorized keys file has +`0600` permissions. + +When Vagrant boots a box and detects the insecure keypair, it will +automatically replace it with a randomly generated keypair for additional +security while the box is running. + +### Root Password: "vagrant" + +Vagrant does not actually use or expect any root password. However, having +a generally well known root password makes it easier for the general public +to modify the machine if needed. + +Publicly available base boxes usually use a root password of "vagrant" to +keep things easy. + +### Password-less Sudo + +This is **important!**. Many aspects of Vagrant expect the default SSH user +to have passwordless sudo configured. This lets Vagrant configure networks, +mount synced folders, install software, and more. + +To begin, some minimal installations of operating systems do not even include +`sudo` by default. Verify that you install `sudo` in some way. + +After installing sudo, configure it (usually using `visudo`) to allow +passwordless sudo for the "vagrant" user. This can be done with the +following line at the end of the configuration file: + +``` +vagrant ALL=(ALL) NOPASSWD: ALL +``` + +Additionally, Vagrant does not use a pty or tty by default when connected +via SSH. You will need to make sure there is no line that has `requiretty` in +it. Remove that if it exists. This allows sudo to work properly without a +tty. Note that you _can_ configure Vagrant to request a pty, which lets +you keep this configuration. But Vagrant by default does not do this. + +### SSH Tweaks + +In order to keep SSH speedy even when your machine or the Vagrant machine +is not connected to the internet, set the `UseDNS` configuration to `no` +in the SSH server configuration. + +This avoids a reverse DNS lookup on the connecting SSH client which +can take many seconds. + +## Windows Boxes + +Supported Windows guest operating systems: + +- Windows 7 +- Windows 8 +- Windows Server 2008 +- Windows Server 2008 R2 +- Windows Server 2012 +- Windows Server 2012 R2 + +Windows Server 2003 and Windows XP are _not_ supported, but if you are a die +hard XP fan [this](https://stackoverflow.com/a/18593425/18475) may help you. + +### Base Windows Configuration + +- Turn off UAC +- Disable complex passwords +- Disable "Shutdown Tracker" +- Disable "Server Manager" starting at login (for non-Core) + +In addition to disabling UAC in the control panel, you also must disable +UAC in the registry. This may vary from Windows version to Windows version, +but Windows 8/8.1 use the command below. This will allow some things like +automated Puppet installs to work within Vagrant Windows base boxes. + +``` +reg add HKEY_LOCAL_MACHINE\Software\Microsoft\Windows\CurrentVersion\Policies\System /v EnableLUA /d 0 /t REG_DWORD /f /reg:64 +``` + +### Base WinRM Configuration + +To enable and configure WinRM you will need to set the WinRM service to +auto-start and allow unencrypted basic auth (obviously this is not secure). +Run the following commands from a regular Windows command prompt: + +``` +winrm quickconfig -q +winrm set winrm/config/winrs @{MaxMemoryPerShellMB="512"} +winrm set winrm/config @{MaxTimeoutms="1800000"} +winrm set winrm/config/service @{AllowUnencrypted="true"} +winrm set winrm/config/service/auth @{Basic="true"} +sc config WinRM start= auto +``` + +### Additional WinRM 1.1 Configuration + +These additional configuration steps are specific to Windows Server 2008 +(WinRM 1.1). For Windows Server 2008 R2, Windows 7 and later versions of +Windows you can ignore this section. + +1. Ensure the Windows PowerShell feature is installed +2. Change the WinRM port to 5985 or upgrade to WinRM 2.0 + +The following commands will change the WinRM 1.1 port to what's expected by +Vagrant: + +``` +netsh firewall add portopening TCP 5985 "Port 5985" +winrm set winrm/config/listener?Address=*+Transport=HTTP @{Port="5985"} +``` + +### Optional WinSSH Configuration + +When using the WinSSH communicator, you may run into an issue where a PowerShell +command can't display a progress bar. A typical error message might look like: + +``` +Win32 internal error "Access is denied" 0x5 occurred while reading the console output buffer. +``` + +In order to prevent this, we recommend setting `$ProgressPreference = "SilentlyContinue"` +in your box's PowerShell profile: + +``` +if (!(Test-Path -Path $PROFILE)) { + New-Item -ItemType File -Path $PROFILE -Force +} + +Add-Content $PROFILE '$ProgressPreference = "SilentlyContinue"' +``` + +## Other Software + +At this point, you have all the common software you absolutely _need_ for +your base box to work with Vagrant. However, there is some additional software +you can install if you wish. + +While we plan on it in the future, Vagrant still does not install Chef +or Puppet automatically when using those provisioners. Users can use a shell +provisioner to do this, but if you want Chef/Puppet to just work out of the +box, you will have to install them in the base box. + +Installing this is outside the scope of this page, but should be fairly +straightforward. + +In addition to this, feel free to install and configure any other software +you want available by default for this base box. + +## Packaging the Box + +Packaging the box into a `box` file is provider-specific. Please refer to +the provider-specific documentation for creating a base box. Some +provider-specific guides are linked to towards the top of this page. + +## Distributing the Box + +You can distribute the box file however you would like. However, if you want +to support versioning, putting multiple providers at a single URL, pushing +updates, analytics, and more, we recommend you add the box to +[HashiCorp's Vagrant Cloud](/docs/vagrant-cloud). + +You can upload both public and private boxes to this service. + +## Testing the Box + +To test the box, pretend you are a new user of Vagrant and give it a shot: + +``` +$ vagrant box add --name my-box /path/to/the/new.box +... +$ vagrant init my-box +... +$ vagrant up +... +``` + +If you made a box for some other provider, be sure to specify the +`--provider` option to `vagrant up`. If the up succeeded, then your +box worked! diff --git a/website/pages/docs/boxes/format.html.md b/website/pages/docs/boxes/format.html.md new file mode 100644 index 000000000..2329de297 --- /dev/null +++ b/website/pages/docs/boxes/format.html.md @@ -0,0 +1,123 @@ +--- +layout: 'docs' +page_title: 'Box File Format' +sidebar_current: 'boxes-format' +description: |- + The box file format for Vagrant has changed from only supporting VirtualBox to + supporting a number different providers and box formats. +--- + +# Box File Format + +In the past, boxes were just [tar files]() +of VirtualBox exports. With Vagrant supporting multiple +[providers](/docs/providers/) and [versioning](/docs/boxes/versioning.html) +now, box files are slightly more complicated. + +Box files made for Vagrant 1.0.x (the VirtualBox export `tar` files) continue +to work with Vagrant today. When Vagrant encounters one of these old boxes, +it automatically updates it internally to the new format. + +Today, there are three different components: + +- Box File - This is a compressed (`tar`, `tar.gz`, `zip`) file that is specific + to a single provider and can contain anything. Vagrant core does not ever + use the contents of this file. Instead, they are passed to the provider. + Therefore, a VirtualBox box file has different contents from a VMware + box file and so on. + +- Box Catalog Metadata - This is a JSON document (typically exchanged + during interactions with [HashiCorp's Vagrant Cloud](/docs/vagrant-cloud)) + that specifies the name of the box, a description, available + versions, available providers, and URLs to the actual box files + (next component) for each provider and version. If this catalog + metadata does not exist, a box file can still be added directly, but + it will not support versioning and updating. + +- Box Information - This is a JSON document that can provide additional + information about the box that displays when a user runs + `vagrant box list -i`. More information is provided [here](/docs/boxes/info.html). + +The first two components are covered in more detail below. + +## Box File + +The actual box file is the required portion for Vagrant. It is recommended +you always use a metadata file alongside a box file, but direct box files +are supported for legacy reasons in Vagrant. + +Box files are compressed using `tar`, `tar.gz`, or `zip`. The contents of the +archive can be anything, and is specific to each +[provider](/docs/providers/). Vagrant core itself only unpacks +the boxes for use later. + +Within the archive, Vagrant does expect a single file: +`metadata.json`. This is a JSON file that is completely unrelated to +the above box catalog metadata component; there is only one +`metadata.json` per box file (inside the box file), whereas one +catalog metadata JSON document can describe multiple versions of the +same box, potentially spanning multiple providers. + +`metadata.json` must contain at least the "provider" key with the +provider the box is for. Vagrant uses this to verify the provider of +the box. For example, if your box was for VirtualBox, the +`metadata.json` would look like this: + +```json +{ + "provider": "virtualbox" +} +``` + +If there is no `metadata.json` file or the file does not contain valid JSON +with at least a "provider" key, then Vagrant will error when adding the box, +because it cannot verify the provider. + +Other keys/values may be added to the metadata without issue. The value +of the metadata file is passed opaquely into Vagrant and plugins can make +use of it. At this point, Vagrant core does not use any other keys in this +file. + +## Box Metadata + +The metadata is an optional component for a box (but highly recommended) +that enables [versioning](/docs/boxes/versioning.html), updating, multiple +providers from a single file, and more. + +
+ You do not need to manually make the metadata. If you + have an account with HashiCorp's Vagrant Cloud, you + can create boxes there, and HashiCorp's Vagrant Cloud automatically creates + the metadata for you. The format is still documented here. +
+ +It is a JSON document, structured in the following way: + +```json +{ + "name": "hashicorp/bionic64", + "description": "This box contains Ubuntu 18.04 LTS 64-bit.", + "versions": [ + { + "version": "0.1.0", + "providers": [ + { + "name": "virtualbox", + "url": "http://somewhere.com/bionic64_010_virtualbox.box", + "checksum_type": "sha1", + "checksum": "foo" + } + ] + } + ] +} +``` + +As you can see, the JSON document can describe multiple versions of a box, +multiple providers, and can add/remove providers in different versions. + +This JSON file can be passed directly to `vagrant box add` from the +local filesystem using a file path or via a URL, and Vagrant will +install the proper version of the box. In this case, the value for the +`url` key in the JSON can also be a file path. If multiple providers +are available, Vagrant will ask what provider you want to use. diff --git a/website/pages/docs/boxes/info.html.md b/website/pages/docs/boxes/info.html.md new file mode 100644 index 000000000..cbb3a3511 --- /dev/null +++ b/website/pages/docs/boxes/info.html.md @@ -0,0 +1,42 @@ +--- +layout: 'docs' +page_title: 'Box Info Format' +sidebar_current: 'boxes-info' +description: |- + A box can provide additional information to the user by supplying an info.json + file within the box. +--- + +# Additional Box Information + +When creating a Vagrant box, you can supply additional information that might be +relevant to the user when running `vagrant box list -i`. For example, you could +package your box to include information about the author of the box and a +website for users to learn more: + +``` +brian@localghost % vagrant box list -i +hashicorp/bionic64 (virtualbox, 1.0.0) + - author: brian + - homepage: https://www.vagrantup.com +``` + +## Box Info + +To accomplish this, you simply need to include a file named `info.json` when +creating a [base box](/docs/boxes/base.html) which is a JSON document containing +any and all relevant information that will be displayed to the user when the +`-i` option is used with `vagrant box list`. + +```json +{ + "author": "brian", + "homepage": "https://example.com" +} +``` + +There are no special keys or values in `info.json`, and Vagrant will print each +key and value on its own line. + +The [Box File Format](/docs/boxes/format.html) provides more information about what +else goes into a Vagrant box. diff --git a/website/pages/docs/boxes/versioning.html.md b/website/pages/docs/boxes/versioning.html.md new file mode 100644 index 000000000..f8ba5eca6 --- /dev/null +++ b/website/pages/docs/boxes/versioning.html.md @@ -0,0 +1,107 @@ +--- +layout: 'docs' +page_title: 'Box Versioning' +sidebar_current: 'boxes-versioning' +description: |- + Since Vagrant 1.5, boxes support versioning. This allows the people who + make boxes to push updates to the box, and the people who use the box + have a simple workflow for checking for updates, updating their boxes, + and seeing what has changed. +--- + +# Box Versioning + +Since Vagrant 1.5, boxes support versioning. This allows the people who +make boxes to push updates to the box, and the people who use the box +have a simple workflow for checking for updates, updating their boxes, +and seeing what has changed. + +If you are just getting started with Vagrant, box versioning is not too +important, and we recommend learning about some other topics first. But +if you are using Vagrant on a team or plan on creating your own boxes, +versioning is very important. Luckily, having versioning built right in +to Vagrant makes it easy to use and fit nicely into the Vagrant workflow. + +This page will cover how to use versioned boxes. It does _not_ cover how +to update your own custom boxes with versions. That is covered in +[creating a base box](/docs/boxes/base.html). + +## Viewing Versions and Updating + +`vagrant box list` only shows _installed_ versions of boxes. If you want +to see all available versions of a box, you will have to find the box +on [HashiCorp's Vagrant Cloud](/docs/vagrant-cloud). An easy way to find a box +is to use the url `https://vagrantcloud.com/$USER/$BOX`. For example, for +the `hashicorp/bionic64` box, you can find information about it at +`https://vagrantcloud.com/hashicorp/bionic64`. + +You can check if the box you are using is outdated with `vagrant box outdated`. +This can check if the box in your current Vagrant environment is outdated +as well as any other box installed on the system. + +Finally, you can update boxes with `vagrant box update`. This will download +and install the new box. This _will not_ magically update running Vagrant +environments. If a Vagrant environment is already running, you will have to +destroy and recreate it to acquire the new updates in the box. The update +command just downloads these updates locally. + +## Version Constraints + +You can constrain a Vagrant environment to a specific version or versions +of a box using the [Vagrantfile](/docs/vagrantfile/) by specifying +the `config.vm.box_version` option. + +If this option is not specified, the latest version is always used. This is +equivalent to specifying a constraint of ">= 0". + +The box version configuration can be a specific version or a constraint of +versions. Constraints can be any combination of the following: +`= X`, `> X`, `< X`, `>= X`, `<= X`, `~> X`. You can combine multiple +constraints by separating them with commas. All the constraints should be +self explanatory except perhaps for `~>`, known as the "pessimistic constraint". +Examples explain it best: `~> 1.0` is equivalent to `>= 1.0, < 2.0`. And +`~> 1.1.5` is equivalent to `>= 1.1.5, < 1.2.0`. + +You can choose to handle versions however you see fit. However, many boxes +in the public catalog follow [semantic versioning](http://semver.org/). +Basically, only the first number (the "major version") breaks backwards +compatibility. In terms of Vagrant boxes, this means that any software that +runs in version "1.1.5" of a box should work in "1.2" and "1.4.5" and so on, +but "2.0" might introduce big changes that break your software. By following +this convention, the best constraint is `~> 1.0` because you know it is safe +no matter what version is in that range. + +Please note that, while the semantic versioning specification allows for +more than three points and pre-release or beta versions, Vagrant boxes must be +of the format `X.Y.Z` where `X`, `Y`, and `Z` are all positive integers. + +## Automatic Update Checking + +Using the [Vagrantfile](/docs/vagrantfile/), you can also configure +Vagrant to automatically check for updates during any `vagrant up`. This is +enabled by default, but can easily be disabled with +`config.vm.box_check_update = false` in your Vagrantfile. + +When this is enabled, Vagrant will check for updates on every `vagrant up`, +not just when the machine is being created from scratch, but also when it +is resuming, starting after being halted, etc. + +If an update is found, Vagrant will output a warning to the user letting +them know an update is available. That user can choose to ignore the warning +for now, or can update the box by running `vagrant box update`. + +Vagrant can not and does not automatically download the updated box and +update the machine because boxes can be relatively large and updating the +machine requires destroying it and recreating it, which can cause important +data to be lost. Therefore, this process is manual to the extent that the +user has to manually enter a command to do it. + +## Pruning Old Versions + +Vagrant does not automatically prune old versions because it does not know +if they might be in use by other Vagrant environments. Because boxes can +be large, you may want to actively prune them once in a while using +`vagrant box remove`. You can see all the boxes that are installed +using `vagrant box list`. + +Another option is to use `vagrant box prune` command to remove all installed boxes that are outdated and not currently in use. diff --git a/website/pages/docs/cli/aliases.html.md b/website/pages/docs/cli/aliases.html.md new file mode 100644 index 000000000..cd83c0f19 --- /dev/null +++ b/website/pages/docs/cli/aliases.html.md @@ -0,0 +1,74 @@ +--- +layout: 'docs' +page_title: 'Aliases - Command-Line Interface' +sidebar_current: 'cli-aliases' +description: |- + Custom Vagrant commands can be defined using aliases, allowing for a simpler, + easier, and more familiar command line interface. +--- + +# Aliases + +Inspired in part by Git's own +[alias functionality](https://git-scm.com/book/en/v2/Git-Basics-Git-Aliases), +aliases make your Vagrant experience simpler, easier, and more familiar by +allowing you to create your own custom Vagrant commands. + +Aliases can be defined within `VAGRANT_HOME/aliases` file, or in a custom file +defined using the `VAGRANT_ALIAS_FILE` environment variable, in the following +format: + +``` +# basic command-level aliases +start = up +stop = halt + +# advanced command-line aliases +eradicate = !vagrant destroy && rm -rf .vagrant +``` + +In a nutshell, aliases are defined using a standard `key = value` format, where +the `key` is the new Vagrant command, and the `value` is the aliased command. +Using this format, there are two types of aliases that can be defined: internal +and external aliases. + +## Internal Aliases + +Internal command aliases call the CLI class directly, allowing you to alias +one Vagrant command to another Vagrant command. This technique can be very +useful for creating commands that you think _should_ exist. For example, +if `vagrant stop` feels more intuitive than `vagrant halt`, the following alias +definitions would make that change possible: + +``` +stop = halt +``` + +This makes the following commands equivalent: + +``` +vagrant stop +vagrant halt +``` + +## External Aliases + +While internal aliases can be used to define more intuitive Vagrant commands, +external command aliases are used to define Vagrant commands with brand new +functionality. These aliases are prefixed with the `!` character, which +indicates to the interpreter that the alias should be executed as a shell +command. For example, let's say that you want to be able to view the processor +and memory utilization of the active project's virtual machine. To do this, you +could define a `vagrant metrics` command that returns the required information +in an easy-to-read format, like so: + +``` +metrics = !ps aux | grep "[V]BoxHeadless" | grep $(cat .vagrant/machines/default/virtualbox/id) | awk '{ printf("CPU: %.02f%%, Memory: %.02f%%", $3, $4) }' +``` + +The above alias, from within the context of an active Vagrant project, would +print the CPU and memory utilization directly to the console: + +``` +CPU: 4.20%, Memory: 11.00% +``` diff --git a/website/pages/docs/cli/box.html.md b/website/pages/docs/cli/box.html.md new file mode 100644 index 000000000..0ca646beb --- /dev/null +++ b/website/pages/docs/cli/box.html.md @@ -0,0 +1,216 @@ +--- +layout: 'docs' +page_title: 'vagrant box - Command-Line Interface' +sidebar_current: 'cli-box' +description: |- + The "vagrant box" command is used to manage "vagrant box add", "vagrant box + remove", and other box-related commands such as "outdated", "list", and + "update". +--- + +# Box + +**Command: `vagrant box`** + +This is the command used to manage (add, remove, etc.) [boxes](/docs/boxes.html). + +The main functionality of this command is exposed via even more subcommands: + +- [`add`](#box-add) +- [`list`](#box-list) +- [`outdated`](#box-outdated) +- [`prune`](#box-prune) +- [`remove`](#box-remove) +- [`repackage`](#box-repackage) +- [`update`](#box-update) + +# Box Add + +**Command: `vagrant box add ADDRESS`** + +This adds a box with the given address to Vagrant. The address can be +one of three things: + +- A shorthand name from the + [public catalog of available Vagrant images](https://vagrantcloud.com/boxes/search), + such as "hashicorp/bionic64". + +- File path or HTTP URL to a box in a [catalog](https://vagrantcloud.com/boxes/search). + For HTTP, basic authentication is supported and `http_proxy` environmental + variables are respected. HTTPS is also supported. + +- URL directly a box file. In this case, you must specify a `--name` flag + (see below) and versioning/updates will not work. + +If an error occurs during the download or the download is interrupted with +a Ctrl-C, then Vagrant will attempt to resume the download the next time it +is requested. Vagrant will only attempt to resume a download for 24 hours +after the initial download. + +## Options + +- `--box-version VALUE` - The version of the box you want to add. By default, + the latest version will be added. The value of this can be an exact version + number such as "1.2.3" or it can be a set of version constraints. A version + constraint looks like ">= 1.0, < 2.0". + +- `--cacert CERTFILE` - The certificate for the CA used to verify the peer. + This should be used if the remote end does not use a standard root CA. + +- `--capath CERTDIR` - The certificate directory for the CA used to verify the peer. + This should be used if the remote end does not use a standard root CA. + +- `--cert CERTFILE` - A client certificate to use when downloading the box, if + necessary. + +- `--clean` - If given, Vagrant will remove any old temporary files from + prior downloads of the same URL. This is useful if you do not want Vagrant + to resume a download from a previous point, perhaps because the contents + changed. + +- `--force` - When present, the box will be downloaded and overwrite any + existing box with this name. + +- `--insecure` - When present, SSL certificates will not be verified if the + URL is an HTTPS URL. + +- `--provider PROVIDER` - If given, Vagrant will verify the box you are + adding is for the given provider. By default, Vagrant automatically + detects the proper provider to use. + +## Options for direct box files + +The options below only apply if you are adding a box file directly (when +you are not using a catalog). + +- `--checksum VALUE` - A checksum for the box that is downloaded. If specified, + Vagrant will compare this checksum to what is actually downloaded and will + error if the checksums do not match. This is highly recommended since + box files are so large. If this is specified, `--checksum-type` must + also be specified. If you are downloading from a catalog, the checksum is + included within the catalog entry. + +- `--checksum-type TYPE` - The type of checksum that `--checksum` is if it + is specified. Supported values are currently "md5", "sha1", "sha256", + "sha384", and "sha512". + +- `--name VALUE` - Logical name for the box. This is the value that you + would put into `config.vm.box` in your Vagrantfile. When adding a box from + a catalog, the name is included in the catalog entry and does not have + to be specified. + +
+ Checksums for versioned boxes or boxes from HashiCorp's Vagrant Cloud: + For boxes from HashiCorp's Vagrant Cloud, the checksums are embedded in the metadata + of the box. The metadata itself is served over TLS and its format is validated. +
+ +# Box List + +**Command: `vagrant box list`** + +This command lists all the boxes that are installed into Vagrant. + +# Box Outdated + +**Command: `vagrant box outdated`** + +This command tells you whether or not the box you are using in +your current Vagrant environment is outdated. If the `--global` flag +is present, every installed box will be checked for updates. + +This will show the latest version available for the specific provider type, +which may be different than the absolute latest version available. + +Checking for updates involves refreshing the metadata associated with +a box. This generally requires an internet connection. + +By default, if Vagrant has recently checked for a box that's out of date, it will +cache that answer and not look up another update for one hour. This cached value +can be ignored if the `--force` flag is used. + +## Options + +- `--force` - Check for updates for all installed boxes and ignore cache interval. +- `--global` - Check for updates for all installed boxes, not just the + boxes for the current Vagrant environment. + +# Box Prune + +**Command: `vagrant box prune`** + +This command removes old versions of installed boxes. If the box is currently in use vagrant will ask for confirmation. + +## Options + +- `--provider PROVIDER` - The specific provider type for the boxes to destroy. + +- `--dry-run` - Only print the boxes that would be removed. + +- `--name NAME` - The specific box name to check for outdated versions. + +- `--force` - Destroy without confirmation even when box is in use. + +- `--keep-active-boxes` - When combined with `--force`, will keep boxes still actively in use. + +# Box Remove + +**Command: `vagrant box remove NAME`** + +This command removes a box from Vagrant that matches the given name. + +If a box has multiple providers, the exact provider must be specified +with the `--provider` flag. If a box has multiple versions, you can select +what versions to delete with the `--box-version` flag or remove all versions +with the `--all` flag. + +## Options + +- `--box-version VALUE` - Version of version constraints of the boxes to + remove. See documentation on this flag for `box add` for more details. + +- `--all` - Remove all available versions of a box. + +- `--force` - Forces removing the box even if an active Vagrant + environment is using it. + +- `--provider VALUE` - The provider-specific box to remove with the given + name. This is only required if a box is backed by multiple providers. + If there is only a single provider, Vagrant will default to removing it. + +# Box Repackage + +**Command: `vagrant box repackage NAME PROVIDER VERSION`** + +This command repackages the given box and puts it in the current +directory so you can redistribute it. The name, provider, and version +of the box can be retrieved using `vagrant box list`. + +When you add a box, Vagrant unpacks it and stores it internally. The +original `*.box` file is not preserved. This command is useful for +reclaiming a `*.box` file from an installed Vagrant box. + +# Box Update + +**Command: `vagrant box update`** + +This command updates the box for the current Vagrant environment if there +are updates available. The command can also update a specific box (outside +of an active Vagrant environment), by specifying the `--box` flag. + +Note that updating the box will not update an already-running Vagrant +machine. To reflect the changes in the box, you will have to destroy and +bring back up the Vagrant machine. + +If you just want to check if there are updates available, use the +`vagrant box outdated` command. + +## Options + +- `--box VALUE` - Name of a specific box to update. If this flag is not + specified, Vagrant will update the boxes for the active Vagrant + environment. + +- `--provider VALUE` - When `--box` is present, this controls what + provider-specific box to update. This is not required unless the box has + multiple providers. Without the `--box` flag, this has no effect. diff --git a/website/pages/docs/cli/cloud.html.md b/website/pages/docs/cli/cloud.html.md new file mode 100644 index 000000000..7c7fa5d3d --- /dev/null +++ b/website/pages/docs/cli/cloud.html.md @@ -0,0 +1,338 @@ +--- +layout: 'docs' +page_title: 'vagrant cloud - Command-Line Interface' +sidebar_current: 'cli-cloud' +description: |- + The "vagrant cloud" command can be used for taking actions against + Vagrant Cloud like searching or uploading a Vagrant Box +--- + +# Cloud + +**Command: `vagrant cloud`** + +This is the command used to manage anything related to [Vagrant Cloud](https://vagrantcloud.com). + +The main functionality of this command is exposed via subcommands: + +- [`auth`](#cloud-auth) +- [`box`](#cloud-box) +- [`provider`](#cloud-provider) +- [`publish`](#cloud-publish) +- [`search`](#cloud-search) +- [`version`](#cloud-version) + +# Cloud Auth + +**Command: `vagrant cloud auth`** + +The `cloud auth` command is for handling all things related to authorization with +Vagrant Cloud. + +- [`login`](#cloud-auth-login) +- [`logout`](#cloud-auth-logout) +- [`whoami`](#cloud-auth-whoami) + +## Cloud Auth Login + +**Command: `vagrant cloud auth login`** + +The login command is used to authenticate with [HashiCorp's Vagrant Cloud](/docs/vagrant-cloud) +server. Logging in is only necessary if you are accessing protected boxes. + +**Logging in is not a requirement to use Vagrant.** The vast majority +of Vagrant does _not_ require a login. Only certain features such as protected +boxes. + +The reference of available command-line flags to this command +is available below. + +### Options + +- `--check` - This will check if you are logged in. In addition to outputting + whether you are logged in or not, the command exit status will be 0 if you are + logged in, or 1 if you are not. + +- `--logout` - This will log you out if you are logged in. If you are already + logged out, this command will do nothing. It is not an error to call this + command if you are already logged out. + +- `--token` - This will set the Vagrant Cloud login token manually to the provided + string. It is assumed this token is a valid Vagrant Cloud access token. + +### Examples + +Securely authenticate to Vagrant Cloud using a username and password: + +```text +$ vagrant cloud auth login +# ... +Vagrant Cloud username: +Vagrant Cloud password: +``` + +Check if the current user is authenticated: + +```text +$ vagrant cloud auth login --check +You are already logged in. +``` + +Securely authenticate with Vagrant Cloud using a token: + +```text +$ vagrant cloud auth login --token ABCD1234 +The token was successfully saved. +``` + +## Cloud Auth Logout + +**Command: `vagrant cloud auth logout`** + +This will log you out if you are logged in. If you are already +logged out, this command will do nothing. It is not an error to call this +command if you are already logged out. + +## Cloud Auth Whomi + +**Command: `vagrant cloud auth whoami [TOKEN]`** + +This command will validate your Vagrant Cloud token and will print the user who +it belongs to. If a token is passed in, it will attempt to validate it instead +of the token stored stored on disk. + +# Cloud Box + +**Command: `vagrant cloud box`** + +The `cloud box` command is used to manage life cycle operations for all `box` +entities on Vagrant Cloud. + +- [`create`](#cloud-box-create) +- [`delete`](#cloud-box-delete) +- [`show`](#cloud-box-show) +- [`update`](#cloud-box-update) + +## Cloud Box Create + +**Command: `vagrant cloud box create ORGANIZATION/BOX-NAME`** + +The box create command is used to create a new box entry on Vagrant Cloud. + +### Options + +- `--description DESCRIPTION` - A full description of the box. Can be + formatted with Markdown. +- `--short-description DESCRIPTION` - A short summary of the box. +- `--private` - Will make the new box private (Public by default) + +## Cloud Box Delete + +**Command: `vagrant cloud box delete ORGANIZATION/BOX-NAME`** + +The box delete command will _permanently_ delete the given box entry on Vagrant Cloud. Before +making the request, it will ask if you are sure you want to delete the box. + +## Cloud Box Show + +**Command: `vagrant cloud box show ORGANIZATION/BOX-NAME`** + +The box show command will display information about the latest version for the given Vagrant box. + +## Cloud Box Update + +**Command: `vagrant cloud box update ORGANIZATION/BOX-NAME`** + +The box update command will update an already created box on Vagrant Cloud with the given options. + +### Options + +- `--description DESCRIPTION` - A full description of the box. Can be + formatted with Markdown. +- `--short-description DESCRIPTION` - A short summary of the box. +- `--private` - Will make the new box private (Public by default) + +# Cloud Provider + +**Command: `vagrant cloud provider`** + +The `cloud provider` command is used to manage the life cycle operations for all +`provider` entities on Vagrant Cloud. + +- [`create`](#cloud-provider-create) +- [`delete`](#cloud-provider-delete) +- [`update`](#cloud-provider-update) +- [`upload`](#cloud-provider-upload) + +## Cloud Provider Create + +**Command: `vagrant cloud provider create ORGANIZATION/BOX-NAME PROVIDER-NAME VERSION [URL]`** + +The provider create command is used to create a new provider entry on Vagrant Cloud. +The `url` argument is expected to be a remote URL that Vagrant Cloud can use +to download the provider. If no `url` is specified, the provider entry can be updated +later with a url or the [upload](#cloud-provider-upload) command can be used to +upload a Vagrant [box file](/docs/boxes.html). + +## Cloud Provider Delete + +**Command: `vagrant cloud provider delete ORGANIZATION/BOX-NAME PROVIDER-NAME VERSION`** + +The provider delete command is used to delete a provider entry on Vagrant Cloud. +Before making the request, it will ask if you are sure you want to delete the provider. + +## Cloud Provider Update + +**Command: `vagrant cloud provider update ORGANIZATION/BOX-NAME PROVIDER-NAME VERSION [URL]`** + +The provider update command will update an already created provider for a box on +Vagrant Cloud with the given options. + +## Cloud Provider Upload + +**Command: `vagrant cloud provider upload ORGANIZATION/BOX-NAME PROVIDER-NAME VERSION BOX-FILE`** + +The provider upload command will upload a Vagrant [box file](/docs/boxes.html) to Vagrant Cloud for +the specified version and provider. + +# Cloud Publish + +**Command: `vagrant cloud publish ORGANIZATION/BOX-NAME VERSION PROVIDER-NAME [PROVIDER-FILE]`** + +The publish command is a complete solution for creating and updating a +Vagrant box on Vagrant Cloud. Instead of having to create each attribute of a Vagrant +box with separate commands, the publish command instead asks you to provide all +the information required before creating or updating a new box. + +## Options + +- `--box-version VERSION` - Version to create for the box +- `--description DESCRIPTION` - A full description of the box. Can be + formatted with Markdown. +- `--force` - Disables confirmation when creating or updating a box. +- `--short-description DESCRIPTION` - A short summary of the box. +- `--private` - Will make the new box private (Public by default) +- `--release` - Automatically releases the box after creation (Unreleased by default) +- `--url` - Valid remote URL to download the box file +- `--version-description DESCRIPTION` - Description of the version that will be created. + +## Examples + +Creating a new box on Vagrant Cloud: + +```text +$ vagrant cloud publish briancain/supertest 1.0.0 virtualbox boxes/my/virtualbox.box -d "A really cool box to download and use" --version-description "A cool version" --release --short-description "Download me!" +You are about to create a box on Vagrant Cloud with the following options: +briancain/supertest (1.0.0) for virtualbox +Automatic Release: true +Box Description: A really cool box to download and use +Box Short Description: Download me! +Version Description: A cool version +Do you wish to continue? [y/N] y +Creating a box entry... +Creating a version entry... +Creating a provider entry... +Uploading provider with file /Users/vagrant/boxes/my/virtualbox.box +Releasing box... +Complete! Published briancain/supertest +tag: briancain/supertest +username: briancain +name: supertest +private: false +downloads: 0 +created_at: 2018-07-25T17:53:04.340Z +updated_at: 2018-07-25T18:01:10.665Z +short_description: Download me! +description_markdown: A really cool box to download and use +current_version: 1.0.0 +providers: virtualbox +``` + +# Cloud Search + +**Command: `vagrant cloud search QUERY`** + +The cloud search command will take a query and search Vagrant Cloud for any matching +Vagrant boxes. Various filters can be applied to the results. + +## Options + +- `--json` - Format search results in JSON. +- `--page PAGE` - The page to display. Defaults to the first page of results. +- `--short` - Shows a simple list of box names for the results. +- `--order ORDER` - Order to display results. Can either be `desc` or `asc`. + Defaults to `desc`. +- `--limit LIMIT` - Max number of search results to display. Defaults to 25. +- `--provider PROVIDER` - Filter search results to a single provider. +- `--sort-by SORT` - The field to sort results on. Can be `created`, `downloads` + , or `updated`. Defaults to `downloads`. + +## Examples + +If you are looking for a HashiCorp box: + +```text +vagrant cloud search hashicorp --limit 5 +| NAME | VERSION | DOWNLOADS | PROVIDERS | ++-------------------------+---------+-----------+---------------------------------+ +| hashicorp/precise64 | 1.1.0 | 6,675,725 | virtualbox,vmware_fusion,hyperv | +| hashicorp/precise32 | 1.0.0 | 2,261,377 | virtualbox | +| hashicorp/boot2docker | 1.7.8 | 59,284 | vmware_desktop,virtualbox | +| hashicorp/connect-vm | 0.1.0 | 6,912 | vmware_desktop,virtualbox | +| hashicorp/vagrant-share | 0.1.0 | 3,488 | vmware_desktop,virtualbox | ++-------------------------+---------+-----------+---------------------------------+ +``` + +# Cloud Version + +**Command: `vagrant cloud version`** + +The `cloud version` command is used to manage life cycle operations for all `version` +entities for a box on Vagrant Cloud. + +- [`create`](#cloud-version-create) +- [`delete`](#cloud-version-delete) +- [`release`](#cloud-version-release) +- [`revoke`](#cloud-version-revoke) +- [`update`](#cloud-version-update) + +## Cloud Version Create + +**Command: `vagrant cloud version create ORGANIZATION/BOX-NAME VERSION`** + +The cloud create command creates a version entry for a box on Vagrant Cloud. + +### Options + +- `--description DESCRIPTION` - Description of the version that will be created. + +## Cloud Version Delete + +**Command: `vagrant cloud version delete ORGANIZATION/BOX-NAME VERSION`** + +The cloud delete command deletes a version entry for a box on Vagrant Cloud. +Before making the request, it will ask if you are sure you want to delete the version. + +## Cloud Version Release + +**Command: `vagrant cloud version release ORGANIZATION/BOX-NAME VERSION`** + +The cloud release command releases a version entry for a box on Vagrant Cloud +if it already exists. Before making the request, it will ask if you are sure you +want to release the version. + +## Cloud Version Revoke + +**Command: `vagrant cloud version revoke ORGANIZATION/BOX-NAME VERSION`** + +The cloud revoke command revokes a version entry for a box on Vagrant Cloud +if it already exists. Before making the request, it will ask if you are sure you +want to revoke the version. + +## Cloud Version Update + +**Command: `vagrant cloud version update ORGANIZATION/BOX-NAME VERSION`** + +### Options + +- `--description DESCRIPTION` - Description of the version that will be created. diff --git a/website/pages/docs/cli/connect.html.md b/website/pages/docs/cli/connect.html.md new file mode 100644 index 000000000..95201a8db --- /dev/null +++ b/website/pages/docs/cli/connect.html.md @@ -0,0 +1,34 @@ +--- +layout: 'docs' +page_title: 'vagrant connect - Command-Line Interface' +sidebar_current: 'cli-connect' +description: |- + The "vagrant connect" command compliments the "vagrant share" command to allow + a user to remotely connect to your Vagrant environment. +--- + +# Connect + +**Command: `vagrant connect NAME`** + +The connect command complements the +[share command](/docs/cli/share.html) by enabling access to shared +environments. You can learn about all the details of Vagrant Share in the +[Vagrant Share section](/docs/share/). + +The reference of available command-line flags to this command +is available below. + +## Options + +- `--disable-static-ip` - The connect command will not spin up a small + virtual machine to create a static IP you can access. When this flag is + set, the only way to access the connection is to use the SOCKS proxy + address outputted. + +- `--static-ip IP` - Tells connect what static IP address to use for the virtual + machine. By default, Vagrant connect will use an IP address that looks + available in the 172.16.0.0/16 space. + +- `--ssh` - Connects via SSH to an environment shared with + `vagrant share --ssh`. diff --git a/website/pages/docs/cli/destroy.html.md b/website/pages/docs/cli/destroy.html.md new file mode 100644 index 000000000..84657ac55 --- /dev/null +++ b/website/pages/docs/cli/destroy.html.md @@ -0,0 +1,42 @@ +--- +layout: 'docs' +page_title: 'vagrant destroy - Command-Line Interface' +sidebar_current: 'cli-destroy' +description: |- + The "vagrant destroy" command is used to stop the running virtual machine and + terminate use of all resources that were in use by that machine. +--- + +# Destroy + +**Command: `vagrant destroy [name|id]`** + +This command stops the running machine Vagrant is managing and +destroys all resources that were created during the machine creation process. +After running this command, your computer should be left at a clean state, +as if you never created the guest machine in the first place. + +For linux-based guests, Vagrant uses the `shutdown` command to gracefully +terminate the machine. Due to the varying nature of operating systems, the +`shutdown` command may exist at many different locations in the guest's `$PATH`. +It is the guest machine's responsibility to properly populate the `$PATH` with +directory containing the `shutdown` command. + +## Options + +- `-f` or `--force` - Do not ask for confirmation before destroying. +- `--[no-]parallel` - Destroys multiple machines in parallel if the provider + supports it. Please consult the provider documentation to see if this feature + is supported. + +
+ The `destroy` command does not remove a box that may have been installed on + your computer during `vagrant up`. Thus, even if you run `vagrant destroy`, + the box installed in the system will still be present on the hard drive. To + return your computer to the state as it was before `vagrant up` command, you + need to use `vagrant box remove`. + +For more information, read about the +`vagrant box remove` command. + +
diff --git a/website/pages/docs/cli/global-status.html.md b/website/pages/docs/cli/global-status.html.md new file mode 100644 index 000000000..4ffbb5a79 --- /dev/null +++ b/website/pages/docs/cli/global-status.html.md @@ -0,0 +1,39 @@ +--- +layout: 'docs' +page_title: 'vagrant global-status - Command-Line Interface' +sidebar_current: 'cli-globalstatus' +description: |- + The "vagrant global-status" command is used to determine the state of all + active Vagrant environments on the system for the currently logged in user. +--- + +# Global Status + +**Command: `vagrant global-status`** + +This command will tell you the state of all active Vagrant environments +on the system for the currently logged in user. + +~> **This command does not actively verify the state of machines**, +and is instead based on a cache. Because of this, it is possible to see +stale results (machines say they're running but they're not). For example, +if you restart your computer, Vagrant would not know. To prune the invalid +entries, run global status with the `--prune` flag. + +The IDs in the output that look like `a1b2c3` can be used to control +the Vagrant machine from anywhere on the system. Any Vagrant command +that takes a target machine (such as `up`, `halt`, `destroy`) can be +used with this ID to control it. For example: `vagrant destroy a1b2c3`. + +## Options + +- `--prune` - Prunes invalid entries from the list. This is much more time + consuming than simply listing the entries. + +## Environment Not Showing Up + +If your environment is not showing up, you may have to do a `vagrant destroy` +followed by a `vagrant up`. + +If you just upgraded from a previous version of Vagrant, existing environments +will not show up in global-status until they are destroyed and recreated. diff --git a/website/pages/docs/cli/halt.html.md b/website/pages/docs/cli/halt.html.md new file mode 100644 index 000000000..3d5516c67 --- /dev/null +++ b/website/pages/docs/cli/halt.html.md @@ -0,0 +1,29 @@ +--- +layout: 'docs' +page_title: 'vagrant halt - Command-Line Interface' +sidebar_current: 'cli-halt' +description: |- + The "vagrant halt" command is used to shut down the virtual machine that + Vagrant is currently managing. +--- + +# Halt + +**Command: `vagrant halt [name|id]`** + +This command shuts down the running machine Vagrant is managing. + +Vagrant will first attempt to gracefully shut down the machine by running +the guest OS shutdown mechanism. If this fails, or if the `--force` flag is +specified, Vagrant will effectively just shut off power to the machine. + +For linux-based guests, Vagrant uses the `shutdown` command to gracefully +terminate the machine. Due to the varying nature of operating systems, the +`shutdown` command may exist at many different locations in the guest's `$PATH`. +It is the guest machine's responsibility to properly populate the `$PATH` with +directory containing the `shutdown` command. + +## Options + +- `-f` or `--force` - Do not attempt to gracefully shut down the machine. + This effectively pulls the power on the guest machine. diff --git a/website/pages/docs/cli/index.html.md b/website/pages/docs/cli/index.html.md new file mode 100644 index 000000000..019e1d528 --- /dev/null +++ b/website/pages/docs/cli/index.html.md @@ -0,0 +1,32 @@ +--- +layout: 'docs' +page_title: 'Command-Line Interface' +sidebar_current: 'cli' +description: |- + Almost all interaction with Vagrant is done via the command-line interface. +--- + +# Command-Line Interface + +Almost all interaction with Vagrant is done through the command-line +interface. + +The interface is available using the `vagrant` command, and comes installed +with Vagrant automatically. The `vagrant` command in turn has many subcommands, +such as `vagrant up`, `vagrant destroy`, etc. + +If you run `vagrant` by itself, help will be displayed showing all available +subcommands. In addition to this, you can run any Vagrant command with the +`-h` flag to output help about that specific command. For example, try +running `vagrant init -h`. The help will output a one sentence synopsis of +what the command does as well as a list of all the flags the command +accepts. + +In depth documentation and use cases of various Vagrant commands is +available by reading the appropriate sub-section available in the left +navigational area of this site. + +You may also wish to consult the +[documentation](/docs/other/environmental-variables.html) regarding the +environmental variables that can be used to configure and control +Vagrant in a global way. diff --git a/website/pages/docs/cli/init.html.md b/website/pages/docs/cli/init.html.md new file mode 100644 index 000000000..81901127b --- /dev/null +++ b/website/pages/docs/cli/init.html.md @@ -0,0 +1,71 @@ +--- +layout: 'docs' +page_title: 'vagrant init - Command-Line Interface' +sidebar_current: 'cli-init' +description: |- + The "vagrant init" command is used to initialize the current directory to be + a Vagrant environment by creating an initial Vagrantfile. +--- + +# Init + +**Command: `vagrant init [name [url]]`** + +This initializes the current directory to be a Vagrant environment +by creating an initial [Vagrantfile](/docs/vagrantfile/) if +one does not already exist. + +If a first argument is given, it will prepopulate the `config.vm.box` +setting in the created Vagrantfile. + +If a second argument is given, it will prepopulate the `config.vm.box_url` +setting in the created Vagrantfile. + +## Options + +- `--box-version` - (Optional) The box version or box version constraint to add + to the `Vagrantfile`. + +- `--force` - If specified, this command will overwrite any existing + `Vagrantfile`. + +- `--minimal` - If specified, a minimal Vagrantfile will be created. This + Vagrantfile does not contain the instructional comments that the normal + Vagrantfile contains. + +- `--output FILE` - This will output the Vagrantfile to the given file. + If this is "-", the Vagrantfile will be sent to stdout. + +- `--template FILE` - Provide a custom ERB template for generating the Vagrantfile. + +## Examples + +Create a base Vagrantfile: + +```sh +$ vagrant init hashicorp/bionic64 +``` + +Create a minimal Vagrantfile (no comments or helpers): + +```sh +$ vagrant init -m hashicorp/bionic64 +``` + +Create a new Vagrantfile, overwriting the one at the current path: + +```sh +$ vagrant init -f hashicorp/bionic64 +``` + +Create a Vagrantfile with the specific box, from the specific box URL: + +```sh +$ vagrant init my-company-box https://boxes.company.com/my-company.box +``` + +Create a Vagrantfile, locking the box to a version constraint: + +```sh +$ vagrant init --box-version '> 0.1.5' hashicorp/bionic64 +``` diff --git a/website/pages/docs/cli/login.html.md b/website/pages/docs/cli/login.html.md new file mode 100644 index 000000000..bdb0ef46b --- /dev/null +++ b/website/pages/docs/cli/login.html.md @@ -0,0 +1,62 @@ +--- +layout: 'docs' +page_title: 'vagrant login - Command-Line Interface' +sidebar_current: 'cli-login' +description: |- + The "vagrant login" command is used to authenticate Vagrant with HashiCorp's + Vagrant Cloud service to use features like private boxes and "vagrant push". +--- + +# Login + +**Command: `vagrant login`** + +The login command is used to authenticate with the +[HashiCorp's Vagrant Cloud](/docs/vagrant-cloud) server. Logging in is only +necessary if you are accessing protected boxes or using +[Vagrant Share](/docs/share/). + +**Logging in is not a requirement to use Vagrant.** The vast majority +of Vagrant does _not_ require a login. Only certain features such as protected +boxes or [Vagrant Share](/docs/share/) require a login. + +The reference of available command-line flags to this command +is available below. + +## Options + +- `--check` - This will check if you are logged in. In addition to outputting + whether you are logged in or not, the command will have exit status 0 if you are + logged in, and exit status 1 if you are not. + +- `--logout` - This will log you out if you are logged in. If you are already + logged out, this command will do nothing. It is not an error to call this + command if you are already logged out. + +- `--token` - This will set the Vagrant Cloud login token manually to the provided + string. It is assumed this token is a valid Vagrant Cloud access token. + +## Examples + +Securely authenticate to Vagrant Cloud using a username and password: + +```text +$ vagrant login +# ... +Vagrant Cloud username: +Vagrant Cloud password: +``` + +Check if the current user is authenticated: + +```text +$ vagrant login --check +You are already logged in. +``` + +Securely authenticate with Vagrant Cloud using a token: + +```text +$ vagrant login --token ABCD1234 +The token was successfully saved. +``` diff --git a/website/pages/docs/cli/machine-readable.html.md b/website/pages/docs/cli/machine-readable.html.md new file mode 100644 index 000000000..02c9d085c --- /dev/null +++ b/website/pages/docs/cli/machine-readable.html.md @@ -0,0 +1,162 @@ +--- +layout: 'docs' +page_title: 'Machine Readable Output - Command-Line Interface' +sidebar_current: 'cli-machinereadable' +description: |- + Almost all commands in Vagrant accept a --machine-readable flag to enable + machine-readable output mode. +--- + +# Machine Readable Output + +Every Vagrant command accepts a `--machine-readable` flag which enables +machine readable output mode. In this mode, the output to the terminal +is replaced with machine-friendly output. + +This mode makes it easy to programmatically execute Vagrant and read data +out of it. This output format is protected by our +[backwards compatibility](/docs/installation/backwards-compatibility.html) +policy. Until Vagrant 2.0 is released, however, the machine readable output +may change as we determine more use cases for it. But the backwards +compatibility promise should make it safe to write client libraries to +parse the output format. + +
+ Advanced topic! This is an advanced topic for use only if + you want to programmatically execute Vagrant. If you are just getting started + with Vagrant, you may safely skip this section. +
+ +## Work-In-Progress + +The machine-readable output is very new (released as part of Vagrant 1.4). +We're still gathering use cases for it and building up the output for each +of the commands. It is likely that what you may want to achieve with +the machine-readable output is not possible due to missing information. + +In this case, we ask that you please +[open an issue](https://github.com/hashicorp/vagrant/issues) +requesting that certain information become available. We will most likely add +it! + +## Format + +The machine readable format is a line-oriented, comma-delimited text format. +This makes it extremely easy to parse using standard Unix tools such as awk or +grep in addition to full programming languages like Ruby or Python. + +The format is: + +``` +timestamp,target,type,data... +``` + +Each component is explained below: + +- **timestamp** is a Unix timestamp in UTC of when the message was printed. + +- **target** is the target of the following output. This is empty if the + message is related to Vagrant globally. Otherwise, this is generally a machine + name so you can relate output to a specific machine when multi-VM is in use. + +- **type** is the type of machine-readable message being outputted. There are + a set of standard types which are covered later. + +- **data** is zero or more comma-separated values associated with the prior + type. The exact amount and meaning of this data is type-dependent, so you + must read the documentation associated with the type to understand fully. + +Within the format, if data contains a comma, it is replaced with +`%!(VAGRANT_COMMA)`. This was preferred over an escape character such as \' +because it is more friendly to tools like awk. + +Newlines within the format are replaced with their respective standard escape +sequence. Newlines become a literal `\n` within the output. Carriage returns +become a literal `\r`. + +## Types + +This section documents all the available types that may be outputted +with the machine-readable output. + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
TypeDescription
box-name + Name of a box installed into Vagrant. +
box-provider + Provider for an installed box. +
cli-command + A subcommand of vagrant that is available. +
error-exit + An error occurred that caused Vagrant to exit. This contains that + error. Contains two data elements: type of error, error message. +
provider-name + The provider name of the target machine. + targeted +
ssh-config + The OpenSSH compatible SSH config for a machine. This is usually + the result of the "ssh-config" command. + targeted +
state + The state ID of the target machine. + targeted +
state-human-long + Human-readable description of the state of the machine. This is the + long version, and may be a paragraph or longer. + targeted +
state-human-short + Human-readable description of the state of the machine. This is the + short version, limited to at most a sentence. + targeted +
diff --git a/website/pages/docs/cli/non-primary.html.md b/website/pages/docs/cli/non-primary.html.md new file mode 100644 index 000000000..60a9c10f3 --- /dev/null +++ b/website/pages/docs/cli/non-primary.html.md @@ -0,0 +1,34 @@ +--- +layout: 'docs' +page_title: 'More Vagrant Commands - Command-Line Interface' +sidebar_current: 'cli-nonprimary' +description: |- + In addition to the commands listed in the sidebar and shown in "vagrant -h", + Vagrant comes with some more commands that are hidden from basic help output. + These commands are hidden because they're not useful to beginners or they're + not commonly used. We call these commands "non-primary subcommands". +--- + +# More Commands + +In addition to the commands listed in the sidebar and shown in `vagrant -h`, +Vagrant comes with some more commands that are hidden from basic help output. +These commands are hidden because they're not useful to beginners or they're +not commonly used. We call these commands "non-primary subcommands". + +You can view all subcommands, including the non-primary subcommands, +by running `vagrant list-commands`, which itself is a non-primary subcommand! + +Note that while you have to run a special command to list the non-primary +subcommands, you do not have to do anything special to actually _run_ the +non-primary subcommands. They're executed just like any other subcommand: +`vagrant COMMAND`. + +The list of non-primary commands is below. Click on any command to learn +more about it. + +- [docker-exec](/docs/docker/commands.html) +- [docker-logs](/docs/docker/commands.html) +- [docker-run](/docs/docker/commands.html) +- [rsync](/docs/cli/rsync.html) +- [rsync-auto](/docs/cli/rsync-auto.html) diff --git a/website/pages/docs/cli/package.html.md b/website/pages/docs/cli/package.html.md new file mode 100644 index 000000000..5f409c738 --- /dev/null +++ b/website/pages/docs/cli/package.html.md @@ -0,0 +1,44 @@ +--- +layout: 'docs' +page_title: 'vagrant package - Command-Line Interface' +sidebar_current: 'cli-package' +description: |- + The "vagrant package" command is used to package a currently-running + VirtualBox or Hyper-V vagrant environment into a reusable Vagrant box. +--- + +# Package + +**Command: `vagrant package [name|id]`** + +This packages a currently running _VirtualBox_ or _Hyper-V_ environment into a +re-usable [box](/docs/boxes.html). This command can only be used with +other [providers](/docs/providers/) based on the provider implementation +and if the provider supports it. + +## Options + +- `--base NAME` - Instead of packaging a VirtualBox machine that Vagrant + manages, this will package a VirtualBox machine that VirtualBox manages. + `NAME` should be the name or UUID of the machine from the VirtualBox GUI. + Currently this option is only available for VirtualBox. + +- `--output NAME` - The resulting package will be saved as `NAME`. By default, + it will be saved as `package.box`. + +- `--include x,y,z` - Additional files will be packaged with the box. These + can be used by a packaged Vagrantfile (documented below) to perform additional + tasks. + +- `--vagrantfile FILE` - Packages a Vagrantfile with the box, that is loaded + as part of the [Vagrantfile load order](/docs/vagrantfile/#load-order) + when the resulting box is used. + +
+ A common misconception is that the --vagrantfile + option will package a Vagrantfile that is used when vagrant init + is used with this box. This is not the case. Instead, a Vagrantfile + is loaded and read as part of the Vagrant load process when the box is + used. For more information, read about the + Vagrantfile load order. +
diff --git a/website/pages/docs/cli/plugin.html.md b/website/pages/docs/cli/plugin.html.md new file mode 100644 index 000000000..33b94c8eb --- /dev/null +++ b/website/pages/docs/cli/plugin.html.md @@ -0,0 +1,165 @@ +--- +layout: 'docs' +page_title: 'vagrant plugin - Command-Line Interface' +sidebar_current: 'cli-plugin' +description: |- + The "vagrant plugin" command is used to manage Vagrant plugins including + installing, uninstalling, and license management. +--- + +# Plugin + +**Command: `vagrant plugin`** + +This is the command used to manage [plugins](/docs/plugins/). + +The main functionality of this command is exposed via another level +of subcommands: + +- [`expunge`](#plugin-expunge) +- [`install`](#plugin-install) +- [`license`](#plugin-license) +- [`list`](#plugin-list) +- [`repair`](#plugin-repair) +- [`uninstall`](#plugin-uninstall) +- [`update`](#plugin-update) + +# Plugin Expunge + +**Command: `vagrant plugin expunge`** + +This removes all user installed plugin information. All plugin gems, their +dependencies, and the `plugins.json` file are removed. This command +provides a simple mechanism to fully remove all user installed custom plugins. + +When upgrading Vagrant it may be required to reinstall plugins due to +an internal incompatibility. The expunge command can help make that process +easier by attempting to automatically reinstall currently configured +plugins: + +```shell +# Delete all plugins and reinstall +$ vagrant plugin expunge --reinstall +``` + +This command accepts optional command-line flags: + +- `--force` - Do not prompt for confirmation prior to removal +- `--global-only` - Only expunge global plugins +- `--local` - Include plugins in local project +- `--local-only` - Only expunge local project plugins +- `--reinstall` - Attempt to reinstall plugins after removal + +# Plugin Install + +**Command: `vagrant plugin install ...`** + +This installs a plugin with the given name or file path. If the name +is not a path to a file, then the plugin is installed from remote +repositories, usually [RubyGems](https://rubygems.org). This command will +also update a plugin if it is already installed, but you can also use +`vagrant plugin update` for that. + +```shell +# Installing a plugin from a known gem source +$ vagrant plugin install my-plugin + +# Installing a plugin from a local file source +$ vagrant plugin install /path/to/my-plugin.gem +``` + +If multiple names are specified, multiple plugins will be installed. If +flags are given below, the flags will apply to _all_ plugins being installed +by the current command invocation. + +If the plugin is already installed, this command will reinstall it with +the latest version available. + +This command accepts optional command-line flags: + +- `--entry-point ENTRYPOINT` - By default, installed plugins are loaded + internally by loading an initialization file of the same name as the plugin. + Most of the time, this is correct. If the plugin you are installing has + another entrypoint, this flag can be used to specify it. + +- `--local` - Install plugin to the local Vagrant project only. + +- `--plugin-clean-sources` - Clears all sources that have been defined so + far. This is an advanced feature. The use case is primarily for corporate + firewalls that prevent access to RubyGems.org. + +- `--plugin-source SOURCE` - Adds a source from which to fetch a plugin. Note + that this does not only affect the single plugin being installed, by all future + plugin as well. This is a limitation of the underlying plugin installer + Vagrant uses. + +- `--plugin-version VERSION` - The version of the plugin to install. By default, + this command will install the latest version. You can constrain the version + using this flag. You can set it to a specific version, such as "1.2.3" or + you can set it to a version constraint, such as "> 1.0.2". You can set it + to a more complex constraint by comma-separating multiple constraints: + "> 1.0.2, < 1.1.0" (do not forget to quote these on the command-line). + +# Plugin License + +**Command: `vagrant plugin license `** + +This command installs a license for a proprietary Vagrant plugin, +such as the [VMware Fusion provider](/docs/vmware). + +# Plugin List + +**Command: `vagrant plugin list`** + +This lists all installed plugins and their respective installed versions. +If a version constraint was specified for a plugin when installing it, the +constraint will be listed as well. Other plugin-specific information may +be shown, too. + +This command accepts optional command-line flags: + +- `--local` - Include local project plugins. + +# Plugin Repair + +Vagrant may fail to properly initialize user installed custom plugins. This can +be caused my improper plugin installation/removal, or by manual manipulation of +plugin related files like the `plugins.json` data file. Vagrant can attempt +to automatically repair the problem. + +If automatic repair is not successful, refer to the [expunge](#plugin-expunge) +command + +This command accepts optional command-line flags: + +- `--local` - Repair local project plugins. + +# Plugin Uninstall + +**Command: `vagrant plugin uninstall [ ...]`** + +This uninstalls the plugin with the given name. Any dependencies of the +plugin will also be uninstalled assuming no other plugin needs them. + +If multiple plugins are given, multiple plugins will be uninstalled. + +This command accepts optional command-line flags: + +- `--local` - Uninstall plugin from local project. + +# Plugin Update + +**Command: `vagrant plugin update []`** + +This updates the plugins that are installed within Vagrant. If you specified +version constraints when installing the plugin, this command will respect +those constraints. If you want to change a version constraint, re-install +the plugin using `vagrant plugin install`. + +If a name is specified, only that single plugin will be updated. If a +name is specified of a plugin that is not installed, this command will not +install it. + +This command accepts optional command-line flags: + +- `--local` - Update plugin from local project. diff --git a/website/pages/docs/cli/port.html.md b/website/pages/docs/cli/port.html.md new file mode 100644 index 000000000..b38131b42 --- /dev/null +++ b/website/pages/docs/cli/port.html.md @@ -0,0 +1,39 @@ +--- +layout: 'docs' +page_title: 'vagrant port - Command-Line Interface' +sidebar_current: 'cli-port' +description: |- + The "vagrant port" command is used to display the full list of guest ports + mapped to the host machine ports. +--- + +# Port + +**Command: `vagrant port [name|id]`** + +The port command displays the full list of guest ports mapped to the host +machine ports: + +``` +$ vagrant port + 22 (guest) => 2222 (host) + 80 (guest) => 8080 (host) +``` + +In a multi-machine Vagrantfile, the name of the machine must be specified: + +``` +$ vagrant port my-machine +``` + +## Options + +- `--guest PORT` - This displays just the host port that corresponds to the + given guest port. If the guest is not forwarding that port, an error is + returned. This is useful for quick scripting, for example: + + $ ssh -p $(vagrant port --guest 22) + +- `--machine-readable` - This tells Vagrant to display machine-readable output + instead of the human-friendly output. More information is available in the + [machine-readable output](/docs/cli/machine-readable.html) documentation. diff --git a/website/pages/docs/cli/powershell.html.md b/website/pages/docs/cli/powershell.html.md new file mode 100644 index 000000000..4135aee78 --- /dev/null +++ b/website/pages/docs/cli/powershell.html.md @@ -0,0 +1,23 @@ +--- +layout: 'docs' +page_title: 'vagrant powershell - Command-Line Interface' +sidebar_current: 'cli-powershell' +description: |- + The "vagrant powershell" command is used to open a powershell prompt running + inside the guest machine. +--- + +# PowerShell + +**Command: `vagrant powershell`** + +This will open a PowerShell prompt on the host into a running Vagrant guest machine. + +This command will only work if the machines supports PowerShell. Not every +environment will support PowerShell. At the moment, only Windows is supported +with this command. + +## Options + +- `-c COMMAND` or `--command COMMAND` - This executes a single PowerShell command, + prints out the stdout and stderr, and exits. diff --git a/website/pages/docs/cli/provision.html.md b/website/pages/docs/cli/provision.html.md new file mode 100644 index 000000000..218c09f22 --- /dev/null +++ b/website/pages/docs/cli/provision.html.md @@ -0,0 +1,28 @@ +--- +layout: 'docs' +page_title: 'vagrant provision - Command-Line Interface' +sidebar_current: 'cli-provision' +description: |- + The "vagrant provision" command is used to run any provisioners configured + for the guest machine, such as Puppet, Chef, Ansible, Salt, or Shell. +--- + +# Provision + +**Command: `vagrant provision [vm-name]`** + +Runs any configured [provisioners](/docs/provisioning/) +against the running Vagrant managed machine. + +This command is a great way to quickly test any provisioners, and is especially +useful for incremental development of shell scripts, Chef cookbooks, or Puppet +modules. You can just make simple modifications to the provisioning scripts +on your machine, run a `vagrant provision`, and check for the desired results. +Rinse and repeat. + +# Options + +- `--provision-with x,y,z` - This will only run the given provisioners. For + example, if you have a `:shell` and `:chef_solo` provisioner and run + `vagrant provision --provision-with shell`, only the shell provisioner will + be run. diff --git a/website/pages/docs/cli/rdp.html.md b/website/pages/docs/cli/rdp.html.md new file mode 100644 index 000000000..22ef1881c --- /dev/null +++ b/website/pages/docs/cli/rdp.html.md @@ -0,0 +1,42 @@ +--- +layout: 'docs' +page_title: 'vagrant rdp - Command-Line Interface' +sidebar_current: 'cli-rdp' +description: |- + The "vagrant rdp" command is used to start an RDP client for a remote desktop + session with the guest machine. +--- + +# RDP + +**Command: `vagrant rdp`** + +This will start an RDP client for a remote desktop session with the +guest. This only works for Vagrant environments that support remote +desktop, which is typically only Windows. + +## Raw Arguments + +You can pass raw arguments through to your RDP client on the +command-line by appending it after a `--`. Vagrant just passes +these through. For example: + +``` +$ vagrant rdp -- /span +``` + +The above command on Windows will execute `mstsc.exe /span config.rdp`, +allowing your RDP to span multiple desktops. + +On Darwin hosts, such as Mac OS X, the additional arguments are added to the +generated RDP configuration file. Since these files can contain multiple options +with different spacing, you _must_ quote multiple arguments. For example: + +``` +$ vagrant rdp -- "screen mode id:i:0" "other config:s:value" +``` + +Note that as of the publishing of this guide, the Microsoft RDP Client for Mac +does _not_ perform validation on the configuration file. This means if you +specify an invalid configuration option or make a typographical error, the +client will silently ignore the error and continue! diff --git a/website/pages/docs/cli/reload.html.md b/website/pages/docs/cli/reload.html.md new file mode 100644 index 000000000..933081fa3 --- /dev/null +++ b/website/pages/docs/cli/reload.html.md @@ -0,0 +1,31 @@ +--- +layout: 'docs' +page_title: 'vagrant reload - Command-Line Interface' +sidebar_current: 'cli-reload' +description: |- + The "vagrant reload" command is the equivalent of running "vagrant halt" + followed by "vagrant up". +--- + +# Reload + +**Command: `vagrant reload [name|id]`** + +The equivalent of running a [halt](/docs/cli/halt.html) followed by an +[up](/docs/cli/up.html). + +This command is usually required for changes made in the Vagrantfile to +take effect. After making any modifications to the Vagrantfile, a `reload` +should be called. + +The configured provisioners will not run again, by default. You can force +the provisioners to re-run by specifying the `--provision` flag. + +# Options + +- `--provision` - Force the provisioners to run. + +- `--provision-with x,y,z` - This will only run the given provisioners. For + example, if you have a `:shell` and `:chef_solo` provisioner and run + `vagrant reload --provision-with shell`, only the shell provisioner will + be run. diff --git a/website/pages/docs/cli/resume.html.md b/website/pages/docs/cli/resume.html.md new file mode 100644 index 000000000..8b24373b5 --- /dev/null +++ b/website/pages/docs/cli/resume.html.md @@ -0,0 +1,28 @@ +--- +layout: 'docs' +page_title: 'vagrant resume - Command-Line Interface' +sidebar_current: 'cli-resume' +description: |- + The "vagrant resume" command is used to bring a machine back into the "up" + state, perhaps if it was previously suspended via "vagrant halt" or "vagrant + suspend". +--- + +# Resume + +**Command: `vagrant resume [name|id]`** + +This resumes a Vagrant managed machine that was previously suspended, +perhaps with the [suspend command](/docs/cli/suspend.html). + +The configured provisioners will not run again, by default. You can force +the provisioners to re-run by specifying the `--provision` flag. + +# Options + +- `--provision` - Force the provisioners to run. + +- `--provision-with x,y,z` - This will only run the given provisioners. For + example, if you have a `:shell` and `:chef_solo` provisioner and run + `vagrant provision --provision-with shell`, only the shell provisioner will + be run. diff --git a/website/pages/docs/cli/rsync-auto.html.md b/website/pages/docs/cli/rsync-auto.html.md new file mode 100644 index 000000000..9461770a3 --- /dev/null +++ b/website/pages/docs/cli/rsync-auto.html.md @@ -0,0 +1,56 @@ +--- +layout: 'docs' +page_title: 'vagrant rsync-auto - Command-Line Interface' +sidebar_current: 'cli-rsyncauto' +description: |- + The "vagrant rsync-auto" command watches all local directories of any rsync + configured synced folders and automatically initiates an rsync transfer when + changes are detected. +--- + +# rsync-auto + +**Command: `vagrant rsync-auto`** + +This command watches all local directories of any +[rsync synced folders](/docs/synced-folders/rsync.html) and automatically +initiates an rsync transfer when changes are detected. This command does +not exit until an interrupt is received. + +The change detection is optimized to use platform-specific APIs to listen +for filesystem changes, and does not simply poll the directory. + +## Options + +- `--[no-]rsync-chown` - Use rsync to modify ownership of transferred files. Enabling + this option can result in faster completion due to a secondary process not being + required to update ownership. By default this is disabled. + +- `--[no-]poll` - Force Vagrant to watch for changes using filesystem + polling instead of filesystem events. This is required for some filesystems + that do not support events. Warning: enabling this will make `rsync-auto` + _much_ slower. By default, polling is disabled. + +## Machine State Changes + +The `rsync-auto` command does not currently handle machine state changes +gracefully. For example, if you start the `rsync-auto` command, then +halt the guest machine, then make changes to some files, then boot it +back up, `rsync-auto` will not attempt to resync. + +To ensure that the command works properly, you should start `rsync-auto` +only when the machine is running, and shut it down before any machine +state changes. + +You can always force a resync with the [rsync](/docs/cli/rsync.html) command. + +## Vagrantfile Changes + +If you change or move your Vagrantfile, the `rsync-auto` command will have +to be restarted. For example, if you add synced folders to the Vagrantfile, +or move the directory that contains the Vagrantfile, the `rsync-auto` +command will either not pick up the changes or may begin experiencing +strange behavior. + +Before making any such changes, it is recommended that you turn off +`rsync-auto`, then restart it afterwards. diff --git a/website/pages/docs/cli/rsync.html.md b/website/pages/docs/cli/rsync.html.md new file mode 100644 index 000000000..f4b391005 --- /dev/null +++ b/website/pages/docs/cli/rsync.html.md @@ -0,0 +1,24 @@ +--- +layout: 'docs' +page_title: 'vagrant rsync - Command-Line Interface' +sidebar_current: 'cli-rsync' +description: |- + The "vagrant rsync" command forces a re-sync of any rsync synced folders. +--- + +# Rsync + +**Command: `vagrant rsync`** + +This command forces a re-sync of any +[rsync synced folders](/docs/synced-folders/rsync.html). + +Note that if you change any settings within the rsync synced folders such +as exclude paths, you will need to `vagrant reload` before this command will +pick up those changes. + +## Options + +- `--[no-]rsync-chown` - Use rsync to modify ownership of transferred files. Enabling + this option can result in faster completion due to a secondary process not being + required to update ownership. By default this is disabled. diff --git a/website/pages/docs/cli/share.html.md b/website/pages/docs/cli/share.html.md new file mode 100644 index 000000000..69522a62e --- /dev/null +++ b/website/pages/docs/cli/share.html.md @@ -0,0 +1,49 @@ +--- +layout: 'docs' +page_title: 'vagrant share - Command-Line Interface' +sidebar_current: 'cli-share' +description: |- + The "vagrant share" command initializes a new Vagrant share session, which + allows you to share your virtual machine with the public Internet. +--- + +# Share + +**Command: `vagrant share`** + +The share command initializes a Vagrant Share session, allowing you to +share your Vagrant environment with anyone in the world, enabling collaboration +directly in your Vagrant environment in almost any network environment. + +You can learn about all the details of Vagrant Share in the +[Vagrant Share section](/docs/share/). + +The reference of available command-line flags to this command +is available below. + +## Options + +- `--disable-http` - Disables the creation of a publicly accessible + HTTP endpoint to your Vagrant environment. With this set, the only way + to access your share is with `vagrant connect`. + +- `--http PORT` - The port of the HTTP server running in the Vagrant + environment. By default, Vagrant will attempt to find this for you. + This has no effect if `--disable-http` is set. + +- `--https PORT` - The port of an HTTPS server running in the Vagrant + environment. By default, Vagrant will attempt to find this for you. + This has no effect if `--disable-http` is set. + +- `--ssh` - Enables SSH sharing (more information below). By default, this + is not enabled. + +- `--ssh-no-password` - Disables the encryption of the SSH keypair created + when SSH sharing is enabled. + +- `--ssh-port PORT` - The port of the SSH server running in the Vagrant + environment. By default, Vagrant will attempt to find this for you. + +- `--ssh-once` - Allows SSH access only once. After the first attempt to + connect via SSH to the Vagrant environment, the generated keypair is + destroyed. diff --git a/website/pages/docs/cli/snapshot.html.md b/website/pages/docs/cli/snapshot.html.md new file mode 100644 index 000000000..5731df004 --- /dev/null +++ b/website/pages/docs/cli/snapshot.html.md @@ -0,0 +1,98 @@ +--- +layout: 'docs' +page_title: 'vagrant snapshot - Command-Line Interface' +sidebar_current: 'cli-snapshot' +description: |- + The "vagrant snapshot" command is used to manage snapshots of the guest + machine. +--- + +# Snapshot + +**Command: `vagrant snapshot`** + +This is the command used to manage snapshots with the guest machine. +Snapshots record a point-in-time state of a guest machine. You can then +quickly restore to this environment. This lets you experiment and try things +and quickly restore back to a previous state. + +Snapshotting is not supported by every provider. If it is not supported, +Vagrant will give you an error message. + +The main functionality of this command is exposed via even more subcommands: + +- [`push`](#snapshot-push) +- [`pop`](#snapshot-pop) +- [`save`](#snapshot-save) +- [`restore`](#snapshot-restore) +- [`list`](#snapshot-list) +- [`delete`](#snapshot-delete) + +# Snapshot Push + +**Command: `vagrant snapshot push`** + +This takes a snapshot and pushes it onto the snapshot stack. + +This is a shorthand for `vagrant snapshot save` where you do not need +to specify a name. When you call the inverse `vagrant snapshot pop`, it will +restore the pushed state. + +~> **Warning:** If you are using `push` and `pop`, avoid using `save` +and `restore` which are unsafe to mix. + +# Snapshot Pop + +**Command: `vagrant snapshot pop`** + +This command is the inverse of `vagrant snapshot push`: it will restore +the pushed state. + +## Options + +- `--[no-]provision` - Force the provisioners to run (or prevent them + from doing so). + +- `--no-delete` - Prevents deletion of the snapshot after restoring + (so that you can restore to the same point again later). + +- `--no-start` - Prevents the guest from being started after restore + +# Snapshot Save + +**Command: `vagrant snapshot save [vm-name] NAME`** + +This command saves a new named snapshot. If this command is used, the +`push` and `pop` subcommands cannot be safely used. + +# Snapshot Restore + +**Command: `vagrant snapshot restore [vm-name] NAME`** + +This command restores the named snapshot. + +- `--[no-]provision` - Force the provisioners to run (or prevent them + from doing so). + +- `--no-start` - Prevents the guest from being started after restore + +# Snapshot List + +**Command: `vagrant snapshot list`** + +This command will list all the snapshots taken. + +# Snapshot Delete + +**Command: `vagrant snapshot delete [vm-name] NAME`** + +This command will delete the named snapshot. + +Some providers require all "child" snapshots to be deleted first. Vagrant +itself does not track what these children are. If this is the case (such +as with VirtualBox), then you must be sure to delete the snapshots in the +reverse order they were taken. + +This command is typically _much faster_ if the machine is halted prior to +snapshotting. If this is not an option, or is not ideal, then the deletion +can also be done online with most providers. diff --git a/website/pages/docs/cli/ssh.html.md b/website/pages/docs/cli/ssh.html.md new file mode 100644 index 000000000..e99a3b942 --- /dev/null +++ b/website/pages/docs/cli/ssh.html.md @@ -0,0 +1,140 @@ +--- +layout: 'docs' +page_title: 'vagrant ssh - Command-Line Interface' +sidebar_current: 'cli-ssh' +description: |- + The "vagrant ssh" command is used to establish an SSH session into a running + virtual machine to give you shell access. +--- + +# SSH + +**Command: `vagrant ssh [name|id] [-- extra_ssh_args]`** + +This will SSH into a running Vagrant machine and give you access to a shell. + +On a simple vagrant project, the instance created will be named default. + +Vagrant will ssh into this instance without the instance name: + +```bash +$ vagrant ssh + +Welcome to your Vagrant-built virtual machine. +Last login: Fri Sep 14 06:23:18 2012 from 10.0.2.2 +$ logout +Connection to 127.0.0.1 closed. +``` + +Or you could use the name: + +```bash +$ vagrant ssh default + + +Welcome to your Vagrant-built virtual machine. +Last login: Fri Jul 20 15:09:52 2018 from 10.0.2.2 +$ logout +Connection to 127.0.0.1 closed. +$ +``` + +On multi-machine setups, you can login to each vm using the name as displayed +on `vagrant status` + +```bash + $ vagrant status +Current machine states: + +node1 running (virtualbox) +node2 running (virtualbox) + +This environment represents multiple VMs. The VMs are all listed +above with their current state. +$ vagrant ssh node1 + +Welcome to your Vagrant-built virtual machine. +Last login: Fri Sep 14 06:23:18 2012 from 10.0.2.2 +vagrant@bionic64:~$ logout +Connection to 127.0.0.1 closed. +$ vagrant ssh node2 + +Welcome to your Vagrant-built virtual machine. +Last login: Fri Sep 14 06:23:18 2012 from 10.0.2.2 +vagrant@bionic64:~$ logout +Connection to 127.0.0.1 closed. +$ +``` + +On a system with machines running from different projects, you could use the id +as listed in `vagrant global-status` + +```bash +$ vagrant global-status +id name provider state directory +----------------------------------------------------------------------- +13759ff node1 virtualbox running /Users/user/vagrant/folder + +The above shows information about all known Vagrant environments +on this machine. This data is cached and may not be completely +up-to-date (use "vagrant global-status --prune" to prune invalid +entries). To interact with any of the machines, you can go to that +directory and run Vagrant, or you can use the ID directly with +Vagrant commands from any directory. +$ vagrant ssh 13759ff + +Welcome to your Vagrant-built virtual machine. +Last login: Fri Jul 20 15:19:36 2018 from 10.0.2.2 +vagrant@bionic64:~$ logout +Connection to 127.0.0.1 closed. +$ +``` + +If a `--` (two hyphens) are found on the command line, any arguments after +this are passed directly into the `ssh` executable. This allows you to pass +any arbitrary commands to do things such as reverse tunneling down into the +`ssh` program. + +## Options + +- `-c COMMAND` or `--command COMMAND` - This executes a single SSH command, prints + out the stdout and stderr, and exits. + +- `-p` or `--plain` - This does an SSH without authentication, leaving + authentication up to the user. + +## SSH client usage + +Vagrant will attempt to use the local SSH client installed on the host machine. On +POSIX machines, an SSH client must be installed and available on the PATH. + +For Windows installations, an SSH client is provided within the installer +image. If no SSH client is found on the current PATH, Vagrant will use the +SSH client it provided. Depending on the local environment used for running +Vagrant, the installer provided SSH client may not work correctly. For example, +when using a cygwin or msys2 shell the SSH client will fail to work as expected +when run interactively. Installing the SSH package built for the current working +environment will resolve this issue. + +## Background Execution + +If the command you specify runs in the background (such as appending a `&` to +a shell command), it will be terminated almost immediately. This is because +when Vagrant executes the command, it executes it within the context of a +shell, and when the shell exits, all of the child processes also exit. + +To avoid this, you will need to detach the process from the shell. Please +Google to learn how to do this for your shell. One method of doing this is +the `nohup` command. + +## Pageant on Windows + +The SSH executable will not be able to access Pageant on Windows. While +Vagrant is capable of accessing Pageant via internal libraries, the +SSH executable does not have support for Pageant. This means keys +from Pageant will not be available for forwarding when using the +`vagrant ssh` command. + +Third party programs exist to allow the SSH executable to access Pageant +by creating a unix socket for the SSH executable to read. For more information +please see [ssh-pageant](https://github.com/cuviper/ssh-pageant). diff --git a/website/pages/docs/cli/ssh_config.html.md b/website/pages/docs/cli/ssh_config.html.md new file mode 100644 index 000000000..a5480ec83 --- /dev/null +++ b/website/pages/docs/cli/ssh_config.html.md @@ -0,0 +1,20 @@ +--- +layout: 'docs' +page_title: 'vagrant ssh-config - Command-Line Interface' +sidebar_current: 'cli-ssh_config' +description: |- + The "vagrant ssh-config" command is used to output a valid SSH configuration + file capable of SSHing into the guest machine directly. +--- + +# SSH Config + +**Command: `vagrant ssh-config [name|id]`** + +This will output valid configuration for an SSH config file to SSH +into the running Vagrant machine from `ssh` directly (instead of +using `vagrant ssh`). + +## Options + +- `--host NAME` - Name of the host for the outputted configuration. diff --git a/website/pages/docs/cli/status.html.md b/website/pages/docs/cli/status.html.md new file mode 100644 index 000000000..5c5e0dc7b --- /dev/null +++ b/website/pages/docs/cli/status.html.md @@ -0,0 +1,18 @@ +--- +layout: 'docs' +page_title: 'vagrant status - Command-Line Interface' +sidebar_current: 'cli-status' +description: |- + The "vagrant status" command is used to tell you the status of the virtual + machines in the current Vagrant environment. +--- + +# Status + +**Command: `vagrant status [name|id]`** + +This will tell you the state of the machines Vagrant is managing. + +It is quite easy, especially once you get comfortable with Vagrant, to +forget whether your Vagrant machine is running, suspended, not created, etc. +This command tells you the state of the underlying guest machine. diff --git a/website/pages/docs/cli/suspend.html.md b/website/pages/docs/cli/suspend.html.md new file mode 100644 index 000000000..549634071 --- /dev/null +++ b/website/pages/docs/cli/suspend.html.md @@ -0,0 +1,23 @@ +--- +layout: 'docs' +page_title: 'vagrant suspend - Command-Line Interface' +sidebar_current: 'cli-suspend' +description: |- + The "vagrant suspend" command is used to suspend the guest machine Vagrant is + currently managing. +--- + +# Suspend + +**Command: `vagrant suspend [name|id]`** + +This suspends the guest machine Vagrant is managing, rather than fully +[shutting it down](/docs/cli/halt.html) or [destroying it](/docs/cli/destroy.html). + +A suspend effectively saves the _exact point-in-time state_ of the machine, +so that when you [resume](/docs/cli/resume.html) it later, it begins running +immediately from that point, rather than doing a full boot. + +This generally requires extra disk space to store all the contents of the +RAM within your guest machine, but the machine no longer consumes the +RAM of your host machine or CPU cycles while it is suspended. diff --git a/website/pages/docs/cli/up.html.md b/website/pages/docs/cli/up.html.md new file mode 100644 index 000000000..ae1aad986 --- /dev/null +++ b/website/pages/docs/cli/up.html.md @@ -0,0 +1,48 @@ +--- +layout: 'docs' +page_title: 'vagrant up - Command-Line Interface' +sidebar_current: 'cli-up' +description: |- + The "vagrant up" command is used to create, configuration, and provision a + guest machine according to your Vagrantfile. +--- + +# Up + +**Command: `vagrant up [name|id]`** + +This command creates and configures guest machines according to your +[Vagrantfile](/docs/vagrantfile/). + +This is the single most important command in Vagrant, since it is how +any Vagrant machine is created. Anyone using Vagrant must use this command +on a day-to-day basis. + +## Options + +- `name` - Name of machine defined in [Vagrantfile](/docs/vagrantfile/) + +- `id` - Machine id found with `vagrant global-status`. Using `id` allows + you to call `vagrant up id` from any directory. + +- `--[no-]destroy-on-error` - Destroy the newly created machine if a fatal, + unexpected error occurs. This will only happen on the first `vagrant up`. + By default this is set. + +- `--[no-]install-provider` - If the requested provider is not installed, + Vagrant will attempt to automatically install it if it can. By default this + is enabled. + +- `--[no-]parallel` - Bring multiple machines up in parallel if the provider + supports it. Please consult the provider documentation to see if this feature + is supported. + +- `--provider x` - Bring the machine up with the given + [provider](/docs/providers/). By default this is "virtualbox". + +- `--[no-]provision` - Force, or prevent, the provisioners to run. + +- `--provision-with x,y,z` - This will only run the given provisioners. For + example, if you have a `:shell` and `:chef_solo` provisioner and run + `vagrant provision --provision-with shell`, only the shell provisioner will + be run. diff --git a/website/pages/docs/cli/upload.html.md b/website/pages/docs/cli/upload.html.md new file mode 100644 index 000000000..2b3782a4e --- /dev/null +++ b/website/pages/docs/cli/upload.html.md @@ -0,0 +1,30 @@ +--- +layout: 'docs' +page_title: 'vagrant upload - Command-Line Interface' +sidebar_current: 'cli-upload' +description: |- + The "vagrant upload" command is used to upload files from the host + to a guest machine. +--- + +# Upload + +**Command: `vagrant upload source [destination] [name|id]`** + +This command uploads files and directories from the host to the guest +machine. + +## Options + +- `destination` - Path on the guest machine to upload file or directory. + +- `source` - Path to file or directory on host to upload to guest machine. + +- `--compress` - Compress the file or directory before uploading to guest machine. + +- `--compression-type type` - Type of compression to use when compressing + file or directory for upload. Defaults to `zip` for Windows guests and + `tgz` for non-Windows guests. Valid values: `tgz`, `zip`. + +- `--temporary` - Create a temporary location on the guest machine and upload + files to that location. diff --git a/website/pages/docs/cli/validate.html.md b/website/pages/docs/cli/validate.html.md new file mode 100644 index 000000000..524a63a09 --- /dev/null +++ b/website/pages/docs/cli/validate.html.md @@ -0,0 +1,24 @@ +--- +layout: 'docs' +page_title: 'vagrant validate - Command-Line Interface' +sidebar_current: 'cli-validate' +description: |- + The "vagrant validate" command is used to validate your Vagrantfile. +--- + +# Validate + +**Command: `vagrant validate`** + +This command validates your [Vagrantfile](/docs/vagrantfile/). + +## Options + +- `--ignore-provider` - Ignores provider config options. + +## Examples + +```sh +$ vagrant validate +Vagrantfile validated successfully. +``` diff --git a/website/pages/docs/cli/version.html.md b/website/pages/docs/cli/version.html.md new file mode 100644 index 000000000..b6346fc21 --- /dev/null +++ b/website/pages/docs/cli/version.html.md @@ -0,0 +1,19 @@ +--- +layout: 'docs' +page_title: 'vagrant version - Command-Line Interface' +sidebar_current: 'cli-version' +description: |- + The "vagrant version" command is used to output the version of Vagrant + currently installed on the system. +--- + +# Version + +**Command: `vagrant version`** + +This command tells you the version of Vagrant you have installed +as well as the latest version of Vagrant that is currently available. + +In order to determine the latest available Vagrant version, this +command must make a network call. If you only want to see the currently +installed version, use `vagrant --version`. diff --git a/website/pages/docs/cli/winrm.html.md b/website/pages/docs/cli/winrm.html.md new file mode 100644 index 000000000..222585d33 --- /dev/null +++ b/website/pages/docs/cli/winrm.html.md @@ -0,0 +1,26 @@ +--- +layout: 'docs' +page_title: 'vagrant winrm - Command-Line Interface' +sidebar_current: 'cli-winrm' +description: |- + The "vagrant winrm" command is used execute commands on the remote + machine via WinRM +--- + +# WinRM + +**Command: `vagrant winrm [name|id]`** + +Executes the provided command(s) on the guest machine using the +WinRM communicator. Commands are provided with the `--command` +option and multiple `--command` flags may be provided for +executing multiple commands. This command requires the guest +machine to be configured with the WinRM communicator. + +## Options + +- `--command COMMAND` - Command to execute. + +- `--elevated` - Run command(s) with elevated credentials. + +- `--shell (cmd|powershell)` - Shell to execute commands. Defaults to `powershell`. diff --git a/website/pages/docs/cli/winrm_config.html.md b/website/pages/docs/cli/winrm_config.html.md new file mode 100644 index 000000000..0b2c0b99b --- /dev/null +++ b/website/pages/docs/cli/winrm_config.html.md @@ -0,0 +1,20 @@ +--- +layout: 'docs' +page_title: 'vagrant winrm-config - Command-Line Interface' +sidebar_current: 'cli-winrm_config' +description: |- + The "vagrant winrm-config" command is used to output the WinRM configuration + used to connect to the guest machine. +--- + +# WinRM Config + +**Command: `vagrant winrm-config [name|id]`** + +This will output the WinRM configuration used for connecting to +the guest machine. It requires that the WinRM communicator is in +use for the guest machine. + +## Options + +- `--host NAME` - Name of the host for the outputted configuration. diff --git a/website/pages/docs/disks/configuration.html.md b/website/pages/docs/disks/configuration.html.md new file mode 100644 index 000000000..6b8da403c --- /dev/null +++ b/website/pages/docs/disks/configuration.html.md @@ -0,0 +1,112 @@ +--- +layout: 'docs' +page_title: 'Vagrant Disks Configuration' +sidebar_current: 'disks-configuration' +description: |- + Documentation of various configuration options for Vagrant Disks +--- + +# Configuration + +Vagrant Disks has several options that allow users to define and attach disks to guests. + +## Disk Options + +- `disk_ext` (string) - Optional argument that defines what kind of file + extension a disk should have. Defaults to `"vdi"` if unspecified. For a list of + supported disk extensions, please check the specific provider being used. +- `file` (string) - Optional argument that defines a path on disk pointing to + the location of a disk file that already exists. +- `name` (string) - Required option to give the disk a name. This name will be + used as the filename when creating the disk. +- `primary` (boolean) - Optional argument that configures a given disk to be the + "primary" disk to manage on the guest. There can only be one `primary` disk per guest. + Defaults to `false` if not specified. +- `provider_config` (hash) - Additional provider specific options for managing a given disk. Please refer to + the provider specific documentation to see any available provider_config options. + + Generally, the disk option accepts two kinds of ways to define a provider config: + + + `providername__diskoption: value` + - The provider name followed by a double underscore, and then the provider specific option for that disk + + `{providername: {diskoption: value}, otherprovidername: {diskoption: value}` + - A hash where the top level key(s) are one or more providers, and each provider keys values are a hash of options and their values. + +- `size` (String) - The size of the disk to create. For example, `"10GB"`. + + **Note:** More specific examples of these can be found under the provider + specific disk page. The `provider_config` option will depend on the provider + you are using. Please read the provider specific documentation for disk + management to learn about what options are available to use. + +## Disk Types + +The disk config currently accepts three kinds of disk types: + +- `disk` (symbol) +- `dvd` (symbol) +- `floppy` (symbol) + +**NOTE:** These types depend on the provider used, and may not yet be functional. Please +refer to the provider specific implementation for more details for what is supported. + +You can set a disk type with the first argument of a disk config in your Vagrantfile: + +```ruby +config.vm.disk :disk, name: "backup", size: "10GB" +config.vm.disk :floppy, name: "cool_files" +``` + +## Provider Author Guide + +If you are a vagrant plugin author who maintains a provider for Vagrant, this short guide will hopefully give some information on how to use the internal disk config object. + +
+ Warning! This guide is still being written as we develop this + new feature for Vagrant. Is something missing, or could this be improved? Please + let us know on GitHub by opening an issue or open a pull request directly. +
+ +All providers must implement the capability `configure_disks`, and `cleanup_disks`. +These methods are responsible for the following: + +- `configure_disks` - Reads in a Vagrant config for defined disks from a Vagrantfile, + and creates and attaches the disks based on the given config +- `cleanup_disks` - Compares the current Vagrant config for defined disks and detaches + any disks that are no longer valid for a guest. + +These methods are called in the builtin Vagrant actions _Disk_ and _CleanupDisks_. +If the provider does not support these capabilities, they will be skipped over and no +disks will be configured. It is the providers job to implement these provider capabilities +and handle the methods required to support disk creation and deletion. Vagrant will +handle parsing and supplying the config object based on what has been defined inside +a users Vagrantfile. + +For a more detailed example of how to use this disk configuration with Vagrant, please +check out how it was implemented using the VirtualBox provider. + +### The disk_meta file + +Both builtin disk actions `configure_disks` and `cleanup_disks` expect to read and +write down a `disk_meta` file inside a machines data dir. This file is specifically +for keeping track of the _last configured state_ for disks in a given provider. +Generally, this file is used as a way for Vagrant to keep track of what disks +are being managed by Vagrant with the provider uses, so that it does not accidentally +delete or manage disks that were configured outside of Vagrants configuration. + +For the VirtualBox provider, Vagrant uses this file to see what disks were configured +on the _last run_ of Vagrant, and compares that to the current configured state for +the Vagrantfile on the _current run_ of Vagrant. It specifically stores each disks +UUID and disk name for use. If it notices a disk that is no longer in the +Vagrantfile, it can be assumed that the disk is no longer valid for that guest, +and cleans up the disk. + +This may not be required for your provider, however with the VirtualBox provider, Vagrant +needs a way to keep track of the defined disks managed by Vagrant and their disk UUIDs +that VirtualBox uses to keep track of these disks. + +### The provider_config hash + +The disk config class supports an optional hash of options called `provider_config`. +This allows the user to define some additional options for a provider to use that +may be non-standard across different providers. diff --git a/website/pages/docs/disks/index.html.md b/website/pages/docs/disks/index.html.md new file mode 100644 index 000000000..6c97549e8 --- /dev/null +++ b/website/pages/docs/disks/index.html.md @@ -0,0 +1,29 @@ +--- +layout: 'docs' +page_title: 'Vagrant Disks' +sidebar_current: 'disks' +description: |- + Introduction to Vagrant Disks +--- + +# Vagrant Disks + +
+ Warning! This feature is experimental and may break or + change in between releases. Use at your own risk. It currently is not officially + supported or functional. Please refer to the providier specific disk documentation + for more information on how to use and enable this feature. +
+ +Vagrant Disks is a feature that allows users to define what mediums should be attached +to their guests, as well as allowing users to resize their primary disk. + +For examples on how to achieve this, among other use cases, please refer to the [usage](/docs/disks/usage.html) +guide for more information! + +For more information about what options are available for configuring disks, see the +[configuration section](/docs/disks/configuration.html). + +## Supported Providers + +Currently, only VirtualBox is supported. Please refer to the [VirtualBox documentation](/docs/disks/virtualbox/index.html) for more information on using disks with the VirtualBox provider! diff --git a/website/pages/docs/disks/usage.html.md b/website/pages/docs/disks/usage.html.md new file mode 100644 index 000000000..6284e3658 --- /dev/null +++ b/website/pages/docs/disks/usage.html.md @@ -0,0 +1,104 @@ +--- +layout: 'docs' +page_title: 'Vagrant Disk Usage' +sidebar_current: 'disks-usage' +description: |- + Various Vagrant Disk examples +--- + +# Basic Usage + +
+ Warning! This feature is experimental and may break or + change in between releases. Use at your own risk. It currently is not officially + supported or functional. + +This feature currently reqiures the experimental flag to be used. To explicitly enable this feature, you can set the experimental flag to: + +``` +VAGRANT_EXPERIMENTAL="disks" +``` + +Please note that `VAGRANT_EXPERIMENTAL` is an environment variable. For more +information about this flag visit the [Experimental docs page](/docs/experimental/) +for more info. Without this flag enabled, any disks defined will not be configured. + +Also note that the examples below use the VirtualBox provider, which is the current +supported providier for this feature. + +
+ +Below are some very simple examples of how to use Vagrant Disks with the VirtualBox provider. + +## Basic Examples + +### Resizing your primary disk + +Sometimes, the primary disk for a guest is not large enough and you will need to +add more space. To resize a disk, you can simply add a config like this below +to expand the size of your guests drive: + +```ruby +config.vm.disk :disk, size: "100GB", primary: true +``` + +Note: the `primary: true` is what tells Vagrant to expand the guests main drive. +Without this option, Vagrant will instead attach a _new_ disk to the guest. + +For example, this Ubuntu guest will now come with 100GB of space, rather than the default: + +```ruby +Vagrant.configure("2") do |config| + config.vm.define "hashicorp" do |h| + h.vm.box = "hashicorp/bionic64" + h.vm.provider :virtualbox + + h.vm.disk :disk, size: "100GB", primary: true + end +end +``` + +It should be noted that due to how VirtualBox functions, it is not possible to shrink +the size of a disk. + +### Attaching new disks + +Vagrant can attach multiple disks to a guest using the VirtualBox provider. An example +of attaching a single disk to a guest with 10 GB of storage can be found below: + +```ruby +Vagrant.configure("2") do |config| + config.vm.define "hashicorp" do |h| + h.vm.box = "hashicorp/bionic64" + h.vm.provider :virtualbox + + h.vm.disk :disk, size: "10GB", name: "extra_storage" + end +end +``` + +Optionally, if you need to attach many disks, you can use Ruby to generate multiple +disks for Vagrant to create and attach to your guest: + +```ruby +Vagrant.configure("2") do |config| + config.vm.define "hashicorp" do |h| + h.vm.box = "hashicorp/bionic64" + h.vm.provider :virtualbox + + (0..3).each do |i| + h.vm.disk :disk, size: "5GB", name: "disk-#{i}" + end + end +end +``` + +Note: Virtualbox only allows for up to 30 disks to be attached to a given SATA Controller, +and this number includes the primary disk! Attempting to configure more than 30 will +result in a Vagrant error. + +### Removing Disks + +If you have removed a disk from your Vagrant config and wish for it to be detached from the guest, +you will need to `vagrant reload` your guest to apply these changes. **NOTE:** Doing so +will also delete the medium from your hard drive. diff --git a/website/pages/docs/disks/virtualbox/common-issues.html.md b/website/pages/docs/disks/virtualbox/common-issues.html.md new file mode 100644 index 000000000..8b5a273d3 --- /dev/null +++ b/website/pages/docs/disks/virtualbox/common-issues.html.md @@ -0,0 +1,42 @@ +--- +layout: 'docs' +page_title: 'Common Issues - Disks VirtualBox Provider' +sidebar_current: 'disks-providers-virtualbox-issues' +description: |- + This page lists some common issues people run into with Vagrant and VirtualBox + as well as solutions for those issues. +--- + +# Common Issues and Troubleshooting + +This page lists some common issues people run into with Vagrant and VirtualBox +as well as solutions for those issues. + +## Are my disks attached? + +A handy way to figure out what disks are attached (or not attached) to your guest +is to open up the VirtualBox GUI and select the guest. When selecting a guest on the GUI, +it should open more information about the guest, including storage information. Here +you should see a list of disks attached to your guest. + +## How many disks can I attach? + +Vagrant attaches all new disks defined to a guests SATA Controller. As of VirtualBox 6.1.x, +SATA Controllers can only support up to **30 disks** per guest. Therefore if you try +to define and attach more than 30, it will result in an error. This number _includes_ +the primary disk for the guest. + +## Resizing VMDK format disks + +VMDK disks cannot be resized in their current state, so Vagrant will automatically +convert these disks to VDI, resize the disk, and convert it back to its original format. +Many Vagrant boxes default to using the VMDK disk format, so resizing disks for +many users will require Vagrant to convert these disks. Generally, this will be transparent +to the user. However if Vagrant crashes or if a user interrupts Vagrant during the +cloning process, there is a chance that you might lose your data. + +## Applying Vagrant disk configuration changes to guests + +Due to how VirtualBox works, you must reload your guest for any disk config changes +to be applied. So if you update your Vagrantfile to update or even remove disks, make +sure to `vagrant reload` your guests for these changes to be applied. diff --git a/website/pages/docs/disks/virtualbox/index.html.md b/website/pages/docs/disks/virtualbox/index.html.md new file mode 100644 index 000000000..562d4b3eb --- /dev/null +++ b/website/pages/docs/disks/virtualbox/index.html.md @@ -0,0 +1,43 @@ +--- +layout: 'docs' +page_title: 'Disks for VirtualBox Provider' +sidebar_current: 'disks-providers-virtualbox' +description: |- + Vagrant comes with support out of the box for VirtualBox, a free, + cross-platform consumer virtualization product. +--- + +# VirtualBox + +
+ Warning! This feature is experimental and may break or + change in between releases. Use at your own risk. It currently is not officially + supported or functional. + +This feature currently reqiures the experimental flag to be used. To explicitly enable this feature, you can set the experimental flag to: + +``` +VAGRANT_EXPERIMENTAL="disks" +``` + +Please note that `VAGRANT_EXPERIMENTAL` is an environment variable. For more +information about this flag visit the [Experimental docs page](/docs/experimental/) +for more info. Without this flag enabled, any disks defined will not be configured. + +
+ +**Vagrant currently only supports VirtualBox version 5.x and newer for configuring and +attaching disks.** + +Because of how VirtualBox handles disk management, a Vagrant guest _must_ be powered +off for any changes to be applied to a guest. If you make a configuration change +with a guests disk, you will need to `vagrant reload` the guest for any changes +to be applied. + +When new disks are defined to be attached to a guest, Vagrant will create and attach +these disks to a guests SATA Controller. It should be noted that up to 30 disks +can be attached to the SATA Controller. + +For more information on how to use VirtualBox to configure disks for a guest, refer +to the [general usage](/docs/disks/usage.html) and [configuration](/docs/disks/configuration.html) +guide for more information. diff --git a/website/pages/docs/disks/virtualbox/usage.html.md b/website/pages/docs/disks/virtualbox/usage.html.md new file mode 100644 index 000000000..b7428511c --- /dev/null +++ b/website/pages/docs/disks/virtualbox/usage.html.md @@ -0,0 +1,35 @@ +--- +layout: 'docs' +page_title: 'Usage - Disks VirtualBox Provider' +sidebar_current: 'disks-providers-virtualbox-usage' +description: |- + The Vagrant VirtualBox provider is used just like any other provider. Please + read the general basic usage page for providers. +--- + +# Usage + +
+ Warning! This feature is experimental and may break or + change in between releases. Use at your own risk. It currently is not officially + supported or functional. + +This feature currently reqiures the experimental flag to be used. To explicitly enable this feature, you can set the experimental flag to: + +``` +VAGRANT_EXPERIMENTAL="disks" +``` + +Please note that `VAGRANT_EXPERIMENTAL` is an environment variable. For more +information about this flag visit the [Experimental docs page](/docs/experimental/) +for more info. Without this flag enabled, any disks defined will not be configured. + +
+ +For examples of how to use the disk feature with VirtualBox, please refer to the +[general disk usage guide](/docs/disks/usage.html) for more examples. + +## provider_config options + +Currently, there are no additional options supported for the `provider_config` option. +This page will be updated with any valid options as they become supported. diff --git a/website/pages/docs/docker/basics.html.md b/website/pages/docs/docker/basics.html.md new file mode 100644 index 000000000..f0c9d914f --- /dev/null +++ b/website/pages/docs/docker/basics.html.md @@ -0,0 +1,128 @@ +--- +layout: 'docs' +page_title: 'Basic Usage - Docker Provider' +sidebar_current: 'providers-docker-basics' +description: |- + The Docker provider in Vagrant behaves just like any other provider. + If you are familiar with Vagrant already, then using the Docker provider + should be intuitive and simple. +--- + +# Docker Basic Usage + +The Docker provider in Vagrant behaves just like any other provider. +If you are familiar with Vagrant already, then using the Docker provider +should be intuitive and simple. + +The Docker provider _does not_ require a `config.vm.box` setting. Since +the "base image" for a Docker container is pulled from the +Docker Index or +built from a Dockerfile, the box does not +add much value, and is optional for this provider. + +## Docker Images + +The first method that Vagrant can use to source a Docker container +is via an image. This image can be from any Docker registry. An +example is shown below: + +```ruby +Vagrant.configure("2") do |config| + config.vm.provider "docker" do |d| + d.image = "foo/bar" + end +end +``` + +When `vagrant up --provider=docker` is run, this will bring up the +image `foo/bar`. + +This is useful for extra components of your application that it might +depend on: databases, queues, etc. Typically, the primary application +you are working on is built with a Dockerfile, or via a container with +SSH. + +## Dockerfiles + +Vagrant can also automatically build and run images based on a local +Dockerfile. This is useful for iterating on an application locally +that is built into an image later. An example is shown below: + +```ruby +Vagrant.configure("2") do |config| + config.vm.provider "docker" do |d| + d.build_dir = "." + end +end +``` + +The above configuration will look for a `Dockerfile` in the same +directory as the Vagrantfile. When `vagrant up --provider=docker` is run, Vagrant +automatically builds that Dockerfile and starts a container +based on that Dockerfile. + +The Dockerfile is rebuilt when `vagrant reload` is called. + +## Synced Folders and Networking + +When using Docker, Vagrant automatically converts synced folders +and networking options into Docker volumes and forwarded ports. +You do not have to use the Docker-specific configurations to do this. +This helps keep your Vagrantfile similar to how it has always looked. + +The Docker provider does not support specifying options for `owner` or `group` +on folders synced with a docker container. + +### Volume Consistency + +Docker's [volume consistency](https://docs.docker.com/v17.09/engine/admin/volumes/bind-mounts/) setting can be specified using the `docker_consistency` option when defining a synced folder. This can +[greatly improve performance on macOS](https://docs.docker.com/docker-for-mac/osxfs-caching). An example is shown using the `cached` and `delegated` settings: + +```ruby +config.vm.synced_folder "/host/dir1", "/guest/dir1", docker_consistency: "cached" +config.vm.synced_folder "/host/dir2", "/guest/dir2", docker_consistency: "delegated" +``` + +## Host VM + +If the system cannot run Linux containers natively, Vagrant automatically spins +up a "host VM" to run Docker. This allows your Docker-based Vagrant environments +to remain portable, without inconsistencies depending on the platform they are +running on. + +Vagrant will spin up a single instance of a host VM and run multiple +containers on this one VM. This means that with the Docker provider, +you only have the overhead of one virtual machine, and only if it is +absolutely necessary. + +By default, the host VM Vagrant spins up is +[backed by boot2docker](https://github.com/hashicorp/vagrant/blob/master/plugins/providers/docker/hostmachine/Vagrantfile), +because it launches quickly and uses little resources. But the host VM +can be customized to point to _any_ Vagrantfile. This allows the host VM +to more closely match production by running a VM running Ubuntu, RHEL, +etc. It can run any operating system supported by Vagrant. + +
+ Synced folder note: Vagrant will attempt to use the + "best" synced folder implementation it can. For boot2docker, this is + often rsync. In this case, make sure you have rsync installed on your + host machine. Vagrant will give you a human-friendly error message if + it is not. +
+ +An example of changing the host VM is shown below. Remember that this +is optional, and Vagrant will spin up a default host VM if it is not +specified: + +```ruby +Vagrant.configure("2") do |config| + config.vm.provider "docker" do |d| + d.vagrant_vagrantfile = "../path/to/Vagrantfile" + end +end +``` + +The host VM will be spun up at the first `vagrant up` where the provider +is Docker. To control this host VM, use the +[global-status command](/docs/cli/global-status.html) +along with global control. diff --git a/website/pages/docs/docker/boxes.html.md b/website/pages/docs/docker/boxes.html.md new file mode 100644 index 000000000..c215210a2 --- /dev/null +++ b/website/pages/docs/docker/boxes.html.md @@ -0,0 +1,20 @@ +--- +layout: 'docs' +page_title: 'Boxes - Docker Provider' +sidebar_current: 'providers-docker-boxes' +description: |- + The Docker provider does not require a Vagrant box. The "config.vm.box" + setting is completely optional. +--- + +# Docker Boxes + +The Docker provider does not require a Vagrant box. The `config.vm.box` +setting is completely optional. + +A box can still be used and specified, however, to provide defaults. +Because the `Vagrantfile` within a box is loaded as part of the +configuration loading sequence, it can be used to configure the +foundation of a development environment. + +In general, however, you will not need a box with the Docker provider. diff --git a/website/pages/docs/docker/commands.html.md b/website/pages/docs/docker/commands.html.md new file mode 100644 index 000000000..b0f328832 --- /dev/null +++ b/website/pages/docs/docker/commands.html.md @@ -0,0 +1,113 @@ +--- +layout: 'docs' +page_title: 'Commands - Docker Provider' +sidebar_current: 'providers-docker-commands' +description: |- + The Docker provider exposes some additional Vagrant commands that are + useful for interacting with Docker containers. This helps with your + workflow on top of Vagrant so that you have full access to Docker + underneath. +--- + +# Docker Commands + +The Docker provider exposes some additional Vagrant commands that are +useful for interacting with Docker containers. This helps with your +workflow on top of Vagrant so that you have full access to Docker +underneath. + +### docker-exec + +`vagrant docker-exec` can be used to run one-off commands against +a Docker container that is currently running. If the container is not running, +an error will be returned. + +```sh +$ vagrant docker-exec app -- rake db:migrate +``` + +The above would run `rake db:migrate` in the context of an `app` container. + +Note that the "name" corresponds to the name of the VM, **not** the name of the +Docker container. Consider the following Vagrantfile: + +```ruby +Vagrant.configure(2) do |config| + config.vm.provider "docker" do |d| + d.image = "consul" + end +end +``` + +This Vagrantfile will start the official Docker Consul image. However, the +associated Vagrant command to `docker-exec` into this instance is: + +```sh +$ vagrant docker-exec -it -- /bin/sh +``` + +In particular, the command is actually: + +```sh +$ vagrant docker-exec default -it -- /bin/sh +``` + +Because "default" is the default name of the first defined VM. In a +multi-machine Vagrant setup as shown below, the "name" attribute corresponds +to the name of the VM, **not** the name of the container: + +```ruby +Vagrant.configure do |config| + config.vm.define "web" do + config.vm.provider "docker" do |d| + d.image = "nginx" + end + end + + config.vm.define "consul" do + config.vm.provider "docker" do |d| + d.image = "consul" + end + end +end +``` + +The following command is invalid: + +```sh +# Not valid +$ vagrant docker-exec -it nginx -- /bin/sh +``` + +This is because the "name" of the VM is "web", so the command is actually: + +```sh +$ vagrant docker-exec -it web -- /bin/sh +``` + +For this reason, it is recommended that you name the VM the same as the +container. In the above example, it is unambiguous that the command to enter +the Consul container is: + +```sh +$ vagrant docker-exec -it consul -- /bin/sh +``` + +### docker-logs + +`vagrant docker-logs` can be used to see the logs of a running container. +Because most Docker containers are single-process, this is used to see +the logs of that one process. Additionally, the logs can be tailed. + +### docker-run + +`vagrant docker-run` can be used to run one-off commands against +a Docker container. The one-off Docker container that is started shares +all the volumes, links, etc. of the original Docker container. An +example is shown below: + +```sh +$ vagrant docker-run app -- rake db:migrate +``` + +The above would run `rake db:migrate` in the context of an `app` container. diff --git a/website/pages/docs/docker/configuration.html.md b/website/pages/docs/docker/configuration.html.md new file mode 100644 index 000000000..cc5e8651e --- /dev/null +++ b/website/pages/docs/docker/configuration.html.md @@ -0,0 +1,123 @@ +--- +layout: 'docs' +page_title: 'Configuration- Docker Provider' +sidebar_current: 'providers-docker-configuration' +description: |- + The Docker provider has some provider-specific configuration options + you may set. A complete reference is shown on this page. +--- + +# Docker Configuration + +The Docker provider has some provider-specific configuration options +you may set. A complete reference is shown below. + +### Required + +One of the following settings is required when using the Docker provider: + +- `build_dir` (string) - The path to a directory containing a Dockerfile. + +- `image` (string) - The image to launch, specified by the image ID or a name + such as `ubuntu:12.04`. + +- `git_repo` (string) - The URL of a git repository to build the image from. + Supports pulling specific tags, branches and revision, consult the + [docker documentation](https://docs.docker.com/engine/reference/commandline/build/#/git-repositories) + for more information. + +### Optional + +General settings: + +- `build_args` (array of strings) - Extra arguments to pass to + `docker build` when `build_dir` is in use. + +- `cmd` (array of strings) - Custom command to run on the container. + Example: `["ls", "/app"]`. + +- `compose` (boolean) - If true, Vagrant will use `docker-compose` to + manage the lifecycle and configuration of containers. This defaults + to false. + +- `compose_configuration` (Hash) - Configuration values used for populating + the `docker-compose.yml` file. The value of this Hash is directly merged + and written to the `docker-compose.yml` file allowing customization of + non-services items like networks and volumes. + +- `create_args` (array of strings) - Additional arguments to pass to + `docker run` when the container is started. This can be used to set + parameters that are not exposed via the Vagrantfile. + +- `dockerfile` (string) - Name of the Dockerfile in the build directory. + This defaults to "Dockerfile" + +- `env` (hash) - Environmental variables to expose into the container. + +- `expose` (array of integers) - Ports to expose from the container + but not to the host machine. Useful for links. + +- `link` (method, string argument) - Link this container to another + by name. The argument should be in the format of `(name:alias)`. + Example: `docker.link("db:db")`. Note, if you are linking to + another container in the same Vagrantfile, make sure you call + `vagrant up` with the `--no-parallel` flag. + +- `force_host_vm` (boolean) - If true, then a host VM will be spun up + even if the computer running Vagrant supports Linux containers. This + is useful to enforce a consistent environment to run Docker. This value + defaults to "false" on Linux, Mac, and Windows hosts and defaults to "true" + on other hosts. Users on other hosts who choose to use a different Docker + provider or opt-in to the native Docker builds can explicitly set this + value to false to disable the behavior. + +- `has_ssh` (boolean) - If true, then Vagrant will support SSH with + the container. This allows `vagrant ssh` to work, provisioners, etc. + This defaults to false. + +- `host_vm_build_dir_options` (hash) - Synced folder options for the + `build_dir`, since the build directory is synced using a synced folder + if a host VM is in use. + +- `name` (string) - Name of the container. Note that this has to be unique + across all containers on the host VM. By default Vagrant will generate + some random name. + +- `pull` (bool) - If true, the image will be pulled on every `up` and + `reload`. Defaults to false. + +- `ports` (array of strings) - Ports to expose from the container to the + host. These should be in the format of `host:container`. + +- `remains_running` (boolean) - If true, Vagrant expects this container + to remain running and will make sure that it does for a certain amount + of time. If false, then Vagrant expects that this container will + automatically stop at some point, and will not error if it sees it do that. + +- `stop_timeout` (integer) - The amount of time to wait when stopping + a container before sending a SIGTERM to the process. + +- `vagrant_machine` (string) - The name of the Vagrant machine in the + `vagrant_vagrantfile` to use as the host machine. This defaults to + "default". + +- `vagrant_vagrantfile` (string) - Path to a Vagrantfile that contains + the `vagrant_machine` to use as the host VM if needed. + +- `volumes` (array of strings) - List of directories to mount as + volumes into the container. These directories must exist in the + host where Docker is running. If you want to sync folders from the + host Vagrant is running, just use synced folders. + +Below, we have settings related to auth. If these are set, then Vagrant +will `docker login` prior to starting containers, allowing you to pull +images from private repositories. + +- `email` (string) - Email address for logging in. + +- `username` (string) - Username for logging in. + +- `password` (string) - Password for logging in. + +- `auth_server` (string) - The server to use for authentication. If not + set, the Docker Hub will be used. diff --git a/website/pages/docs/docker/index.html.md b/website/pages/docs/docker/index.html.md new file mode 100644 index 000000000..3369f7bfc --- /dev/null +++ b/website/pages/docs/docker/index.html.md @@ -0,0 +1,27 @@ +--- +layout: 'docs' +page_title: 'Docker Provider' +sidebar_current: 'providers-docker' +description: |- + Vagrant comes with support out of the box for + using Docker as a provider. This allows for your development environments + to be backed by Docker containers rather than virtual machines. Additionally, + it provides for a good workflow for developing Dockerfiles. +--- + +# Docker + +Vagrant comes with support out of the box for +using Docker as a provider. This allows for your development environments +to be backed by Docker containers rather than virtual machines. Additionally, +it provides for a good workflow for developing Dockerfiles. + +
+ Warning: Docker knowledge assumed. We assume that + you know what Docker is and that you are comfortable with the basics + of Docker. If not, we recommend starting with another provider such + as VirtualBox. +
+ +Use the navigation to the left to find a specific Docker topic +to read more about. diff --git a/website/pages/docs/docker/networking.html.md b/website/pages/docs/docker/networking.html.md new file mode 100644 index 000000000..47fea6d55 --- /dev/null +++ b/website/pages/docs/docker/networking.html.md @@ -0,0 +1,290 @@ +--- +layout: 'docs' +page_title: 'Networking - Docker Provider' +sidebar_current: 'providers-docker-networking' +description: |- + The Vagrant Docker provider supports using the private network using the + `docker network` commands. +--- + +# Networking + +Vagrant uses the `docker network` command under the hood to create and manage +networks for containers. Vagrant will do its best to create and manage networks +for any containers configured inside the Vagrantfile. Each docker network is grouped +by the subnet used for a requested ip address. + +For each newly unique network, Vagrant will run the `docker network create` subcommand +with the provided options from the network config inside your Vagrantfile. If multiple +networks share the same subnet, Vagrant will reuse that existing network for multiple +containers. Once these networks have been created, Vagrant will attach these +networks to the requested containers using the `docker network connect` for each +network. + +Vagrant names the networks inside docker as `vagrant_network` or `vagrant_network_` +where `` is the subnet for the network if defined by the user. An +example of these networks is shown later in this page. If no subnet is requested +for the network, Vagrant will connect the `vagrant_network` to the container. + +When destroying containers through Vagrant, Vagrant will clean up the network if +there are no more containers using the network. + +## Docker Network Options + +Most of the options work similar to other Vagrant providers. Defining either an +ip or using `type: 'dhcp'` will give you a network on your container. + +```ruby +docker.vm.network :private_network, type: "dhcp" +docker.vm.network :private_network, ip: "172.20.128.2" +``` + +If you want to set something specific with a new network you can use scoped options +which align with the command line flags for the [docker network create](https://docs.docker.com/engine/reference/commandline/network_create/) +command. If there are any specific options you want to enable from the `docker network create` +command, you can specify them like this: + +```ruby +docker.vm.network :private_network, type: "dhcp", docker_network__internal: true +``` + +This will enable the `internal` option for the network when created with `docker network create`. + +Where `option` corresponds to the given flag that will be provided to the `docker network create` +command. Similarly, if there is a value you wish to enable when connecting a container +to a given network, you can use the following value in your network config: + +```ruby +docker_connect__option: "value" +``` + +When the docker provider creates a new network a netmask is required. If the netmask +is not provided, Vagrant will default to a `/24` for IPv4 and `/64` for IPv6. To provide +a different mask, set it using the `netmask` option: + +```ruby +docker.vm.network :private_network, ip: "172.20.128.2", netmask: 16 +``` + +For networks which set the type to "dhcp", it is also possible to specify a specific +subnet for the network connection. This allows containers to connect to networks other +than the default `vagrant_network` network. The docker provider supports specifying +the desired subnet in two ways. The first is by using the `ip` and `netmask` options: + +```ruby +docker.vm.network :private_network, type: "dhcp", ip: "172.20.128.0", netmask: 24 +``` + +The second is by using the `subnet` option: + +```ruby +docker.vm.network :private_network, type: "dhcp", subnet: "172.20.128.0/24" +``` + +### Public Networks + +The Vagrant docker provider also supports defining public networks. The easiest way +to define a public network is by setting the `type` option to "dhcp": + +```ruby +docker.vm.network :public_network, type: "dhcp" +``` + +A bridge interface is required when setting up a public network. When no bridge +device name is provided, Vagrant will prompt for the appropriate device to use. This +can also be set using the `bridge` option: + +```ruby +docker.vm.network :public_network, type: "dhcp", bridge: "eth0" +``` + +The `bridge` option also supports a list of interfaces which can be used for +setting up the network. Vagrant will inspect the defined interfaces and use +the first active interface when setting up the network: + +```ruby +docker.vm.network :public_network, type: "dhcp", bridge: ["eth0", "wlan0"] +``` + +The available IP range for the bridge interface must be known when setting up +the docker network. Even though a DHCP service may be available on the public +network, docker will manage IP addresses provided to containers. This means +that the subnet provided when defining the available IP range for the network +should not be included within the subnet managed by the DHCP service. Vagrant +will prompt for the available IP range information, however, it can also be +provided in the Vagrantfile using the `docker_network__ip_range` option: + +```ruby +docker.vm.network :public_network, type: "dhcp", bridge: "eth0", docker_network__ip_range: "192.168.1.252/30" +``` + +Finally, the gateway for the interface is required during setup. The docker +provider will default the gateway address to the first address available for +the subnet of the bridge device. Vagrant will prompt for confirmation to use +the default address. The address can also be manually set in the Vagrantfile +using the `docker_network__gateway` option: + +```ruby +docker.vm.network :public_network, type: "dhcp", bridge: "eth0", docker_network__gateway: "192.168.1.2" +``` + +More examples are shared below which demonstrate creating a few common network +interfaces. + +## Docker Network Example + +The following Vagrantfile will generate these networks for a container: + +1. A IPv4 IP address assigned by DHCP +2. A IPv4 IP address 172.20.128.2 on a network with subnet 172.20.0.0/16 +3. A IPv6 IP address assigned by DHCP on subnet 2a02:6b8:b010:9020:1::/80 + +```ruby +Vagrant.configure("2") do |config| + config.vm.define "docker" do |docker| + docker.vm.network :private_network, type: "dhcp", docker_network__internal: true + docker.vm.network :private_network, + ip: "172.20.128.2", netmask: "16" + docker.vm.network :private_network, type: "dhcp", subnet: "2a02:6b8:b010:9020:1::/80" + docker.vm.provider "docker" do |d| + d.build_dir = "docker_build_dir" + end + end +end +``` + +You can test that your container has the proper configured networks by looking +at the result of running `ip addr`, for example: + +``` +brian@localghost:vagrant-sandbox % docker ps ±[●][master] +CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES +370f4e5d2217 196a06ef12f5 "tail -f /dev/null" 5 seconds ago Up 3 seconds 80/tcp, 443/tcp vagrant-sandbox_docker-1_1551810440 +brian@localghost:vagrant-sandbox % docker exec 370f4e5d2217 ip addr ±[●][master] +1: lo: mtu 65536 qdisc noqueue state UNKNOWN group default qlen 1000 + link/loopback 00:00:00:00:00:00 brd 00:00:00:00:00:00 + inet 127.0.0.1/8 scope host lo + valid_lft forever preferred_lft forever + inet6 ::1/128 scope host + valid_lft forever preferred_lft forever +24: eth0@if25: mtu 1500 qdisc noqueue state UP group default + link/ether 02:42:ac:11:00:03 brd ff:ff:ff:ff:ff:ff link-netnsid 0 + inet 172.17.0.3/16 brd 172.17.255.255 scope global eth0 + valid_lft forever preferred_lft forever +27: eth1@if28: mtu 1500 qdisc noqueue state UP group default + link/ether 02:42:ac:13:00:02 brd ff:ff:ff:ff:ff:ff link-netnsid 0 + inet 172.19.0.2/16 brd 172.19.255.255 scope global eth1 + valid_lft forever preferred_lft forever +30: eth2@if31: mtu 1500 qdisc noqueue state UP group default + link/ether 02:42:ac:14:80:02 brd ff:ff:ff:ff:ff:ff link-netnsid 0 + inet 172.20.128.2/16 brd 172.20.255.255 scope global eth2 + valid_lft forever preferred_lft forever +33: eth3@if34: mtu 1500 qdisc noqueue state UP group default + link/ether 02:42:ac:15:00:02 brd ff:ff:ff:ff:ff:ff link-netnsid 0 + inet 172.21.0.2/16 brd 172.21.255.255 scope global eth3 + valid_lft forever preferred_lft forever + inet6 2a02:6b8:b010:9020:1::2/80 scope global nodad + valid_lft forever preferred_lft forever + inet6 fe80::42:acff:fe15:2/64 scope link + valid_lft forever preferred_lft forever +``` + +You can also connect your containers to a docker network that was created outside +of Vagrant: + +``` +$ docker network create my-custom-network --subnet=172.20.0.0/16 +``` + +```ruby +Vagrant.configure("2") do |config| + config.vm.define "docker" do |docker| + docker.vm.network :private_network, type: "dhcp", name: "my-custom-network" + docker.vm.provider "docker" do |d| + d.build_dir = "docker_build_dir" + end + end +end +``` + +Vagrant will not delete or modify these outside networks when deleting the container, however. + +## Useful Debugging Tips + +The `docker network` command provides some helpful insights to what might be going +on with the networks Vagrant creates. For example, if you want to know what networks +you currently have running on your machine, you can run the `docker network ls` command: + +``` +brian@localghost:vagrant-sandbox % docker network ls ±[●][master] +NETWORK ID NAME DRIVER SCOPE +a2bfc26bd876 bridge bridge local +2a2845e77550 host host local +f36682aeba68 none null local +00d4986c7dc2 vagrant_network bridge local +d02420ff4c39 vagrant_network_2a02:6b8:b010:9020:1::/80 bridge local +799ae9dbaf98 vagrant_network_172.20.0.0/16 bridge local +``` + +You can also inspect any network for more information: + +``` +brian@localghost:vagrant-sandbox % docker network inspect vagrant_network ±[●][master] +[ + { + "Name": "vagrant_network", + "Id": "00d4986c7dc2ed7bf1961989ae1cfe98504c711f9de2f547e5dfffe2bb819fc2", + "Created": "2019-03-05T10:27:21.558824922-08:00", + "Scope": "local", + "Driver": "bridge", + "EnableIPv6": false, + "IPAM": { + "Driver": "default", + "Options": {}, + "Config": [ + { + "Subnet": "172.19.0.0/16", + "Gateway": "172.19.0.1" + } + ] + }, + "Internal": false, + "Attachable": false, + "Ingress": false, + "ConfigFrom": { + "Network": "" + }, + "ConfigOnly": false, + "Containers": { + "370f4e5d2217e698b16376583fbf051dd34018e5fd18958b604017def92fea63": { + "Name": "vagrant-sandbox_docker-1_1551810440", + "EndpointID": "166b7ca8960a9f20a150bb75a68d07e27e674781ed9f916e9aa58c8bc2539a61", + "MacAddress": "02:42:ac:13:00:02", + "IPv4Address": "172.19.0.2/16", + "IPv6Address": "" + } + }, + "Options": {}, + "Labels": {} + } +] +``` + +## Caveats + +For now, Vagrant only looks at the subnet when figuring out if it should create +a new network for a guest container. If you bring up a container with a network, +and then change or add some new options (but leave the subnet the same), it will +not apply those changes or create a new network. + +Because the `--link` flag for the `docker network connect` command is considered +legacy, Vagrant does not support that option when creating containers and connecting +networks. + +## More Information + +For more information on how docker manages its networks, please refer to their +documentation: + +- https://docs.docker.com/network/ +- https://docs.docker.com/engine/reference/commandline/network/ diff --git a/website/pages/docs/experimental/index.html.md b/website/pages/docs/experimental/index.html.md new file mode 100644 index 000000000..2c73f74b4 --- /dev/null +++ b/website/pages/docs/experimental/index.html.md @@ -0,0 +1,56 @@ +--- +layout: 'docs' +page_title: 'Vagrant Experimental Feature Flag' +sidebar_current: 'experimental' +description: |- + Introduction to Vagrants Experimental Feature Flag +--- + +# Experimental Feature Flag + +Some features that aren't ready for release can be enabled through this feature +flag. There are a couple of different ways of going about enabling these features. +It is also worth noting that Vagrant will not validate the existence of a feature +flag. + +For example if you are on Linux or Mac, and you wish to enable every single experimental feature, you can set the flag +to "on" by setting it to `1`: + +```shell +export VAGRANT_EXPERIMENTAL="1" +``` + +You can also enable some or many features if there are specific ones you would like, +but don't want every single feature enabled: + +```shell +# Only enables feature_one +export VAGRANT_EXPERIMENTAL="feature_one" +``` + +```shell +# Enables both feature_one and feature_two +export VAGRANT_EXPERIMENTAL="feature_one,feature_two" +``` + +## Valid experimental features + +
+ Advanced topic! This is an advanced topic for use only if + you want to use new Vagrant features. If you are just getting + started with Vagrant, you may safely skip this section. +
+ +This is a list of all the valid experimental features that Vagrant recognizes: + +### `typed_triggers` + +Enabling this feature allows triggers to recognize and execute `:type` triggers. +More information about how these should be used can be found on the [trigger documentation page](/docs/triggers/configuration.html#trigger-types) + +### `dependency_provisioners` + +Enabling this feature allows all provisioners to specify `before` and `after` +options. These options allow provisioners to be configured to run before or after +any given "root" provisioner. more information about these options can be found +on the [base provisioner documentation page](/docs/provisioning/basic_usage.html) diff --git a/website/pages/docs/hyperv/boxes.html.md b/website/pages/docs/hyperv/boxes.html.md new file mode 100644 index 000000000..053e2af0b --- /dev/null +++ b/website/pages/docs/hyperv/boxes.html.md @@ -0,0 +1,103 @@ +--- +layout: 'docs' +page_title: 'Creating a Base Box - Hyper-V Provider' +sidebar_current: 'providers-hyperv-boxes' +description: |- + As with every Vagrant provider, the Vagrant Hyper-V provider has a custom box + format that affects how base boxes are made. +--- + +# Creating a Base Box + +As with [every Vagrant provider](/docs/providers/basic_usage.html), the +Vagrant Hyper-V provider has a custom box format that affects how base boxes are made. + +Prior to reading this, you should read the +[general guide to creating base boxes](/docs/boxes/base.html). Actually, +it would probably be most useful to keep this open in a separate tab +as you may be referencing it frequently while creating a base box. That +page contains important information about common software to install +on the box. + +Additionally, it is helpful to understand the +[basics of the box file format](/docs/boxes/format.html). + +
+ Advanced topic! This is a reasonably advanced topic that + a beginning user of Vagrant does not need to understand. If you are + just getting started with Vagrant, skip this and use an available + box. If you are an experienced user of Vagrant and want to create + your own custom boxes, this is for you. +
+ +## Additional Software + +In addition to the software that should be installed based on the +[general guide to creating base boxes](/docs/boxes/base.html), +Hyper-V base boxes require some additional software. + +### Hyper-V Kernel Modules + +You will need to install Hyper-V kernel modules. While this improves performance, +it also enables necessary features such as reporting its IP address so that +Vagrant can access it. + +You can verify Hyper-V kernel modules are properly installed by +running `lsmod` on Linux machines and looking for modules prefixed with +`hv_`. Additionally, you will need to verify that the "Network" tab for your +virtual machine in the Hyper-V manager is reporting an IP address. If it +is not reporting an IP address, Vagrant will not be able to access it. + +For most newer Linux distributions, the Hyper-V modules will be available +out of the box. + +Ubuntu 12.04 requires some special steps to make networking work. These +are reproduced here in case similar steps are needed with other distributions. +Without these commands, Ubuntu 12.04 will not report an IP address to +Hyper-V: + +``` +$ sudo apt-get install linux-tools-3.11.0-15-generic +$ sudo apt-get install hv-kvp-daemon-init +$ sudo cp /usr/lib/linux-tools/3.11.0-15/hv_* /usr/sbin/ +``` + +## Packaging the Box + +To package a Hyper-V box, export the virtual machine from the +Hyper-V Manager using the "Export" feature. This will create a directory +with a structure similar to the following: + +``` +. +|-- Snapshots +|-- Virtual Hard drives +|-- Virtual Machines +``` + +Delete the "Snapshots" folder. It is of no use to the Vagrant Hyper-V +provider and can only add to the size of the box if there are snapshots +in that folder. + +Then, create the "metadata.json" file necessary for the box, as documented +in [basics of the box file format](/docs/boxes/format.html). The proper +provider value to use for the metadata is "hyperv". + +Finally, create an archive of those contents (but _not_ the parent folder) +using a tool such as `tar`: + +``` +$ tar cvzf ~/custom.box ./* +``` + +A common mistake is to also package the parent folder by accident. Vagrant +will not work in this case. To verify you've packaged it properly, add the +box to Vagrant and try to bring up the machine. + +## Additional Help + +There is also some less structured help available from the experience of +other users. These are not official documentation but if you are running +into trouble they may help you: + +- [Ubuntu 14.04.2 without secure boot](https://github.com/hashicorp/vagrant/issues/5419#issuecomment-86235427) diff --git a/website/pages/docs/hyperv/configuration.html.md b/website/pages/docs/hyperv/configuration.html.md new file mode 100644 index 000000000..2683f12ec --- /dev/null +++ b/website/pages/docs/hyperv/configuration.html.md @@ -0,0 +1,57 @@ +--- +layout: 'docs' +page_title: 'Configuration- Hyper-V Provider' +sidebar_current: 'providers-hyperv-configuration' +description: |- + The Vagrant Hyper-V provider has some provider-specific configuration options + you may set. +--- + +# Configuration + +The Vagrant Hyper-V provider has some provider-specific configuration options +you may set. A complete reference is shown below: + +- `auto_start_action` (Nothing, StartIfRunning, Start) - Automatic start action for VM on host startup. Default: Nothing. +- `auto_stop_action` (ShutDown, TurnOff, Save) - Automatic stop action for VM on host shutdown. Default: ShutDown. +- `cpus` (integer) - Number of virtual CPUs allocated to VM at startup. +- `differencing_disk` (boolean) - **Deprecated** Use differencing disk instead of cloning entire VHD (use `linked_clone` instead) Default: false. +- `enable_virtualization_extensions` (boolean) - Enable virtualization extensions for the virtual CPUs. Default: false +- `enable_checkpoints` (boolean) Enable checkpoints of the VM. Default: true +- `enable_automatic_checkpoints` (boolean) Enable automatic checkpoints of the VM. Default: false +- `ip_address_timeout` (integer) - Number of seconds to wait for the VM to report an IP address. Default: 120. +- `linked_clone` (boolean) - Use differencing disk instead of cloning entire VHD. Default: false +- `mac` (string) - MAC address for the guest network interface +- `maxmemory` (integer) - Maximum number of megabytes allowed to be allocated for the VM. When set Dynamic Memory Allocation will be enabled. +- `memory` (integer) - Number of megabytes allocated to VM at startup. If `maxmemory` is set, this will be amount of memory allocated at startup. +- `vlan_id` (integer) - VLAN ID for the guest network interface. +- `vmname` (string) - Name of virtual machine as shown in Hyper-V manager. Default: Generated name. +- `vm_integration_services` (Hash) - Hash to set the state of integration services. (Note: Unknown key values will be passed directly.) + - `guest_service_interface` (boolean) + - `heartbeat` (boolean) + - `key_value_pair_exchange` (boolean) + - `shutdown` (boolean) + - `time_synchronization` (boolean) + - `vss` (boolean) + +## VM Integration Services + +The `vm_integration_services` configuration option consists of a simple Hash. The key values are the +names of VM integration services to enable or disable for the VM. Vagrant includes an internal +mapping of known services which allows them to be provided in a "snake case" format. When a provided +key is unknown, the key value is used "as-is" without any modifications. + +For example, if a new `CustomVMSRV` VM integration service was added and Vagrant is not aware of this +new service name, it can be provided as the key value explicitly: + +```ruby +config.vm.provider "hyperv" do |h| + h.vm_integration_services = { + guest_service_interface: true, + CustomVMSRV: true + } +end +``` + +This example would enable the `GuestServiceInterface` (which Vagrant is aware) and `CustomVMSRV` (which +Vagrant is _not_ aware) VM integration services. diff --git a/website/pages/docs/hyperv/index.html.md b/website/pages/docs/hyperv/index.html.md new file mode 100644 index 000000000..b8d22f962 --- /dev/null +++ b/website/pages/docs/hyperv/index.html.md @@ -0,0 +1,37 @@ +--- +layout: 'docs' +page_title: 'Hyper-V Provider' +sidebar_current: 'providers-hyperv' +description: |- + Vagrant comes with support out of the box for Hyper-V, a native hypervisor + written by Microsoft. Hyper-V is available by default for almost all + Windows 8.1 and later installs. +--- + +# Hyper-V + +Vagrant comes with support out of the box for [Hyper-V](https://en.wikipedia.org/wiki/Hyper-V), +a native hypervisor written by Microsoft. Hyper-V is available by default for +almost all Windows 8.1 and later installs. + +The Hyper-V provider is compatible with Windows 8.1 and later only. Prior versions +of Hyper-V do not include the necessary APIs for Vagrant to work. + +Hyper-V must be enabled prior to using the provider. Most Windows installations +will not have Hyper-V enabled by default. Hyper-V is available by default for +almost all Windows Enterprise, Professional, or Education 8.1 and later installs. +To enable Hyper-V, go to "Programs and Features", click on "Turn Windows +features on or off" and check the box next to "Hyper-V". Or install via +PowerShell with: + +Enable-WindowsOptionalFeature -Online -FeatureName Microsoft-Hyper-V -All + +See official documentation [here](https://docs.microsoft.com/en-us/virtualization/hyper-v-on-windows/quick-start/enable-hyper-v). + +
+ Warning: Enabling Hyper-V will cause VirtualBox, VMware, + and any other virtualization technology to no longer work. See + this blog post + for an easy way to create a boot entry to boot Windows without Hyper-V + enabled, if there will be times you will need other hypervisors. +
diff --git a/website/pages/docs/hyperv/limitations.html.md b/website/pages/docs/hyperv/limitations.html.md new file mode 100644 index 000000000..ee8f71b8d --- /dev/null +++ b/website/pages/docs/hyperv/limitations.html.md @@ -0,0 +1,35 @@ +--- +layout: 'docs' +page_title: 'Limitations - Hyper-V Provider' +sidebar_current: 'providers-hyperv-limitations' +description: |- + The Hyper-V provider works in almost every way like the VirtualBox + or VMware provider would, but has some limitations that are inherent to + Hyper-V itself. +--- + +# Limitations + +The Vagrant Hyper-V provider works in almost every way like the VirtualBox +or VMware provider would, but has some limitations that are inherent to +Hyper-V itself. + +## Limited Networking + +Vagrant does not yet know how to create and configure new networks for +Hyper-V. When launching a machine with Hyper-V, Vagrant will prompt you +asking what virtual switch you want to connect the virtual machine to. + +A result of this is that networking configurations in the Vagrantfile +are completely ignored with Hyper-V. Vagrant cannot enforce a static IP +or automatically configure a NAT. + +However, the IP address of the machine will be reported as part of +the `vagrant up`, and you can use that IP address as if it were +a host only network. + +## Snapshots + +Restoring snapshot VMs using `vagrant snapshot pop` or +`vagrant snapshot restore` will sometimes raise errors when mounting +SMB shared folders, however these mounts will still work inside the guest. diff --git a/website/pages/docs/hyperv/usage.html.md b/website/pages/docs/hyperv/usage.html.md new file mode 100644 index 000000000..46eae3a1c --- /dev/null +++ b/website/pages/docs/hyperv/usage.html.md @@ -0,0 +1,25 @@ +--- +layout: 'docs' +page_title: 'Usage - Hyper-V Provider' +sidebar_current: 'providers-hyperv-usage' +description: |- + The Hyper-V provider is used just like any other provider. Please read the + general basic usage page for providers. +--- + +# Usage + +The Vagrant Hyper-V 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 `hyperv`. + +Hyper-V also requires that you execute Vagrant with administrative +privileges. Creating and managing virtual machines with Hyper-V requires +admin rights. Vagrant will show you an error if it does not have the proper +permissions. + +Boxes for Hyper-V can be easily found on +[HashiCorp's Vagrant Cloud](https://vagrantcloud.com/boxes/search). To get started, you might +want to try the `hashicorp/bionic64` box. diff --git a/website/pages/docs/index.html.md b/website/pages/docs/index.html.md new file mode 100644 index 000000000..633c5c3a1 --- /dev/null +++ b/website/pages/docs/index.html.md @@ -0,0 +1,24 @@ +--- +layout: 'docs' +sidebar_current: 'overview' +page_title: 'Documentation' +description: |- + Welcome to the documentation for Vagrant - the command line utility for + managing the lifecycle of virtual machines. This website aims to document + every feature of Vagrant from top-to-bottom, covering as much detail as + possible. +--- + +# Vagrant Documentation + +Welcome to the documentation for Vagrant - the command line utility for managing +the lifecycle of virtual machines. This website aims to document every feature +of Vagrant from top-to-bottom, covering as much detail as possible. If you are +just getting started with Vagrant, it is highly recommended that you start with +the [getting started guide](/intro/getting-started/index.html) first, and then +return to this page. + +The navigation will take you through each component of Vagrant. Click on a +navigation item to get started, or read more about +[why developers, designers, and operators choose Vagrant](/intro/index.html) +for their needs. diff --git a/website/pages/docs/installation/backwards-compatibility.html.md b/website/pages/docs/installation/backwards-compatibility.html.md new file mode 100644 index 000000000..aee97ec16 --- /dev/null +++ b/website/pages/docs/installation/backwards-compatibility.html.md @@ -0,0 +1,41 @@ +--- +layout: 'docs' +page_title: 'Backwards Compatibility' +sidebar_current: 'installation-backwards-compatibility' +description: |- + Vagrant makes a very strict backwards-compatibility promise. +--- + +# Backwards Compatibility + +## For 1.0.x + +Vagrant 1.1+ provides full backwards compatibility for valid Vagrant 1.0.x +Vagrantfiles which do not use plugins. After installing Vagrant 1.1, your 1.0.x +environments should continue working without modifications, and existing running +machines will continue to be managed properly. + +This compatibility layer will remain in Vagrant up to and including Vagrant 2.0. +It may still exist after that, but Vagrant's compatibility promise is only for +two versions. Seeing that major Vagrant releases take years to develop and +release, it is safe to stick with your version 1.0.x Vagrantfile for the +time being. + +If you use any Vagrant 1.0.x plugins, you must remove references to these from +your Vagrantfile prior to upgrading. Vagrant 1.1+ introduces a new plugin +format that will protect against this sort of incompatibility from ever +happening again. + +## For 1.x + +Backwards compatibility between 1.x is not promised, and Vagrantfile +syntax stability is not promised until 2.0 final. Any backwards +incompatibilities within 1.x will be clearly documented. + +This is similar to how Vagrant 0.x was handled. In practice, Vagrant 0.x +only introduced a handful of backwards incompatibilities during the entire +development cycle, but the possibility of backwards incompatibilities +is made clear so people are not surprised. + +Vagrant 2.0 final will have a stable Vagrantfile format that will +remain backwards compatible, just as 1.0 is considered stable. diff --git a/website/pages/docs/installation/index.html.md b/website/pages/docs/installation/index.html.md new file mode 100644 index 000000000..5df28876e --- /dev/null +++ b/website/pages/docs/installation/index.html.md @@ -0,0 +1,96 @@ +--- +layout: 'docs' +page_title: 'Installing Vagrant' +sidebar_current: 'installation' +description: |- + Installing Vagrant is extremely easy. Head over to the Vagrant downloads page + and get the appropriate installer or package for your platform. Install the + package using standard procedures for your operating system. +--- + +# Installing Vagrant + +Installing Vagrant is extremely easy. Head over to the +[Vagrant downloads page](/downloads.html) and get the appropriate installer or +package for your platform. Install the package using standard procedures for +your operating system. + +The installer will automatically add `vagrant` to your system path +so that it is available in terminals. If it is not found, please try +logging out and logging back in to your system (this is particularly +necessary sometimes for Windows). + + + + + +## Running Multiple Hypervisors + +Sometimes, certain hypervisors do not allow you to bring up virtual machines +if more than one hypervisor is in use. If you are lucky, you might see the following +error message come up when trying to bring up a virtual machine with Vagrant and +VirtualBox: + + There was an error while executing `VBoxManage`, a CLI used by Vagrant for controlling VirtualBox. The command and stderr is shown below. + + Command: ["startvm", , "--type", "headless"] + + Stderr: VBoxManage: error: VT-x is being used by another hypervisor (VERR_VMX_IN_VMX_ROOT_MODE). + VBoxManage: error: VirtualBox can't operate in VMX root mode. Please disable the KVM kernel extension, recompile your kernel and reboot + (VERR_VMX_IN_VMX_ROOT_MODE) + VBoxManage: error: Details: code NS_ERROR_FAILURE (0x80004005), component ConsoleWrap, interface IConsole + +Other operating systems like Windows will blue screen if you attempt to bring up +a VirtualBox VM with Hyper-V enabled. Below are a couple of ways to ensure you +can use Vagrant and VirtualBox if another hypervisor is present. + +### Linux, VirtualBox, and KVM + +The above error message is because another hypervisor (like KVM) is in use. +We must blacklist these in order for VirtualBox to run correctly. + +First find out the name of the hypervisor: + + $ lsmod | grep kvm + kvm_intel 204800 6 + kvm 593920 1 kvm_intel + irqbypass 16384 1 kvm + +The one we're interested in is `kvm_intel`. You might have another. + +Blacklist the hypervisor (run the following as root): + + # echo 'blacklist kvm-intel' >> /etc/modprobe.d/blacklist.conf + +Restart your machine and try running vagrant again. + +### Windows, VirtualBox, and Hyper-V + +If you wish to use VirtualBox on Windows, you must ensure that Hyper-V is not enabled +on Windows. You can turn off the feature by running this Powershell command: + +```powershell +Disable-WindowsOptionalFeature -Online -FeatureName Microsoft-Hyper-V-All +``` + +You can also disable it by going through the Windows system settings: + +- Right click on the Windows button and select ‘Apps and Features’. +- Select Turn Windows Features on or off. +- Unselect Hyper-V and click OK. + +You might have to reboot your machine for the changes to take effect. More information +about Hyper-V can be read [here](https://docs.microsoft.com/en-us/virtualization/hyper-v-on-windows/quick-start/enable-hyper-v). diff --git a/website/pages/docs/installation/source.html.md b/website/pages/docs/installation/source.html.md new file mode 100644 index 000000000..0b2ce3bd9 --- /dev/null +++ b/website/pages/docs/installation/source.html.md @@ -0,0 +1,80 @@ +--- +layout: 'docs' +page_title: 'Installing Vagrant from Source' +sidebar_current: 'installation-source' +description: |- + Installing Vagrant from source is an advanced topic and is only recommended + when using the official installer is not an option. This page details the + steps and prerequisites for installing Vagrant from source. +--- + +# Installing Vagrant from Source + +Installing Vagrant from source is an advanced topic and is only recommended +when using the official installer is not an option. This page details the +steps and prerequisites for installing Vagrant from source. + +## Install Ruby + +You must have a modern Ruby (>= 2.2) in order to develop and build Vagrant. The +specific Ruby version is documented in the Vagrant's `gemspec`. Please refer to +the `vagrant.gemspec` in the repository on GitHub, as it will contain the most +up-to-date requirement. This guide will not discuss how to install and manage Ruby. +However, beware of the following pitfalls: + +- Do **NOT** use the system Ruby - use a Ruby version manager like rvm or chruby +- Vagrant plugins are configured based on current environment. If plugins are installed + using Vagrant from source, they will not work from the package based Vagrant installation. + +## Clone Vagrant + +Clone Vagrant's repository from GitHub into the directory where you keep code on your machine: + +```shell +$ git clone https://github.com/hashicorp/vagrant.git +``` + +Next, `cd` into that path. All commands will be run from this path: + +```shell +$ cd /path/to/your/vagrant/clone +``` + +Run the `bundle` command with a required version\* to install the requirements: + +```shell +$ bundle install +``` + +You can now run Vagrant by running `bundle exec vagrant` from inside that +directory. + +## Use Locally + +In order to use your locally-installed version of Vagrant in other projects, you will need to create a binstub and add it to your path. + +First, run the following command from the Vagrant repo: + +```shell +$ bundle --binstubs exec +``` + +This will generate files in `exec/`, including `vagrant`. You can now specify +the full path to the `exec/vagrant` anywhere on your operating system: + +```shell +$ /path/to/vagrant/exec/vagrant init -m hashicorp/bionic64 +``` + +Note that you _will_ receive warnings that running Vagrant like this is not +supported. It's true. It's not. You should listen to those warnings. + +If you do not want to specify the full path to Vagrant (i.e. you just want to +run `vagrant`), you can create a symbolic link to your exec: + +```shell +$ ln -sf /path/to/vagrant/exec/vagrant /usr/local/bin/vagrant +``` + +When you want to switch back to the official Vagrant version, simply +remove the symlink. diff --git a/website/pages/docs/installation/uninstallation.html.md b/website/pages/docs/installation/uninstallation.html.md new file mode 100644 index 000000000..bf1cbe2bf --- /dev/null +++ b/website/pages/docs/installation/uninstallation.html.md @@ -0,0 +1,61 @@ +--- +layout: 'docs' +page_title: 'Uninstalling Vagrant' +sidebar_current: 'installation-uninstallation' +description: |- + Uninstalling Vagrant is easy and straightforward. You can either uninstall + the Vagrant binary, the user data, or both. The sections below cover how to + do this on every platform. +--- + +# Uninstalling Vagrant + +Uninstalling Vagrant is easy and straightforward. You can either uninstall +the Vagrant binary, the user data, or both. The sections below cover how to +do this on every platform. + +## Removing the Vagrant Program + +Removing the Vagrant program will remove the `vagrant` binary and all +dependencies from your machine. After uninstalling the program, you can +always [reinstall](/docs/installation/) again using standard +methods. Uninstalling Vagrant will _not_ remove user data. The section below this +one gives more detailed instructions on how to remove that directory from your +system. + +On **Windows** + +> Uninstall using the add/remove programs section of the control panel + +On **Mac OS X**: + +```sh +rm -rf /opt/vagrant +rm -f /usr/local/bin/vagrant +sudo pkgutil --forget com.vagrant.vagrant +``` + +On **Linux**: + +```sh +rm -rf /opt/vagrant +rm -f /usr/bin/vagrant +``` + +## Removing User Data + +Removing the user data will remove all [boxes](/docs/boxes.html), +[plugins](/docs/plugins/), license files, and any stored state that may be used +by Vagrant. Removing the user data effectively makes Vagrant think it +is a fresh install. + +On all platforms, this directory is located in the root of your home directory, +and is named `vagrant.d`. Simply remove the `~/.vagrant.d` directory to delete the user data. If on +Windows, this directory is located at `C:\Users\YourUsername\.vagrant.d`, where +`YourUsername` is the username of your local user. + +When debugging, the Vagrant support team may ask you to remove this +directory. Before removing this directory, please make a backup. + +Running Vagrant will automatically regenerate any data necessary to run, +so it is safe to remove the user data at any time. diff --git a/website/pages/docs/installation/upgrading-from-1-0.html.md b/website/pages/docs/installation/upgrading-from-1-0.html.md new file mode 100644 index 000000000..71bcc1cc1 --- /dev/null +++ b/website/pages/docs/installation/upgrading-from-1-0.html.md @@ -0,0 +1,33 @@ +--- +layout: 'docs' +page_title: 'Upgrading from Vagrant 1.0' +sidebar_current: 'installation-1-0-upgrading' +description: |- + The upgrade process from 1.0.x to 1.x is straightforward. Vagrant is + backwards compatible with Vagrant 1.0.x, so you can simply reinstall Vagrant + over your previous installation by downloading the latest package and + installing it using standard procedures for your operating system. +--- + +# Upgrading From Vagrant 1.0.x + +The upgrade process from 1.0.x to 1.x is straightforward. Vagrant is quite +[backwards compatible](/docs/installation/backwards-compatibility.html) +with Vagrant 1.0.x, so you can simply reinstall Vagrant +over your previous installation by downloading the latest package and +installing it using standard procedures for your operating system. + +As the [backwards compatibility](/docs/installation/backwards-compatibility.html) +page says, **Vagrant 1.0.x plugins will not work with Vagrant 1.1+**. Many +of these plugins have been updated to work with newer versions of Vagrant, +so you can look to see if they've been updated. If not however, you will have +to remove them before upgrading. + +It is recommended you remove _all_ plugins before upgrading, and then slowly +add back the plugins. This usually makes for a smoother upgrade process. + + diff --git a/website/pages/docs/installation/upgrading.html.md b/website/pages/docs/installation/upgrading.html.md new file mode 100644 index 000000000..874726ea2 --- /dev/null +++ b/website/pages/docs/installation/upgrading.html.md @@ -0,0 +1,35 @@ +--- +layout: 'docs' +page_title: 'Upgrading Vagrant' +sidebar_current: 'installation-upgrading' +description: |- + If you are upgrading from Vagrant 1.0.x, please read the specific page + dedicated to that. This page covers upgrading Vagrant in general during the + 1.x series. +--- + +# Upgrading Vagrant + +If you are upgrading from Vagrant 1.0.x, please read the +[specific page dedicated to that](/docs/installation/upgrading-from-1-0.html). +This page covers upgrading Vagrant in general during the 1.x series. + +Vagrant upgrades during the 1.x release series are straightforward: + +1. [Download](/downloads.html) the new package +2. Install it over the existing package + +The installers will properly overwrite and remove old files. It is recommended +that no other Vagrant processes are running during the upgrade process. + +Note that Vagrantfile stability for the new Vagrantfile syntax is not +promised until 2.0 final. So while Vagrantfiles made for 1.0.x will +[continue to work](/docs/installation/backwards-compatibility.html), +newer Vagrantfiles may have backwards incompatible changes until 2.0 final. + +
+ Run into troubles upgrading? Please + report an issue + if you run into problems upgrading. Upgrades are meant to be a smooth + process and we consider it a bug if it was not. +
diff --git a/website/pages/docs/multi-machine/index.html.md b/website/pages/docs/multi-machine/index.html.md new file mode 100644 index 000000000..3594ecf9c --- /dev/null +++ b/website/pages/docs/multi-machine/index.html.md @@ -0,0 +1,153 @@ +--- +layout: 'docs' +page_title: 'Multi-Machine' +sidebar_current: 'multimachine' +description: |- + Vagrant is able to define and control multiple guest machines per + Vagrantfile. This is known as a "multi-machine" environment. +--- + +# Multi-Machine + +Vagrant is able to define and control multiple guest machines per +Vagrantfile. This is known as a "multi-machine" environment. + +These machines are generally able to work together or are somehow associated +with each other. Here are some use-cases people are using multi-machine +environments for today: + +- Accurately modeling a multi-server production topology, such as separating + a web and database server. +- Modeling a distributed system and how they interact with each other. +- Testing an interface, such as an API to a service component. +- Disaster-case testing: machines dying, network partitions, slow networks, + inconsistent world views, etc. + +Historically, running complex environments such as these was done by +flattening them onto a single machine. The problem with that is that it is +an inaccurate model of the production setup, which can behave far differently. + +Using the multi-machine feature of Vagrant, these environments can be modeled +in the context of a single Vagrant environment without losing any of the +benefits of Vagrant. + +## Defining Multiple Machines + +Multiple machines are defined within the same project [Vagrantfile](/docs/vagrantfile/) +using the `config.vm.define` method call. This configuration directive +is a little funny, because it creates a Vagrant configuration within a +configuration. An example shows this best: + +```ruby +Vagrant.configure("2") do |config| + config.vm.provision "shell", inline: "echo Hello" + + config.vm.define "web" do |web| + web.vm.box = "apache" + end + + config.vm.define "db" do |db| + db.vm.box = "mysql" + end +end +``` + +As you can see, `config.vm.define` takes a block with another variable. This +variable, such as `web` above, is the _exact_ same as the `config` variable, +except any configuration of the inner variable applies only to the machine +being defined. Therefore, any configuration on `web` will only affect the +`web` machine. + +And importantly, you can continue to use the `config` object as well. The +configuration object is loaded and merged before the machine-specific configuration, +just like other Vagrantfiles within the +[Vagrantfile load order](/docs/vagrantfile/#load-order). + +If you are familiar with programming, this is similar to how languages have +different variable scopes. + +When using these scopes, order of execution for things such as +provisioners becomes important. Vagrant enforces ordering outside-in, in +the order listed in the Vagrantfile. For example, with the Vagrantfile +below: + +```ruby +Vagrant.configure("2") do |config| + config.vm.provision :shell, inline: "echo A" + + config.vm.define :testing do |test| + test.vm.provision :shell, inline: "echo B" + end + + config.vm.provision :shell, inline: "echo C" +end +``` + +The provisioners in this case will output "A", then "C", then "B". Notice +that "B" is last. That is because the ordering is outside-in, in +the order of the file. + +If you want to apply a slightly different configuration to multiple machines, +see [this tip](/docs/vagrantfile/tips.html#loop-over-vm-definitions). + +## Controlling Multiple Machines + +The moment more than one machine is defined within a Vagrantfile, the +usage of the various `vagrant` commands changes slightly. The change should +be mostly intuitive. + +Commands that only make sense to target a single machine, such as +`vagrant ssh`, now _require_ the name of the machine to control. Using +the example above, you would say `vagrant ssh web` or `vagrant ssh db`. + +Other commands, such as `vagrant up`, operate on _every_ machine by +default. So if you ran `vagrant up`, Vagrant would bring up both the +web and DB machine. You could also optionally be specific and say +`vagrant up web` or `vagrant up db`. + +Additionally, you can specify a regular expression for matching only +certain machines. This is useful in some cases where you specify many similar +machines, for example if you are testing a distributed service you may have +a `leader` machine as well as a `follower0`, `follower1`, `follower2`, etc. If you +want to bring up all the followers but not the leader, you can just do +`vagrant up /follower[0-9]/`. If Vagrant sees a machine name within forward +slashes, it assumes you are using a regular expression. + +## Communication Between Machines + +In order to facilitate communication within machines in a multi-machine setup, +the various [networking](/docs/networking/) options should be used. +In particular, the [private network](/docs/networking/private_network.html) can +be used to make a private network between multiple machines and the host. + +## Specifying a Primary Machine + +You can also specify a _primary machine_. The primary machine will be the +default machine used when a specific machine in a multi-machine environment +is not specified. + +To specify a default machine, just mark it primary when defining it. Only +one primary machine may be specified. + +```ruby +config.vm.define "web", primary: true do |web| + # ... +end +``` + +## Autostart Machines + +By default in a multi-machine environment, `vagrant up` will start +all of the defined machines. The `autostart` setting allows you to tell +Vagrant to _not_ start specific machines. Example: + +```ruby +config.vm.define "web" +config.vm.define "db" +config.vm.define "db_follower", autostart: false +``` + +When running `vagrant up` with the settings above, Vagrant will automatically +start the "web" and "db" machines, but will not start the "db_follower" machine. +You can manually force the "db_follower" machine to start by running +`vagrant up db_follower`. diff --git a/website/pages/docs/networking/basic_usage.html.md b/website/pages/docs/networking/basic_usage.html.md new file mode 100644 index 000000000..c2110297a --- /dev/null +++ b/website/pages/docs/networking/basic_usage.html.md @@ -0,0 +1,48 @@ +--- +layout: 'docs' +page_title: 'Basic Usage - Networking' +sidebar_current: 'networking-basic' +description: |- + Vagrant offers multiple options for how you are able to connect your + guest machines to the network, but there is a standard usage pattern as + well as some points common to all network configurations that + are important to know. +--- + +# Basic Usage of Networking + +Vagrant offers multiple options for how you are able to connect your +guest machines to the network, but there is a standard usage pattern as +well as some points common to all network configurations that +are important to know. + +## Configuration + +All networks are configured within your [Vagrantfile](/docs/vagrantfile/) +using the `config.vm.network` method call. For example, the Vagrantfile +below defines some port forwarding: + +```ruby +Vagrant.configure("2") do |config| + # ... + config.vm.network "forwarded_port", guest: 80, host: 8080 +end +``` + +Every network type has an identifier such as `"forwarded_port"` in the above +example. Following this is a set of configuration arguments that can differ +for each network type. In the case of forwarded ports, two numeric arguments +are expected: the port on the guest followed by the port on the host that +the guest port can be accessed by. + +## Multiple Networks + +Multiple networks can be defined by having multiple `config.vm.network` +calls within the Vagrantfile. The exact meaning of this can differ for +each [provider](/docs/providers/), but in general the order specifies +the order in which the networks are enabled. + +## Enabling Networks + +Networks are automatically configured and enabled after they've been defined +in the Vagrantfile as part of the `vagrant up` or `vagrant reload` process. diff --git a/website/pages/docs/networking/forwarded_ports.html.md b/website/pages/docs/networking/forwarded_ports.html.md new file mode 100644 index 000000000..d9ded1981 --- /dev/null +++ b/website/pages/docs/networking/forwarded_ports.html.md @@ -0,0 +1,122 @@ +--- +layout: 'docs' +page_title: 'Forwarded Ports - Networking' +sidebar_current: 'networking-fp' +description: |- + Vagrant forwarded ports allow you to access a port on your host machine and + have all data forwarded to a port on the guest machine, over either TCP or + UDP. +--- + +# Forwarded Ports + +**Network identifier: `forwarded_port`** + +Vagrant forwarded ports allow you to access a port on your host machine and have +all data forwarded to a port on the guest machine, over either TCP or UDP. + +For example: If the guest machine is running a web server listening on port 80, +you can make a forwarded port mapping to port 8080 (or anything) on your host +machine. You can then open your browser to `localhost:8080` and browse the +website, while all actual network data is being sent to the guest. + +## Defining a Forwarded Port + +The forwarded port configuration expects two parameters, the port on the +guest and the port on the host. Example: + +```ruby +Vagrant.configure("2") do |config| + config.vm.network "forwarded_port", guest: 80, host: 8080 +end +``` + +This will allow accessing port 80 on the guest via port 8080 on the host. + +For most providers, forwarded ports by default bind to all interfaces. This +means that other devices on your network can access the forwarded ports. +If you want to restrict access, see the `guest_ip` and `host_ip` settings +below. + +## Options Reference + +This is a complete list of the options that are available for forwarded +ports. Only the `guest` and `host` options are required. Below this section, +there are more detailed examples of using these options. + +- `auto_correct` (boolean) - If true, the host port will be changed + automatically in case it collides with a port already in use. By + default, this is false. + +- `guest` (int) - The port on the guest that you want to be exposed on + the host. This can be any port. + +- `guest_ip` (string) - The guest IP to bind the forwarded port to. If + this is not set, the port will go to every IP interface. By default, + this is empty. + +- `host` (int) - The port on the host that you want to use to access the + port on the guest. This must be greater than port 1024 unless Vagrant + is running as root (which is not recommended). + +- `host_ip` (string) - The IP on the host you want to bind the forwarded + port to. If not specified, it will be bound to every IP. By default, + this is empty. + +- `protocol` (string) - Either "udp" or "tcp". This specifies the protocol + that will be allowed through the forwarded port. By default this is "tcp". + +- `id` (string) - Name of the rule (can be visible in VirtualBox). By + default this is "protocol""guest" (example : "tcp123"). + +## Forwarded Port Protocols + +By default, any defined port will only forward the TCP protocol. As an optional +third parameter, you may specify `protocol: 'udp'` in order to pass UDP +traffic. If a given port needs to be able to listen to the same port on both +protocols, you must define the port twice with each protocol specified, like +so: + +```ruby +Vagrant.configure("2") do |config| + config.vm.network "forwarded_port", guest: 2003, host: 12003, protocol: "tcp" + config.vm.network "forwarded_port", guest: 2003, host: 12003, protocol: "udp" +end +``` + +## Port Collisions and Correction + +It is common when running multiple Vagrant machines to unknowingly create +forwarded port definitions that collide with each other (two separate +Vagrant projects forwarded to port 8080, for example). Vagrant includes +built-in mechanism to detect this and correct it, automatically. + +Port collision detection is always done. Vagrant will not allow you to +define a forwarded port where the port on the host appears to be accepting +traffic or connections. + +Port collision auto-correction must be manually enabled for each forwarded +port, since it is often surprising when it occurs and can lead the Vagrant +user to think that the port was not properly forwarded. Enabling auto correct +is easy: + +```ruby +Vagrant.configure("2") do |config| + config.vm.network "forwarded_port", guest: 80, host: 8080, + auto_correct: true +end +``` + +The final `:auto_correct` parameter set to true tells Vagrant to auto +correct any collisions. During a `vagrant up` or `vagrant reload`, Vagrant +will output information about any collisions detections and auto corrections +made, so you can take notice and act accordingly. + +You can define allowed port range assignable by Vagrant when port collision is +detected via [config.vm.usable_port_range](/docs/vagrantfile/machine_settings.html) property. + +```ruby +Vagrant.configure("2") do |config| + config.vm.usable_port_range = 8000..8999 +end +``` diff --git a/website/pages/docs/networking/index.html.md b/website/pages/docs/networking/index.html.md new file mode 100644 index 000000000..3d2c3aad0 --- /dev/null +++ b/website/pages/docs/networking/index.html.md @@ -0,0 +1,42 @@ +--- +layout: 'docs' +page_title: 'Networking' +sidebar_current: 'networking' +description: |- + In order to access the Vagrant environment created, Vagrant exposes + some high-level networking options for things such as forwarded ports, + connecting to a public network, or creating a private network. +--- + +# Networking + +In order to access the Vagrant environment created, Vagrant exposes +some high-level networking options for things such as forwarded ports, +connecting to a public network, or creating a private network. + +The high-level networking options are meant to define an abstraction that +works across multiple [providers](/docs/providers/). This means that +you can take your Vagrantfile you used to spin up a VirtualBox machine and +you can reasonably expect that Vagrantfile to behave the same with something +like VMware. + +You should first read the [basic usage](/docs/networking/basic_usage.html) page +and then continue by reading the documentation for a specific networking +primitive by following the navigation to the left. + +## Advanced Configuration + +In some cases, +these options are _too_ high-level, and you may want to more finely tune +and configure the network interfaces of the underlying machine. Most +providers expose [provider-specific configuration](/docs/providers/configuration.html) +to do this, so please read the documentation for your specific provider +to see what options are available. + +
+ For beginners: It is strongly recommended you use + only the high-level networking options until you are comfortable + with the Vagrant workflow and have things working at a basic level. + Provider-specific network configuration can very quickly lock you out + of your guest machine if improperly done. +
diff --git a/website/pages/docs/networking/private_network.html.md b/website/pages/docs/networking/private_network.html.md new file mode 100644 index 000000000..4d19ffd97 --- /dev/null +++ b/website/pages/docs/networking/private_network.html.md @@ -0,0 +1,126 @@ +--- +layout: 'docs' +page_title: 'Private Networks - Networking' +sidebar_current: 'networking-private' +description: |- + Vagrant private networks allow you to access your guest machine by some + address that is not publicly accessible from the global internet. In general, + this means your machine gets an address in the private address space. +--- + +# Private Networks + +**Network identifier: `private_network`** + +Vagrant private networks allow you to access your guest machine by some address +that is not publicly accessible from the global internet. In general, this +means your machine gets an address in the [private address space](https://en.wikipedia.org/wiki/Private_network#Private_IPv4_address_spaces). + +Multiple machines within the same private network (also usually with the +restriction that they're backed by the same [provider](/docs/providers/)) +can communicate with each other on private networks. + +
+ Guest operating system support. Private networks + generally require configuring the network adapters on the guest + machine. This process varies from OS to OS. Vagrant ships with + knowledge of how to configure networks on a variety of guest + operating systems, but it is possible if you are using a particularly + old or new operating system that private networks will not properly + configure. +
+ +## DHCP + +The easiest way to use a private network is to allow the IP to be assigned +via DHCP. + +```ruby +Vagrant.configure("2") do |config| + config.vm.network "private_network", type: "dhcp" +end +``` + +This will automatically assign an IP address from the reserved address space. +The IP address can be determined by using `vagrant ssh` to SSH into the +machine and using the appropriate command line tool to find the IP, +such as `ifconfig`. + +## Static IP + +You can also specify a static IP address for the machine. This lets you +access the Vagrant managed machine using a static, known IP. The +Vagrantfile for a static IP looks like this: + +```ruby +Vagrant.configure("2") do |config| + config.vm.network "private_network", ip: "192.168.50.4" +end +``` + +It is up to the users to make sure that the static IP does not collide +with any other machines on the same network. + +While you can choose any IP you would like, you _should_ use an IP from +the [reserved private address space](https://en.wikipedia.org/wiki/Private_network#Private_IPv4_address_spaces). These IPs are guaranteed to never be publicly routable, +and most routers actually block traffic from going to them from the +outside world. + +For some operating systems, additional configuration options for the static +IP address are available such as setting the default gateway or MTU. + +
+ Warning! Do not choose an IP that overlaps with any + other IP space on your system. This can cause the network to not be + reachable. +
+ +## IPv6 + +You can specify a static IP via IPv6. DHCP for IPv6 is not supported. +To use IPv6, just specify an IPv6 address as the IP: + +```ruby +Vagrant.configure("2") do |config| + config.vm.network "private_network", ip: "fde4:8dba:82e1::c4" +end +``` + +This will assign that IP to the machine. The entire `/64` subnet will +be reserved. Please make sure to use the reserved local addresses approved +for IPv6. + +You can also modify the prefix length by changing the `netmask` option +(defaults to 64): + +```ruby +Vagrant.configure("2") do |config| + config.vm.network "private_network", + ip: "fde4:8dba:82e1::c4", + netmask: "96" +end +``` + +IPv6 supports for private networks was added in Vagrant 1.7.5 and may +not work with every provider. + +## Disable Auto-Configuration + +If you want to manually configure the network interface yourself, you +can disable Vagrant's auto-configure feature by specifying `auto_config`: + +```ruby +Vagrant.configure("2") do |config| + config.vm.network "private_network", ip: "192.168.50.4", + auto_config: false +end +``` + +If you already started the Vagrant environment before setting `auto_config`, +the files it initially placed there will stay there. You will have to remove +those files manually or destroy and recreate the machine. + +The files created by Vagrant depend on the OS. For example, for many +Linux distros, this is `/etc/network/interfaces`. In general you should +look in the normal location that network interfaces are configured for your +distro. diff --git a/website/pages/docs/networking/public_network.html.md b/website/pages/docs/networking/public_network.html.md new file mode 100644 index 000000000..9da455bce --- /dev/null +++ b/website/pages/docs/networking/public_network.html.md @@ -0,0 +1,162 @@ +--- +layout: 'docs' +page_title: 'Public Networks - Networking' +sidebar_current: 'networking-public' +description: |- + Vagrant public networks are less private than private networks, and the exact + meaning actually varies from provider to provider, hence the ambiguous + definition. The idea is that while private networks should never allow the + general public access to your machine, public networks can. +--- + +# Public Networks + +**Network identifier: `public_network`** + +Vagrant public networks are less private than private networks, and the exact +meaning actually varies from [provider to provider](/docs/providers/), +hence the ambiguous definition. The idea is that while +[private networks](/docs/networking/private_network.html) should never allow the +general public access to your machine, public networks can. + +
+ Confused? We kind of are, too. It is likely that + public networks will be replaced by :bridged in a + future release, since that is in general what should be done with + public networks, and providers that do not support bridging generally + do not have any other features that map to public networks either. +
+ +
+ Warning! Vagrant boxes are insecure by default + and by design, featuring public passwords, insecure keypairs + for SSH access, and potentially allow root access over SSH. With + these known credentials, your box is easily accessible by anyone on + your network. Before configuring Vagrant to use a public network, + consider all potential security implications + and review the default box + configuration to identify potential security risks. +
+ +## DHCP + +The easiest way to use a public network is to allow the IP to be assigned +via DHCP. In this case, defining a public network is trivially easy: + +```ruby +Vagrant.configure("2") do |config| + config.vm.network "public_network" +end +``` + +When DHCP is used, the IP can be determined by using `vagrant ssh` to +SSH into the machine and using the appropriate command line tool to find +the IP, such as `ifconfig`. + +### Using the DHCP Assigned Default Route + +Some cases require the DHCP assigned default route to be untouched. In these cases one +may specify the `use_dhcp_assigned_default_route` option. As an example: + +```ruby +Vagrant.configure("2") do |config| + config.vm.network "public_network", + use_dhcp_assigned_default_route: true +end +``` + +## Static IP + +Depending on your setup, you may wish to manually set the IP of your +bridged interface. To do so, add a `:ip` clause to the network definition. + +```ruby +config.vm.network "public_network", ip: "192.168.0.17" +``` + +## Default Network Interface + +If more than one network interface is available on the host machine, Vagrant will +ask you to choose which interface the virtual machine should bridge to. A default +interface can be specified by adding a `:bridge` clause to the network definition. + +```ruby +config.vm.network "public_network", bridge: "en1: Wi-Fi (AirPort)" +``` + +The string identifying the desired interface must exactly match the name of an +available interface. If it cannot be found, Vagrant will ask you to pick +from a list of available network interfaces. + +With some providers, it is possible to specify a list of adapters to bridge +against: + +```ruby +config.vm.network "public_network", bridge: [ + "en1: Wi-Fi (AirPort)", + "en6: Broadcom NetXtreme Gigabit Ethernet Controller", +] +``` + +In this example, the first network adapter that exists and can successfully be +bridge will be used. + +## Disable Auto-Configuration + +If you want to manually configure the network interface yourself, you +can disable auto-configuration by specifying `auto_config`: + +```ruby +Vagrant.configure("2") do |config| + config.vm.network "public_network", auto_config: false +end +``` + +Then the shell provisioner can be used to configure the ip of the interface: + +```ruby +Vagrant.configure("2") do |config| + config.vm.network "public_network", auto_config: false + + # manual ip + config.vm.provision "shell", + run: "always", + inline: "ifconfig eth1 192.168.0.17 netmask 255.255.255.0 up" + + # manual ipv6 + config.vm.provision "shell", + run: "always", + inline: "ifconfig eth1 inet6 add fc00::17/7" +end +``` + +## Default Router + +Depending on your setup, you may wish to manually override the default +router configuration. This is required if you need to access the Vagrant box from +other networks over the public network. To do so, you can use a shell +provisioner script: + +```ruby +Vagrant.configure("2") do |config| + config.vm.network "public_network", ip: "192.168.0.17" + + # default router + config.vm.provision "shell", + run: "always", + inline: "route add default gw 192.168.0.1" + + # default router ipv6 + config.vm.provision "shell", + run: "always", + inline: "route -A inet6 add default gw fc00::1 eth1" + + # delete default gw on eth0 + config.vm.provision "shell", + run: "always", + inline: "eval `route -n | awk '{ if ($8 ==\"eth0\" && $2 != \"0.0.0.0\") print \"route del default gw \" $2; }'`" +end +``` + +Note the above is fairly complex and may be guest OS specific, but we +document the rough idea of how to do it because it is a common question. diff --git a/website/pages/docs/other/debugging.html.md b/website/pages/docs/other/debugging.html.md new file mode 100644 index 000000000..257431b21 --- /dev/null +++ b/website/pages/docs/other/debugging.html.md @@ -0,0 +1,70 @@ +--- +layout: 'docs' +page_title: 'Debugging and Troubleshooting' +sidebar_current: 'other-debugging' +description: |- + As much as we try to keep Vagrant stable and bug free, it is inevitable + that issues will arise and Vagrant will behave in unexpected ways. In + these cases, Vagrant has amazing support channels available to assist you. +--- + +# Debugging + +As much as we try to keep Vagrant stable and bug free, it is inevitable +that issues will arise and Vagrant will behave in unexpected ways. + +When using these support channels, it is generally helpful to include +debugging logs along with any error reports. These logs can often help you +troubleshoot any problems you may be having. + +!> **Scan for sensitive information!** Vagrant debug logs include information +about your system including environment variables and user information. If you +store sensitive information in the environment or in your user account, please +scan or scrub the debug log of this information before uploading the contents to +the public Internet. + +~> **Submit debug logs using GitHub Gist.** If you plan on submitting a bug +report or issue that includes debug-level logs, please use a service like +[Gist](https://gist.github.com). **Do not** paste the raw debug logs into an +issue as it makes it very difficult to scroll and parse the information. + +To enable detailed logging, set the `VAGRANT_LOG` environmental variable +to the desired log level name, which is one of `debug` (loud), `info` (normal), +`warn` (quiet), and `error` (very quiet). When asking for support, please +set this to `debug`. When troubleshooting your own issues, you should start +with `info`, which is much quieter, but contains important information +about the behavior of Vagrant. + +On Linux and Mac systems, this can be done by prepending the `vagrant` +command with an environmental variable declaration: + +``` +$ VAGRANT_LOG=info vagrant up +``` + +On Windows, multiple steps are required: + +``` +$ set VAGRANT_LOG=info +$ vagrant up +``` + +You can also get the debug level output using the `--debug` command line +option. For example: + +``` +$ vagrant up --debug +``` + +On Linux and Mac, if you are saving the output to a file, you may need to redirect stderr and +stdout using `&>`: + +``` +$ vagrant up --debug &> vagrant.log +``` + +On Windows in PowerShell (outputs to log and screen): + +``` +$ vagrant up --debug 2>&1 | Tee-Object -FilePath ".\vagrant.log" +``` diff --git a/website/pages/docs/other/environmental-variables.html.md b/website/pages/docs/other/environmental-variables.html.md new file mode 100644 index 000000000..1d1caddaa --- /dev/null +++ b/website/pages/docs/other/environmental-variables.html.md @@ -0,0 +1,321 @@ +--- +layout: 'docs' +page_title: 'Environmental Variables' +sidebar_current: 'other-envvars' +description: |- + Vagrant has a set of environmental variables that can be used to + configure and control it in a global way. This page lists those environmental + variables. +--- + +# Environmental Variables + +Vagrant has a set of environmental variables that can be used to +configure and control it in a global way. This page lists those environmental +variables. + +## `CFLAGS` + +If set the contents of this environment variable will be appended to the +value generated by the Vagrant launcher. + +## `CPPFLAGS` + +If set the contents of this environment variable will be appended to the +value generated by the Vagrant launcher. + +## `CURL_CA_BUNDLE` + +If set this environment variable will be passed through to the Vagrant +process. By default Vagrant will use the CA certificate included with +the Vagrant installation. + +## `LDFLAGS` + +If set the contents of this environment variable will be appended to the +value generated by the Vagrant launcher. + +## `SSL_CERT_FILE` + +If set this environment variable will be passed through to the Vagrant +process. By default Vagrant will use the CA certificate included with +the Vagrant installation. + +## `VAGRANT_ALIAS_FILE` + +`VAGRANT_ALIAS_FILE` can be set to change the file where Vagrant aliases are +defined. By default, this is set to `~/.vagrant.d/aliases`. + +## `VAGRANT_ALLOW_PLUGIN_SOURCE_ERRORS` + +If this is set to any value, then Vagrant will not error when a configured +plugin source is unavailable. When installing a Vagrant plugin Vagrant +will error and halt if a plugin source is inaccessible. In some cases it +may be desirable to ignore inaccessible sources and continue with the +plugin installation. Enabling this value will cause Vagrant to simply log +the plugin source error and continue. + +## `VAGRANT_BOX_UPDATE_CHECK_DISABLE` + +By default, Vagrant will query the metadata API server to see if a newer +box version is available for download. This optional can be disabled on a +per-Vagrantfile basis with `config.vm.box_check_update`, but it can also be +disabled globally setting `VAGRANT_BOX_UPDATE_CHECK_DISABLE` to any non-empty +value. + +This option will not affect global box functions like `vagrant box update`. + +## `VAGRANT_CHECKPOINT_DISABLE` + +Vagrant does occasional network calls to check whether the version of Vagrant +that is running locally is up to date. We understand that software making remote +calls over the internet for any reason can be undesirable. To suppress these +calls, set the environment variable `VAGRANT_CHECKPOINT_DISABLE` to any +non-empty value. + +If you use other HashiCorp tools like Packer and would prefer to configure this +setting only once, you can set `CHECKPOINT_DISABLE` instead. + +## `VAGRANT_CWD` + +`VAGRANT_CWD` can be set to change the working directory of Vagrant. By +default, Vagrant uses the current directory you are in. The working directory +is important because it is where Vagrant looks for the Vagrantfile. It +also defines how relative paths in the Vagrantfile are expanded, since they're +expanded relative to where the Vagrantfile is found. + +This environmental variable is most commonly set when running Vagrant from +a scripting environment in order to set the directory that Vagrant sees. + +## `VAGRANT_DEBUG_LAUNCHER` + +For performance reasons, especially for Windows users, Vagrant uses a static +binary to launch the actual Vagrant process. If you have _very_ early issues +when launching Vagrant from the official installer, you can specify the +`VAGRANT_DEBUG_LAUNCHER` environment variable to output debugging information +about the launch process. + +## `VAGRANT_DEFAULT_PROVIDER` + +This configures the default provider Vagrant will use. + +This normally does not need to be set since Vagrant is fairly intelligent +about how to detect the default provider. By setting this, you will force +Vagrant to use this provider for any _new_ Vagrant environments. Existing +Vagrant environments will continue to use the provider they came `up` with. +Once you `vagrant destroy` existing environments, this will take effect. + +## `VAGRANT_DEFAULT_TEMPLATE` + +This configures the template used by `vagrant init` when the `--template` option +is not provided. + +## `VAGRANT_DETECTED_ARCH` + +This environment variable may be set by the Vagrant launcher to help determine +the current runtime architecture in use. In general Vagrant will set this value +when running on a Windows host using a cygwin or msys based shell. The value +the Vagrant launcher may set in this environment variable will not always match +the actual architecture of the platform itself. Instead it signifies the detected +architecture of the environment it is running within. If this value is set, the +Vagrant launcher will not modify it. + +## `VAGRANT_DETECTED_OS` + +This environment variable may be set by the Vagrant launcher to help determine +the current runtime platform. In general Vagrant will set this value when running +on a Windows host using a cygwin or msys based shell. If this value is set, the +Vagrant launcher will not modify it. + +## `VAGRANT_DISABLE_RESOLV_REPLACE` + +Vagrant can optionally use the Ruby Resolv library in place of the libc resolver. +This can be disabled setting this environment variable. + +## `VAGRANT_DISABLE_VBOXSYMLINKCREATE` + +If set, this will completely disable the ability to create symlinks with all VirtualBox +shared folders. If this environment variable is not set, the VirtualBox synced +folders option `SharedFoldersEnableSymlinksCreate` will be enabled by default. +This option can be overridden on a per-folder basis within your Vagrantfile +config by setting the `SharedFoldersEnableSymlinksCreate` option to true if you +do not wish to completely disable this feature for all VirtualBox guests. + +More information on the option can be read in the [VirtualBox synced folders docs page.](/docs/synced-folders/virtualbox.html#sharedfoldersenablesymlinkscreate) + +## `VAGRANT_DISABLE_SMBMFSYMLINKS` + +If set, this will disable the `mfsymlinks` option for mounting SMB filesystems. If not set, then the `mfsymlinks` option will be enabled by default. This option can be overriden on a pre-folder basis with your Vagrantfile by setting `mount_options: ['mfsymlinks']`. + +## `VAGRANT_DOTFILE_PATH` + +`VAGRANT_DOTFILE_PATH` can be set to change the directory where Vagrant stores +VM-specific state, such as the VirtualBox VM UUID. By default, this is set to +`.vagrant`. If you keep your Vagrantfile in a Dropbox folder in order to share +the folder between your desktop and laptop (for example), Vagrant will overwrite +the files in this directory with the details of the VM on the most recently-used +host. To avoid this, you could set `VAGRANT_DOTFILE_PATH` to `.vagrant-laptop` +and `.vagrant-desktop` on the respective machines. (Remember to update your +`.gitignore`!) + +## `VAGRANT_ENABLE_RESOLV_REPLACE` + +Use the Ruby Resolv library in place of the libc resolver. + +## `VAGRANT_FORCE_COLOR` + +If this is set to any value, then Vagrant will force colored output, even +if it detected that there is no TTY or the current environment does not +support it. + +The equivalent behavior can be achieved by using the `--color` flag on a +command-by-command basis. This environmental variable is useful for setting +this flag globally. + +## `VAGRANT_HOME` + +`VAGRANT_HOME` can be set to change the directory where Vagrant stores +global state. By default, this is set to `~/.vagrant.d`. The Vagrant home +directory is where things such as boxes are stored, so it can actually become +quite large on disk. + +## `VAGRANT_IGNORE_WINRM_PLUGIN` + +Vagrant will not display warning when `vagrant-winrm` plugin is installed. + +## `VAGRANT_INSTALL_LOCAL_PLUGINS` + +If this is set to any value, Vagrant will not prompt for confirmation +prior to installing local plugins which have been defined within the +local Vagrantfile. + +## `VAGRANT_IS_HYPERV_ADMIN` + +Disable Vagrant's check for Hyper-V admin privileges and allow Vagrant to assume +the current user has full access to Hyper-V. This is useful if the internal +privilege check incorrectly determines the current user does not have access +to Hyper-V. + +## `VAGRANT_LOCAL_PLUGINS_LOAD` + +If this is set Vagrant will not stub the Vagrantfile when running +`vagrant plugin` commands. When this environment variable is set the +`--local` flag will not be required by `vagrant plugin` commands to +enable local project plugins. + +## `VAGRANT_LOG` + +`VAGRANT_LOG` specifies the verbosity of log messages from Vagrant. +By default, Vagrant does not actively show any log messages. + +Log messages are very useful when troubleshooting issues, reporting +bugs, or getting support. At the most verbose level, Vagrant outputs +basically everything it is doing. + +Available log levels are "debug," "info," "warn," and "error." Both +"warn" and "error" are practically useless since there are very few +cases of these, and Vagrant generally reports them within the normal +output. + +"info" is a good level to start with if you are having problems, because +while it is much louder than normal output, it is still very human-readable +and can help identify certain issues. + +"debug" output is _extremely_ verbose and can be difficult to read without +some knowledge of Vagrant internals. It is the best output to attach to +a support request or bug report, however. + +## `VAGRANT_NO_COLOR` + +If this is set to any value, then Vagrant will not use any colorized +output. This is useful if you are logging the output to a file or +on a system that does not support colors. + +The equivalent behavior can be achieved by using the `--no-color` flag +on a command-by-command basis. This environmental variable is useful +for setting this flag globally. + +## `VAGRANT_NO_PARALLEL` + +If this is set, Vagrant will not perform any parallel operations (such as +parallel box provisioning). All operations will be performed in serial. + +## `VAGRANT_NO_PLUGINS` + +If this is set to any value, then Vagrant will not load any 3rd party +plugins. This is useful if you install a plugin and it is introducing +instability to Vagrant, or if you want a specific Vagrant environment to +not load plugins. + +Note that any `vagrant plugin` commands automatically do not load any +plugins, so if you do install any unstable plugins, you can always use +the `vagrant plugin` commands without having to worry. + +## `VAGRANT_POWERSHELL_VERSION_DETECTION_TIMEOUT` + +Vagrant will use a default timeout when checking for the installed version +of PowerShell. Occasionally the default can be too low and Vagrant will report +being unable to detect the installed version of PowerShell. This environment +variable can be used to extend the timeout used during PowerShell version +detection. + +When setting this environment variable, its value will be in seconds. By default, +it will use 30 seconds as a timeout. + +## `VAGRANT_PREFERRED_PROVIDERS` + +This configures providers that Vagrant should prefer. + +Much like the `VAGRANT_DEFAULT_PROVIDER` this environment variable normally +does not need to be set. By setting this you will instruct Vagrant to +_prefer_ providers defined in this environment variable for any _new_ +Vagrant environments. Existing Vagrant environments will continue to use +the provider they came `up` with. Once you `vagrant destroy` existing environments, +this will take effect. A single provider can be defined within this environment +variable or a comma delimited list of providers. + +## `VAGRANT_PREFER_SYSTEM_BIN` + +If this is set, Vagrant will prefer using utility executables (like `ssh` and `rsync`) +from the local system instead of those vendored within the Vagrant installation. + +Vagrant will default to using a system provided `ssh` on Windows. This +environment variable can also be used to disable that behavior to force Vagrant to +use the embedded `ssh` executable by setting it to `0`. + +## `VAGRANT_SKIP_SUBPROCESS_JAILBREAK` + +As of Vagrant 1.7.3, Vagrant tries to intelligently detect if it is running in +the installer or running via Bundler. Although not officially supported, Vagrant +tries its best to work when executed via Bundler. When Vagrant detects that you +have spawned a subprocess that lives outside of Vagrant's installer, Vagrant +will do its best to reset the preserved environment during the subprocess +execution. + +If Vagrant detects it is running outside of the officially installer, the +original environment will always be restored. You can disable this automatic +jailbreak by setting `VAGRANT_SKIP_SUBPROCESS_JAILBREAK`. + +## `VAGRANT_USER_AGENT_PROVISIONAL_STRING` + +Vagrant will append the contents of this variable to the default user agent header. + +## `VAGRANT_USE_VAGRANT_TRIGGERS` + +Vagrant will not display the warning about disabling the core trigger feature if +the community plugin is installed. + +## `VAGRANT_VAGRANTFILE` + +This specifies the filename of the Vagrantfile that Vagrant searches for. +By default, this is "Vagrantfile". Note that this is _not_ a file path, +but just a filename. + +This environmental variable is commonly used in scripting environments +where a single folder may contain multiple Vagrantfiles representing +different configurations. + +## `VAGRANT_WINPTY_DISABLE` + +If this is set, Vagrant will _not_ wrap interactive processes with winpty where +required. diff --git a/website/pages/docs/other/index.html.md b/website/pages/docs/other/index.html.md new file mode 100644 index 000000000..a772547b5 --- /dev/null +++ b/website/pages/docs/other/index.html.md @@ -0,0 +1,16 @@ +--- +layout: 'docs' +page_title: 'Other' +sidebar_current: 'other' +description: |- + This page covers Vagrant information that does not quite fit under the other + categories. +--- + +# Other + +This section covers other information that does not quite fit under the +other categories. + +- [Debugging](/docs/other/debugging.html) +- [Environment Variables](/docs/other/environmental-variables.html) diff --git a/website/pages/docs/other/macos-catalina.html.md b/website/pages/docs/other/macos-catalina.html.md new file mode 100644 index 000000000..7ed6a431d --- /dev/null +++ b/website/pages/docs/other/macos-catalina.html.md @@ -0,0 +1,32 @@ +--- +layout: 'docs' +page_title: 'Vagrant and macOS Catalina' +sidebar_current: 'other-macos-catalina' +description: |- + An overview of using Vagrant on macOS Catalina. +--- + +# Vagrant and macOS Catalina + +The latest version of macOS (Catalina) includes security changes that prevent +applications from accessing data in your Documents, Desktop, and Downloads +folders without explicit permission. If you keep any virtual machine files in +these folders, you will need to allow access to these folders for your terminal +emulator. + +Initially when you try to access one of these folders from the command line, you +should see a popup that says something like: + +> “Terminal” would like to access files in your Documents folder. + +Click "OK" to grant those permissions. + +If you click "Don't Allow" and find that you need to grant access later on, you +can go to "System Preferences" -> "Security & Privacy" -> "Files and Folders" +and you should see your terminal emulator there. Click on the lock, and then +click on the checkbox next to the folder that contains the files that Vagrant +needs to access. + +Note that granting the `vagrant` binary "Full Disk Access" is not sufficient or +necessary. If Terminal (or iTerm2/Hyper/etc.) is granted access to a particular +folder, then Vagrant will also be able to access that folder. diff --git a/website/pages/docs/other/wsl.html.md b/website/pages/docs/other/wsl.html.md new file mode 100644 index 000000000..8717870b3 --- /dev/null +++ b/website/pages/docs/other/wsl.html.md @@ -0,0 +1,135 @@ +--- +layout: 'docs' +page_title: 'Vagrant and Windows Subsystem for Linux' +sidebar_current: 'other-wsl' +description: |- + An overview of using Vagrant on Windows within the Windows Subsystem + for Linux. +--- + +# Vagrant and Windows Subsystem for Linux + +Recent versions of Windows 10 now include Windows Subsystem for Linux (WSL) as +an optional Windows feature. The WSL supports running a Linux environment +within Windows. Vagrant support for WSL is still in development and should +be considered _beta_. + +
+ Warning: Advanced Topic! Using Vagrant within the Windows + Subsystem for Linux is an advanced topic that only experienced Vagrant users + who are reasonably comfortable with Windows, WSL, and Linux should approach. +
+ +## Vagrant Installation + +Vagrant _must_ be installed within the Linux distribution used with WSL. While +the `vagrant.exe` executable provided by the Vagrant Windows installation is +accessible from within the WSL, it will not function as expected. + +Download the installer package for the Linux distribution from the releases +page and install Vagrant. + +**NOTE: When Vagrant is installed on the Windows system the version installed +within the Linux distribution _must_ match.** + +# Vagrant Usage + +## Windows Access + +By default Vagrant will not access features available on the Windows system +from within the WSL. This means the VirtualBox and Hyper-V providers will +not be available. To enable Windows access, which will also enable the +VirtualBox and Hyper-V providers, set the `VAGRANT_WSL_ENABLE_WINDOWS_ACCESS` +environment variable: + +``` +$ export VAGRANT_WSL_ENABLE_WINDOWS_ACCESS="1" +``` + +When Windows access is enabled Vagrant will automatically adjust `VAGRANT_HOME` +to be located on the Windows host. This is required to ensure `VAGRANT_HOME` +is located on a DrvFs file system. + +## PATH modifications + +Vagrant will detect when it is being run within the WSL and adjust how it +locates and executes third party executables. For example, when using the +VirtualBox provider Vagrant will interact with VirtualBox installed on +the Windows system, not within the WSL. It is important to ensure that +any required Windows executable is available within your `PATH` to allow +Vagrant to access them. + +For example, when using the VirtualBox provider: + +``` +export PATH="$PATH:/mnt/c/Program Files/Oracle/VirtualBox" +``` + +## Synced Folders + +Support for synced folders within the WSL is implementation dependent. In +most cases synced folders will not be supported when running Vagrant within +WSL on a VolFs file system. Synced folder implementations must "opt-in" to +supporting usage from VolFs file systems. To use synced folders from within +the WSL that do not support VolFs file systems, move the Vagrant project +directory to a DrvFs file system location (/mnt/c/ prefixed path for example). + +## Windows Access + +Working within the WSL provides a layer of isolation from the actual +Windows system. In most cases Vagrant will need access to the actual +Windows system to function correctly. As most Vagrant providers will +need to be installed on Windows directly (not within the WSL) Vagrant +will require Windows access. Access to the Windows system is controlled +via an environment variable: `VAGRANT_WSL_ENABLE_WINDOWS_ACCESS`. If +this environment variable is set, Vagrant will access the Windows system +to run executables and enable things like synced folders. When running +in a bash shell within WSL, the environment variable can be setup like so: + +``` +$ export VAGRANT_WSL_ENABLE_WINDOWS_ACCESS="1" +``` + +This will enable Vagrant to access the Windows system outside of the +WSL and properly interact with Windows executables. This will automatically +modify the `VAGRANT_HOME` environment variable if it is not already defined, +setting it to be within the user's home directory on Windows. + +It is important to note that paths shared with the Windows system will +not have Linux permissions enforced. For example, when a directory within +the WSL is synced to a guest using the VirtualBox provider, any local +permissions defined on that directory (or its contents) will not be +visible from the guest. Likewise, any files created from the guest within +the synced folder will be world readable/writeable in WSL. + +Other useful WSL related environment variables: + +- `VAGRANT_WSL_WINDOWS_ACCESS_USER` - Override current Windows username +- `VAGRANT_WSL_DISABLE_VAGRANT_HOME` - Do not modify the `VAGRANT_HOME` variable +- `VAGRANT_WSL_WINDOWS_ACCESS_USER_HOME_PATH` - Custom Windows system home path + +If a Vagrant project directory is not within the user's home directory on the +Windows system, certain actions that include permission checks may fail (like +`vagrant ssh`). When accessing Vagrant projects outside the WSL Vagrant will +skip these permission checks when the project path is within the path defined +in the `VAGRANT_WSL_WINDOWS_ACCESS_USER_HOME_PATH` environment variable. For +example, if a user wants to run a Vagrant project from the WSL that is located +at `C:\TestDir\vagrant-project`: + +``` +C:\Users\vagrant> cd C:\TestDir\vagrant-project +C:\TestDir\vagrant-project> bash +vagrant@vagrant-10:/mnt/c/TestDir/vagrant-project$ export VAGRANT_WSL_WINDOWS_ACCESS_USER_HOME_PATH="/mnt/c/TestDir" +vagrant@vagrant-10:/mnt/c/TestDir/vagrant-project$ vagrant ssh +``` + +## Using Docker + +The docker daemon cannot be run inside the Windows Subsystem for Linux. However, +the daemon _can_ be run on Windows and accessed by Vagrant while running in the +WSL. Once docker is installed and running on Windows, export the following +environment variable to give Vagrant access: + +``` +vagrant@vagrant-10:/mnt/c/Users/vagrant$ export DOCKER_HOST=tcp://127.0.0.1:2375 +``` diff --git a/website/pages/docs/plugins/action-hooks.html.md b/website/pages/docs/plugins/action-hooks.html.md new file mode 100644 index 000000000..41178552c --- /dev/null +++ b/website/pages/docs/plugins/action-hooks.html.md @@ -0,0 +1,83 @@ +--- +layout: 'docs' +page_title: 'Plugin Development Basics - Action Hooks' +sidebar_current: 'plugins-action-hooks' +description: |- + Action hooks provide ways to interact with Vagrant at a very low level by + injecting middleware in various phases of Vagrant's lifecycle. This is an + advanced option, even for plugin development. +--- + +# Action Hooks + +Action hooks provide ways to interact with Vagrant at a very low level by +injecting middleware in various phases of Vagrant's lifecycle. This is an +advanced option, even for plugin development. + +
+ Warning: Advanced Topic! Developing plugins is an + advanced topic that only experienced Vagrant users who are reasonably + comfortable with Ruby should approach. +
+ +## Public Action Hooks + +The following action hooks are available in the core of Vagrant. Please note +that this list is not exhaustive and additional hooks can be added via plugins. + +- `environment_plugins_loaded` - called after the plugins have been loaded, + but before the configurations, provisioners, providers, etc. are loaded. + +* `environment_load` - called after the environment and all configurations are + fully loaded. + +- `environment_unload` - called after the environment is done being used. The + environment should not be used in this hook. + +* `machine_action_boot` - called after the hypervisor has reported the machine + was booted. + +- `machine_action_config_validate` - called after all `Vagrantfile`s have been + loaded, merged, and validated. + +* `machine_action_destroy` - called after the hypervisor has reported the + virtual machine is down. + +- `machine_action_halt` - called after the hypervisor has moved the machine + into a halted state (usually "stopped" but not "terminated"). + +* `machine_action_package` - called after Vagrant has successfully packaged a + new box. + +- `machine_action_provision` - called after all provisioners have executed. + +* `machine_action_read_state` - called after Vagrant has loaded state from + disk and the hypervisor. + +- `machine_action_reload` - called after a virtual machine is reloaded (varies + by hypervisor). + +* `machine_action_resume` - called after a virtual machine is moved from the + halted to up state. + +- `machine_action_run_command` - called after a command is executed on the + machine. + +* `machine_action_ssh` - called after an SSH connection has been established. + +- `machine_action_ssh_run` - called after an SSH command is executed. + +* `machine_action_start` - called after the machine has been started. + +- `machine_action_suspend` - called after the machine has been suspended. + +* `machine_action_sync_folders` - called after synced folders have been set up. + +- `machine_action_up` - called after the machine has entered the up state. + +## Private API + +You may find additional action hooks if you browse the Vagrant source code, but +only the list of action hooks here are guaranteed to persist between Vagrant +releases. Please do not rely on the internal API as it is subject to change +without notice. diff --git a/website/pages/docs/plugins/commands.html.md b/website/pages/docs/plugins/commands.html.md new file mode 100644 index 000000000..7941eb95e --- /dev/null +++ b/website/pages/docs/plugins/commands.html.md @@ -0,0 +1,135 @@ +--- +layout: 'docs' +page_title: 'Command Plugins - Plugin Development' +sidebar_current: 'plugins-commands' +description: |- + This page documents how to add new commands to Vagrant, invocable + via "vagrant YOUR-COMMAND". Prior to reading this, you should be familiar + with the plugin development basics. +--- + +# Plugin Development: Commands + +This page documents how to add new commands to Vagrant, invocable +via `vagrant YOUR-COMMAND`. Prior to reading this, you should be familiar +with the [plugin development basics](/docs/plugins/development-basics.html). + +
+ Warning: Advanced Topic! Developing plugins is an + advanced topic that only experienced Vagrant users who are reasonably + comfortable with Ruby should approach. +
+ +## Definition Component + +Within the context of a plugin definition, new commands can be defined +like so: + +```ruby +command "foo" do + require_relative "command" + Command +end +``` + +Commands are defined with the `command` method, which takes as an argument +the name of the command, in this case "foo." This means the command will be +invocable via `vagrant foo`. Then the block argument returns a class that +implements the `Vagrant.plugin(2, "command")` interface. + +You can also define _non-primary commands_. These commands do not show +up in the `vagrant -h` output. They only show up if the user explicitly +does a `vagrant list-commands` which shows the full listing of available +commands. This is useful for highly specific commands or plugins that a +beginner to Vagrant would not be using anyways. Vagrant itself uses non-primary +commands to expose some internal functions, as well. + +To define a non-primary command: + +```ruby +command("foo", primary: false) do + require_relative "command" + Command +end +``` + +## Implementation + +Implementations of commands should subclass `Vagrant.plugin(2, :command)`, +which is a Vagrant method that will return the proper superclass for +a version 2 command. The implementation itself is quite simple, since the +class needs to only implement a single method: `execute`. Example: + +```ruby +class Command < Vagrant.plugin(2, :command) + def execute + puts "Hello!" + 0 + end +end +``` + +The `execute` method is called when the command is invoked, and it should +return the exit status (0 for success, anything else for error). + +This is a command at its simplest form. Of course, the command superclass +gives you access to the Vagrant environment and provides some helpers to +do common tasks such as command line parsing. + +## Parsing Command-Line Options + +The `parse_options` method is available which will parse the command line +for you. It takes an [OptionParser](http://ruby-doc.org/stdlib-1.9.3/libdoc/optparse/rdoc/OptionParser.html) +as an argument, and adds some common elements to it such as the `--help` flag, +automatically showing help if requested. View the API docs directly for more +information. + +This is recommended over raw parsing/manipulation of command line flags. +The following is an example of parsing command line flags pulled directly +from the built-in Vagrant `destroy` command: + +```ruby +options = {} +options[:force] = false + +opts = OptionParser.new do |o| + o.banner = "Usage: vagrant destroy [vm-name]" + o.separator "" + + o.on("-f", "--force", "Destroy without confirmation.") do |f| + options[:force] = f + end +end + +# Parse the options +argv = parse_options(opts) +``` + +## Using Vagrant Machines + +The `with_target_vms` method is a helper that helps you interact with +the machines that Vagrant manages in a standard Vagrant way. This method +automatically does the right thing in the case of multi-machine environments, +handling target machines on the command line (`vagrant foo my-vm`), etc. +If you need to do any manipulation of a Vagrant machine, including SSH +access, this helper should be used. + +An example of using the helper, again pulled directly from the built-in +`destroy` command: + +```ruby +with_target_vms(argv, reverse: true) do |machine| + machine.action(:destroy) +end +``` + +In this case, it asks for the machines in reverse order and calls the +destroy action on each of them. If a user says `vagrant destroy foo`, then +the helper automatically only yields the `foo` machine. If no parameter +is given and it is a multi-machine environment, every machine in the environment +is yielded, and so on. It just does the right thing. + +## Using the Raw Vagrant Environment + +The raw loaded `Vagrant::Environment` object is available with the +'@env' instance variable. diff --git a/website/pages/docs/plugins/configuration.html.md b/website/pages/docs/plugins/configuration.html.md new file mode 100644 index 000000000..f41edb1c5 --- /dev/null +++ b/website/pages/docs/plugins/configuration.html.md @@ -0,0 +1,208 @@ +--- +layout: 'docs' +page_title: 'Custom Configuration - Plugin Development' +sidebar_current: 'plugins-configuration' +description: |- + This page documents how to add new configuration options to Vagrant, + settable with "config.YOURKEY" in Vagrantfiles. Prior to reading this, + you should be familiar with the plugin development basics. +--- + +# Plugin Development: Configuration + +This page documents how to add new configuration options to Vagrant, +settable with `config.YOURKEY` in Vagrantfiles. Prior to reading this, +you should be familiar with the +[plugin development basics](/docs/plugins/development-basics.html). + +
+ Warning: Advanced Topic! Developing plugins is an + advanced topic that only experienced Vagrant users who are reasonably + comfortable with Ruby should approach. +
+ +## Definition Component + +Within the context of a plugin definition, new configuration keys can be defined +like so: + +```ruby +config "foo" do + require_relative "config" + Config +end +``` + +Configuration keys are defined with the `config` method, which takes as an +argument the name of the configuration variable as the argument. This +means that the configuration object will be accessible via `config.foo` +in Vagrantfiles. Then, the block argument returns a class that implements +the `Vagrant.plugin(2, :config)` interface. + +## Implementation + +Implementations of configuration keys should subclass `Vagrant.plugin(2, :config)`, +which is a Vagrant method that will return the proper subclass for a version +2 configuration section. The implementation is very simple, and acts mostly +as a plain Ruby object. Here is an example: + +```ruby +class Config < Vagrant.plugin(2, :config) + attr_accessor :widgets + + def initialize + @widgets = UNSET_VALUE + end + + def finalize! + @widgets = 0 if @widgets == UNSET_VALUE + end +end +``` + +When using this configuration class, it looks like the following: + +```ruby +Vagrant.configure("2") do |config| + # ... + + config.foo.widgets = 12 +end +``` + +Easy. The only odd thing is the `UNSET_VALUE` bits above. This is actually +so that Vagrant can properly automatically merge multiple configurations. +Merging is covered in the next section, and `UNSET_VALUE` will be explained +there. + +## Merging + +Vagrant works by loading [multiple Vagrantfiles and merging them](/docs/vagrantfile/#load-order). +This merge logic is built-in to configuration classes. When merging two +configuration objects, we will call them "old" and "new", it'll by default +take all the instance variables defined on "new" that are not `UNSET_VALUE` +and set them onto the merged result. + +The reason `UNSET_VALUE` is used instead of Ruby's `nil` is because +it is possible that you want the default to be some value, and the user +actually wants to set the value to `nil`, and it is impossible for Vagrant +to automatically determine whether the user set the instance variable, or +if it was defaulted as nil. + +This merge logic is what you want almost every time. Hence, in the example +above, `@widgets` is set to `UNSET_VALUE`. If we had two Vagrant configuration +objects in the same file, then Vagrant would properly merge the follows. +The example below shows this: + +```ruby +Vagrant.configure("2") do |config| + config.widgets = 1 +end + +Vagrant.configure("2") do |config| + # ... other stuff +end + +Vagrant.configure("2") do |config| + config.widgets = 2 +end +``` + +If this were placed in a Vagrantfile, after merging, the value of widgets +would be "2". + +The `finalize!` method is called only once ever on the final configuration +object in order to set defaults. If `finalize!` is called, that configuration +will never be merged again, it is final. This lets you detect any `UNSET_VALUE` +and set the proper default, as we do in the above example. + +Of course, sometimes you want custom merge logic. Let us say we +wanted our widgets to be additive. We can override the `merge` method to +do this: + +```ruby +class Config < Vagrant.config("2", :config) + attr_accessor :widgets + + def initialize + @widgets = 0 + end + + def merge(other) + super.tap do |result| + result.widgets = @widgets + other.widgets + end + end +end +``` + +In this case, we did not use `UNSET_VALUE` for widgets because we did not +need that behavior. We default to 0 and always merge by summing the +two widgets. Now, if we ran the example above that had the 3 configuration +blocks, the final value of widgets would be "3". + +## Validation + +Configuration classes are also responsible for validating their own +values. Vagrant will call the `validate` method to do this. An example +validation method is shown below: + +```ruby +class Config < Vagrant.plugin("2", :config) + # ... + + def validate(machine) + errors = _detected_errors + if @widgets <= 5 + errors << "widgets must be greater than 5" + end + + { "foo" => errors } + end +end +``` + +The validation method is given a `machine` object, since validation is +done for each machine that Vagrant is managing. This allows you to +conditionally validate some keys based on the state of the machine and so on. + +The `_detected_errors` method returns any errors already detected by Vagrant, +such as unknown configuration keys. This returns an array of error messages, +so be sure to turn it into the proper Hash object to return later. + +The return value is a Ruby Hash object, where the key is a section name, +and the value is a list of error messages. These will be displayed by +Vagrant. The hash must not contain any values if there are no errors. + +## Accessing + +After all the configuration options are merged and finalized, you will likely +want to access the finalized value in your plugin. The initializer function +varies with each type of plugin, but _most_ plugins expose an initializer like +this: + +```ruby +def initialize(machine, config) + @machine = machine + @config = config +end +``` + +When authoring a plugin, simply call `super` in your initialize function to +setup these instance variables: + +```ruby +def initialize(*) + super + + @config.is_now_available + # ...existing code +end + +def my_helper + @config.is_here_too +end +``` + +For examples, take a look at Vagrant's own internal plugins in the `plugins` +folder in Vagrant's source on GitHub. diff --git a/website/pages/docs/plugins/development-basics.html.md b/website/pages/docs/plugins/development-basics.html.md new file mode 100644 index 000000000..18129f7dd --- /dev/null +++ b/website/pages/docs/plugins/development-basics.html.md @@ -0,0 +1,181 @@ +--- +layout: 'docs' +page_title: 'Plugin Development Basics - Plugins' +sidebar_current: 'plugins-development-basics' +description: |- + Plugins are a great way to augment or change the behavior and functionality + of Vagrant. Since plugins introduce additional external dependencies for + users, they should be used as a last resort when attempting to + do something with Vagrant. +--- + +# Plugin Development Basics + +Plugins are a great way to augment or change the behavior and functionality +of Vagrant. Since plugins introduce additional external dependencies for +users, they should be used as a last resort when attempting to +do something with Vagrant. + +But if you need to introduce custom behaviors +into Vagrant, plugins are the best way, since they are safe against future +upgrades and use a stable API. + +
+ Warning: Advanced Topic! Developing plugins is an + advanced topic that only experienced Vagrant users who are reasonably + comfortable with Ruby should approach. +
+ +Plugins are written using [Ruby](https://www.ruby-lang.org/en/) and are packaged +using [RubyGems](https://rubygems.org/). Familiarity with Ruby is required, +but the [packaging and distribution](/docs/plugins/packaging.html) section should help +guide you to packaging your plugin into a RubyGem. + +## Setup and Workflow + +Because plugins are packaged as RubyGems, Vagrant plugins should be +developed as if you were developing a regular RubyGem. The easiest +way to do this is to use the `bundle gem` command. + +Once the directory structure for a RubyGem is setup, you will want +to modify your Gemfile. Here is the basic structure of a Gemfile for +Vagrant plugin development: + +```ruby +source "https://rubygems.org" + +group :development do + gem "vagrant", git: "https://github.com/hashicorp/vagrant.git" +end + +group :plugins do + gem "my-vagrant-plugin", path: "." +end +``` + +This Gemfile gets "vagrant" for development. This allows you to +`bundle exec vagrant` to run Vagrant with your plugin already loaded, +so that you can test it manually that way. + +The only thing about this Gemfile that may stand out as odd is the +"plugins" group and putting your plugin in that group. Because +`vagrant plugin` commands do not work in development, this is how +you "install" your plugin into Vagrant. Vagrant will automatically +load any gems listed in the "plugins" group. Note that this also +allows you to add multiple plugins to Vagrant for development, if +your plugin works with another plugin. + +When you want to manually test your plugin, use +`bundle exec vagrant` in order to run Vagrant with your plugin +loaded (as we specified in the Gemfile). + +## Plugin Definition + +All plugins are required to have a definition. A definition contains details +about the plugin such as the name of it and what components it contains. + +A definition at the bare minimum looks like the following: + +```ruby +class MyPlugin < Vagrant.plugin("2") + name "My Plugin" +end +``` + +A definition is a class that inherits from `Vagrant.plugin("2")`. The "2" +there is the version that the plugin is valid for. API stability is only +promised for each major version of Vagrant, so this is important. (The +1.x series is working towards 2.0, so the API version is "2") + +**The most critical feature of a plugin definition** is that it must _always_ +load, no matter what version of Vagrant is running. Theoretically, Vagrant +version 87 (does not actually exist) would be able to load a version 2 plugin +definition. This is achieved through clever lazy loading of individual components +of the plugin, and is covered shortly. + +## Plugin Components + +Within the definition, a plugin advertises what components it adds to +Vagrant. An example is shown below where a command and provisioner are +added: + +```ruby +class MyPlugin < Vagrant.plugin("2") + name "My Plugin" + + command "run-my-plugin" do + require_relative "command" + Command + end + + provisioner "my-provisioner" do + require_relative "provisioner" + Provisioner + end +end +``` + +Let us go over the major pieces of what is going on here. Note from a general +Ruby language perspective the above _should_ be familiar. The syntax should +not scare you. If it does, then please familiarize with Ruby further before +attempting to write a plugin. + +The first thing to note is that individual components are defined by +making a method call with the component name, such as `command` or +`provisioner`. These in turn take some parameters. In the case of our +example it is just the name of the command and the name of the provisioner. +All component definitions then take a block argument (a callback) that +must return the actual component implementation class. + +The block argument is where the "clever lazy loading" (mentioned above) +comes into play. The component blocks should lazy load the actual file that +contains the implementation of the component, and then return that component. + +This is done because the actual dependencies and APIs used when defining +components are not stable across major Vagrant versions. A command implementation +written for Vagrant 2.0 will not be compatible with Vagrant 3.0 and so on. But +the _definition_ is just plain Ruby that must always be forward compatible +to future Vagrant versions. + +To repeat, **the lazy loading aspect of plugin components is critical** +to the way Vagrant plugins work. All components must be lazily loaded +and returned within their definition blocks. + +Now, each component has a different API. Please visit the relevant section +using the navigation to the left under "Plugins" to learn more about developing +each type of component. + +## Error Handling + +One of Vagrant's biggest strength is gracefully handling errors and reporting +them in human-readable ways. Vagrant has always strongly believed that if +a user sees a stack trace, it is a bug. It is expected that plugins will behave +the same way, and Vagrant provides strong error handling mechanisms to +assist with this. + +Error handling in Vagrant is done entirely by raising Ruby exceptions. +But Vagrant treats certain errors differently than others. If an error +is raised that inherits from `Vagrant::Errors::VagrantError`, then the +`vagrant` command will output the message of the error in nice red text +to the console and exit with an exit status of 1. + +Otherwise, Vagrant reports an "unexpected error" that should be reported +as a bug, and shows a full stack trace and other ugliness. Any stack traces +should be considered bugs. + +Therefore, to fit into Vagrant's error handling mechanisms, subclass +`VagrantError` and set a proper message on your exception. To see +examples of this, look at Vagrant's [built-in errors](https://github.com/hashicorp/vagrant/blob/master/lib/vagrant/errors.rb). + +## Console Input and Output + +Most plugins are likely going to want to do some sort of input/output. +Plugins should _never_ use Ruby's built-in `puts` or `gets` style methods. +Instead, all input/output should go through some sort of Vagrant UI object. +The Vagrant UI object properly handles cases where there is no TTY, output +pipes are closed, there is no input pipe, etc. + +A UI object is available on every `Vagrant::Environment` via the `ui` property +and is exposed within every middleware environment via the `:ui` key. UI +objects have [decent documentation](https://github.com/hashicorp/vagrant/blob/master/lib/vagrant/ui.rb) +within the comments of their source. diff --git a/website/pages/docs/plugins/guest-capabilities.html.md b/website/pages/docs/plugins/guest-capabilities.html.md new file mode 100644 index 000000000..3ac0c83b1 --- /dev/null +++ b/website/pages/docs/plugins/guest-capabilities.html.md @@ -0,0 +1,104 @@ +--- +layout: 'docs' +page_title: 'Guest Capabilities - Plugin Development' +sidebar_current: 'plugins-guestcapabilities' +description: |- + This page documents how to add new capabilities for guests to Vagrant, + allowing Vagrant to perform new actions on specific guest operating systems. + Prior to reading this, you should be familiar with the plugin development + basics. +--- + +# Plugin Development: Guest Capabilities + +This page documents how to add new capabilities for [guests](/docs/plugins/guests.html) +to Vagrant, allowing Vagrant to perform new actions on specific guest +operating systems. +Prior to reading this, you should be familiar +with the [plugin development basics](/docs/plugins/development-basics.html). + +
+ Warning: Advanced Topic! Developing plugins is an + advanced topic that only experienced Vagrant users who are reasonably + comfortable with Ruby should approach. +
+ +Guest capabilities augment [guests](/docs/plugins/guests.html) by attaching +specific "capabilities" to the guest, which are actions that can be performed +in the context of that guest operating system. + +The power of capabilities is that plugins can add new capabilities to +existing guest operating systems without modifying the core of Vagrant. +In earlier versions of Vagrant, all the guest logic was contained in the +core of Vagrant and was not easily augmented. + +## Definition Component + +Within the context of a plugin definition, guest capabilities can be +defined like so: + +```ruby +guest_capability "ubuntu", "my_custom_capability" do + require_relative "cap/my_custom_capability" + Cap::MyCustomCapability +end +``` + +Guest capabilities are defined by calling the `guest_capability` method, +which takes two parameters: the guest to add the capability to, and the +name of the capability itself. Then, the block argument returns a class +that implements a method named the same as the capability. This is +covered in more detail in the next section. + +## Implementation + +Implementations should be classes or modules that have a method with +the same name as the capability. The method must be immediately accessible +on the class returned from the `guest_capability` component, meaning that +if it is an instance method, an instance should be returned. + +In general, class methods are used for capabilities. For example, here +is the implementation for the capability above: + +```ruby +module Cap + class MyCustomCapability + def self.my_custom_capability(machine) + # implementation + end + end +end +``` + +All capabilities get the Vagrant machine object as the first argument. +Additional arguments are determined by the specific capability, so view the +documentation or usage of the capability you are trying to implement for more +information. + +Some capabilities must also return values back to the caller, so be aware +of that when implementing a capability. + +Capabilities always have access to communication channels such as SSH +on the machine, and the machine can generally be assumed to be booted. + +## Calling Capabilities + +Since you have access to the machine in every capability, capabilities can +also call _other_ capabilities. This is useful for using the inheritance +mechanism of capabilities to potentially ask helpers for more information. +For example, the "redhat" guest has a "network_scripts_dir" capability that +simply returns the directory where networking scripts go. + +Capabilities on child guests of RedHat such as CentOS or Fedora use this +capability to determine where networking scripts go, while sometimes overriding +it themselves. + +Capabilities can be called like so: + +```ruby +machine.guest.capability(:capability_name) +``` + +Any additional arguments given to the method will be passed on to the +capability, and the capability will return the value that the actual +capability returned. diff --git a/website/pages/docs/plugins/guests.html.md b/website/pages/docs/plugins/guests.html.md new file mode 100644 index 000000000..60c9502e0 --- /dev/null +++ b/website/pages/docs/plugins/guests.html.md @@ -0,0 +1,102 @@ +--- +layout: 'docs' +page_title: 'Custom Guests - Plugin Development' +sidebar_current: 'plugins-guests' +description: |- + This page documents how to add new guest OS detection to Vagrant, allowing + Vagrant to properly configure new operating systems. Prior to reading this, + you should be familiar with the plugin development basics. +--- + +# Plugin Development: Guests + +This page documents how to add new guest OS detection to Vagrant, allowing +Vagrant to properly configure new operating systems. +Prior to reading this, you should be familiar +with the [plugin development basics](/docs/plugins/development-basics.html). + +
+ Warning: Advanced Topic! Developing plugins is an + advanced topic that only experienced Vagrant users who are reasonably + comfortable with Ruby should approach. +
+ +Vagrant has many features that requires doing guest OS-specific +actions, such as mounting folders, configuring networks, etc. These +tasks vary from operating system to operating system. If you find that +one of these does not work for your operating system, then maybe the +guest implementation is incomplete or incorrect. + +## Definition Component + +Within the context of a plugin definition, new guests can be defined +like so: + +```ruby +guest "ubuntu" do + require_relative "guest" + Guest +end +``` + +Guests are defined with the `guest` method. The first argument is the +name of the guest. This name is not actually used anywhere, but may in the +future, so choose something helpful. Then, the block argument returns a +class that implements the `Vagrant.plugin(2, :guest)` interface. + +## Implementation + +Implementations of guests subclass `Vagrant.plugin("2", "guest")`. Within +this implementation, only the `detect?` method needs to be implemented. + +The `detect?` method is called by Vagrant at some point after the machine +is booted in order to determine what operating system the guest is running. +If you detect that it is your operating system, return `true` from `detect?`. +Otherwise, return `false`. + +Communication channels to the machine are guaranteed to be running at this +point, so the most common way to detect the operating system is to do +some basic testing: + +```ruby +class MyGuest < Vagrant.plugin("2", "guest") + def detect?(machine) + machine.communicate.test("cat /etc/myos-release") + end +end +``` + +After detecting an OS, that OS is used for various +[guest capabilities](/docs/plugins/guest-capabilities.html) that may be +required. + +## Guest Inheritance + +Vagrant also supports a form of inheritance for guests, since sometimes +operating systems stem from a common root. A good example of this is Linux +is the root of Debian, which further is the root of Ubuntu in many cases. +Inheritance allows guests to share a lot of common behavior while allowing +distro-specific overrides. + +Inheritance is not done via standard Ruby class inheritance because Vagrant +uses a custom [capability-based](/docs/plugins/guest-capabilities.html) system. +Vagrant handles inheritance dispatch for you. + +To subclass another guest, specify that guest's name as a second parameter +in the guest definition: + +```ruby +guest "ubuntu", "debian" do + require_relative "guest" + Guest +end +``` + +With the above component, the "ubuntu" guest inherits from "debian." When +a capability is looked up for "ubuntu", all capabilities from "debian" are +also available, and any capabilities in "ubuntu" override parent capabilities. + +When detecting operating systems with `detect?`, Vagrant always does a +depth-first search by searching the children operating systems before +checking their parents. Therefore, it is guaranteed in the above example +that the `detect?` method on "ubuntu" will be called before "debian." diff --git a/website/pages/docs/plugins/host-capabilities.html.md b/website/pages/docs/plugins/host-capabilities.html.md new file mode 100644 index 000000000..21fb92b26 --- /dev/null +++ b/website/pages/docs/plugins/host-capabilities.html.md @@ -0,0 +1,64 @@ +--- +layout: 'docs' +page_title: 'Host Capabilities - Plugin Development' +sidebar_current: 'plugins-hostcapabilities' +description: |- + This page documents how to add new capabilities for hosts to Vagrant, allowing Vagrant to perform new actions on specific host operating systems. Prior to reading this, you should be familiar with the plugin development basics. +--- + +# Plugin Development: Host Capabilities + +This page documents how to add new capabilities for [hosts](/docs/plugins/hosts.html) +to Vagrant, allowing Vagrant to perform new actions on specific host +operating systems. +Prior to reading this, you should be familiar +with the [plugin development basics](/docs/plugins/development-basics.html). + +
+ Warning: Advanced Topic! Developing plugins is an + advanced topic that only experienced Vagrant users who are reasonably + comfortable with Ruby should approach. +
+ +Host capabilities augment [hosts](/docs/plugins/hosts.html) by attaching +specific "capabilities" to the host, which are actions that can be performed +in the context of that host operating system. + +The power of capabilities is that plugins can add new capabilities to +existing host operating systems without modifying the core of Vagrant. +In earlier versions of Vagrant, all the host logic was contained in the +core of Vagrant and was not easily augmented. + +## Definition and Implementation + +The definition and implementation of host capabilities is identical +to [guest capabilities](/docs/plugins/guest-capabilities.html). + +The main difference from guest capabilities, however, is that instead of +taking a machine as the first argument, all host capabilities take an +instance of `Vagrant::Environment` as their first argument. + +Access to the environment allows host capabilities to access global state, +specific machines, and also allows them to call other host capabilities. + +## Calling Capabilities + +Since you have access to the environment in every capability, capabilities can +also call _other_ host capabilities. This is useful for using the inheritance +mechanism of capabilities to potentially ask helpers for more information. +For example, the "linux" guest has a "nfs_check_command" capability that +returns the command to use to check if NFS is running. + +Capabilities on child guests of Linux such as RedHat or Arch use this +capability to mostly inherit the Linux behavior, except for this minor +detail. + +Capabilities can be called like so: + +```ruby +environment.host.capability(:capability_name) +``` + +Any additional arguments given to the method will be passed on to the +capability, and the capability will return the value that the actual +capability returned. diff --git a/website/pages/docs/plugins/hosts.html.md b/website/pages/docs/plugins/hosts.html.md new file mode 100644 index 000000000..17895a153 --- /dev/null +++ b/website/pages/docs/plugins/hosts.html.md @@ -0,0 +1,99 @@ +--- +layout: 'docs' +page_title: 'Custom Hosts - Plugin Development' +sidebar_current: 'plugins-hosts' +description: |- + This page documents how to add new host OS detection to Vagrant, allowing + Vagrant to properly execute host-specific operations on new operating systems. + Prior to reading this, you should be familiar with the plugin development + basics. +--- + +# Plugin Development: Hosts + +This page documents how to add new host OS detection to Vagrant, allowing +Vagrant to properly execute host-specific operations on new operating systems. +Prior to reading this, you should be familiar +with the [plugin development basics](/docs/plugins/development-basics.html). + +
+ Warning: Advanced Topic! Developing plugins is an + advanced topic that only experienced Vagrant users who are reasonably + comfortable with Ruby should approach. +
+ +Vagrant has some features that require host OS-specific actions, such as +exporting NFS folders. These tasks vary from operating system to operating +system. Vagrant uses host detection as well as +[host capabilities](/docs/plugins/host-capabilities.html) to perform these +host OS-specific operations. + +## Definition Component + +Within the context of a plugin definition, new hosts can be defined +like so: + +```ruby +host "ubuntu" do + require_relative "host" + Host +end +``` + +Hosts are defined with the `host` method. The first argument is the +name of the host. This name is not actually used anywhere, but may in the +future, so choose something helpful. Then, the block argument returns a +class that implements the `Vagrant.plugin(2, :host)` interface. + +## Implementation + +Implementations of hosts subclass `Vagrant.plugin("2", "host")`. Within +this implementation, only the `detect?` method needs to be implemented. + +The `detect?` method is called by Vagrant very early on in its initialization +process to determine if the OS that Vagrant is running on is this host. +If you detect that it is your operating system, return `true` from `detect?`. +Otherwise, return `false`. + +```ruby +class MyHost < Vagrant.plugin("2", "host") + def detect?(environment) + File.file?("/etc/arch-release") + end +end +``` + +After detecting an OS, that OS is used for various +[host capabilities](/docs/plugins/host-capabilities.html) that may be +required. + +## Host Inheritance + +Vagrant also supports a form of inheritance for hosts, since sometimes +operating systems stem from a common root. A good example of this is Linux +is the root of Debian, which further is the root of Ubuntu in many cases. +Inheritance allows hosts to share a lot of common behavior while allowing +distro-specific overrides. + +Inheritance is not done via standard Ruby class inheritance because Vagrant +uses a custom [capability-based](/docs/plugins/host-capabilities.html) system. +Vagrant handles inheritance dispatch for you. + +To subclass another host, specify that host's name as a second parameter +in the host definition: + +```ruby +host "ubuntu", "debian" do + require_relative "host" + Host +end +``` + +With the above component, the "ubuntu" host inherits from "debian." When +a capability is looked up for "ubuntu", all capabilities from "debian" are +also available, and any capabilities in "ubuntu" override parent capabilities. + +When detecting operating systems with `detect?`, Vagrant always does a +depth-first search by searching the children operating systems before +checking their parents. Therefore, it is guaranteed in the above example +that the `detect?` method on "ubuntu" will be called before "debian." diff --git a/website/pages/docs/plugins/index.html.md b/website/pages/docs/plugins/index.html.md new file mode 100644 index 000000000..c5a8c778e --- /dev/null +++ b/website/pages/docs/plugins/index.html.md @@ -0,0 +1,27 @@ +--- +layout: 'docs' +page_title: 'Plugins' +sidebar_current: 'plugins' +description: |- + Vagrant comes with many great features out of the box to get your environments + up and running. Sometimes, however, you want to change the way Vagrant does + something or add additional functionality to Vagrant. This can be done via + Vagrant plugins. +--- + +# Plugins + +Vagrant comes with many great features out of the box to get your environments up +and running. Sometimes, however, you want to change the way Vagrant does something +or add additional functionality to Vagrant. This can be done via Vagrant +_plugins_. + +Plugins are powerful, first-class citizens that extend Vagrant using a +well-documented, stable API that can withstand major version upgrades. + +In fact, most of the core of Vagrant is [implemented using plugins](https://github.com/hashicorp/vagrant/tree/master/plugins). +Since Vagrant [dogfoods](https://en.wikipedia.org/wiki/Eating_your_own_dog_food) its own +plugin API, you can be confident that the interface is stable and well supported. + +Use the navigation on the left below the "Plugins" section to learn more +about how to use and build your own plugins. diff --git a/website/pages/docs/plugins/packaging.html.md b/website/pages/docs/plugins/packaging.html.md new file mode 100644 index 000000000..b1a2235ed --- /dev/null +++ b/website/pages/docs/plugins/packaging.html.md @@ -0,0 +1,114 @@ +--- +layout: 'docs' +page_title: 'Packaging and Distribution - Plugin Development' +sidebar_current: 'plugins-packaging' +description: |- + This page documents how to organize the file structure of your plugin + and distribute it so that it is installable using standard installation + methods. Prior to reading this, you should be familiar with the plugin + development basics. +--- + +# Plugin Development: Packaging & Distribution + +This page documents how to organize the file structure of your plugin +and distribute it so that it is installable using +[standard installation methods](/docs/plugins/usage.html). +Prior to reading this, you should be familiar +with the [plugin development basics](/docs/plugins/development-basics.html). + +
+ Warning: Advanced Topic! Developing plugins is an + advanced topic that only experienced Vagrant users who are reasonably + comfortable with Ruby should approach. +
+ +## Example Plugin + +The best way to describe packaging and distribution is to look at +how another plugin does it. The best example plugin available for this +is [vagrant-aws](https://github.com/mitchellh/vagrant-aws). + +By using [Bundler](http://bundler.io) and Rake, building a new +vagrant-aws package is easy. By simply calling `rake package`, a +`gem` file is dropped into the directory. By calling `rake release`, +the gem is built and it is uploaded to the central [RubyGems](https://rubygems.org) +repository so that it can be installed using `vagrant plugin install`. + +Your plugin can and should be this easy, too, since you basically +get this for free by using Bundler. + +## Setting Up Your Project + +To setup your project, run `bundle gem vagrant-my-plugin`. This will create a +`vagrant-my-plugin` directory that has the initial layout to be a RubyGem. + +You should modify the `vagrant-my-plugin.gemspec` file to add any +dependencies and change any metadata. View the [vagrant-aws.gemspec](https://github.com/mitchellh/vagrant-aws/blob/master/vagrant-aws.gemspec) +for a good example. + +
+

+ Do not depend on Vagrant for your gem. Vagrant + is no longer distributed as a gem, and you can assume that it will + always be available when your plugin is installed. +

+
+ +Once the directory structure for a RubyGem is setup, you will want +to modify your Gemfile. Here is the basic structure of a Gemfile for +Vagrant plugin development: + +```ruby +source "https://rubygems.org" + +group :development do + gem "vagrant", git: "https://github.com/hashicorp/vagrant.git" +end + +group :plugins do + gem "my-vagrant-plugin", path: "." +end +``` + +This Gemfile gets "vagrant" for development. This allows you to +`bundle exec vagrant` to run Vagrant with your plugin already loaded, +so that you can test it manually that way. + +The only thing about this Gemfile that may stand out as odd is the +"plugins" group and putting your plugin in that group. Because +`vagrant plugin` commands do not work in development, this is how +you "install" your plugin into Vagrant. Vagrant will automatically +load any gems listed in the "plugins" group. Note that this also +allows you to add multiple plugins to Vagrant for development, if +your plugin works with another plugin. + +Next, create a `Rakefile` that has at the very least, the following +contents: + +```ruby +require "rubygems" +require "bundler/setup" +Bundler::GemHelper.install_tasks +``` + +If you run `rake -T` now, which lists all the available rake tasks, +you should see that you have the `package` and `release` tasks. You +can now develop your plugin and build it! + +You can view the [vagrant-aws Rakefile](https://github.com/mitchellh/vagrant-aws/blob/master/Rakefile) +for a more comprehensive example that includes testing. + +## Testing Your Plugin + +To manually test your plugin during development, use +`bundle exec vagrant` to execute Vagrant with your plugin loaded +(thanks to the Gemfile setup we did earlier). + +For automated testing, the +[vagrant-spec](https://github.com/hashicorp/vagrant-spec) +project provides helpers for both unit and acceptance testing +plugins. See the giant README for that project for a detailed +description of how to integrate vagrant-spec into your project. +Vagrant itself (and all of its core plugins) use vagrant-spec +for automated testing. diff --git a/website/pages/docs/plugins/providers.html.md b/website/pages/docs/plugins/providers.html.md new file mode 100644 index 000000000..278c6cdc5 --- /dev/null +++ b/website/pages/docs/plugins/providers.html.md @@ -0,0 +1,237 @@ +--- +layout: 'docs' +page_title: 'Custom Providers - Plugin Development' +sidebar_current: 'plugins-providers' +description: |- + This page documents how to add support for new providers to Vagrant, allowing + Vagrant to run and manage machines powered by a system other than VirtualBox. + Prior to reading this, you should be familiar with the plugin development + basics. +--- + +# Plugin Development: Providers + +This page documents how to add support for new [providers](/docs/providers/) +to Vagrant, allowing Vagrant to run and manage machines powered by a +system other than VirtualBox. Prior to reading this, you should be familiar +with the [plugin development basics](/docs/plugins/development-basics.html). + +Prior to developing a provider you should also be familiar with how +[providers work](/docs/providers/) from +a user standpoint. + +
+ Warning: Advanced Topic! Developing plugins is an + advanced topic that only experienced Vagrant users who are reasonably + comfortable with Ruby should approach. +
+ +## Example Provider: AWS + +The best way to learn how to write a provider is to see how one is +written in practice. To augment this documentation, please heavily +study the [vagrant-aws](https://github.com/mitchellh/vagrant-aws) plugin, +which implements an AWS provider. The plugin is a good example of how to +structure, test, and implement your plugin. + +## Definition Component + +Within the context of a plugin definition, new providers are defined +like so: + +```ruby +provider "my_cloud" do + require_relative "provider" + Provider +end +``` + +Providers are defined with the `provider` method, which takes a single +argument specifying the name of the provider. This is the name that is +used with `vagrant up` to specify the provider. So in the case above, +our provider would be used by calling `vagrant up --provider=my_cloud`. + +The block argument then lazily loads and returns a class that +implements the `Vagrant.plugin(2, :provider)` interface, which is covered +next. + +## Provider Class + +The provider class should subclass and implement +`Vagrant.plugin(2, :provider)` which is an upgrade-safe way to let Vagrant +return the proper parent class. + +This class and the methods that need to be implemented are +[very well documented](https://github.com/hashicorp/vagrant/blob/master/lib/vagrant/plugin/v2/provider.rb). The documentation done on the class in the comments should be +enough to understand what needs to be done. + +Viewing the [AWS provider class](https://github.com/mitchellh/vagrant-aws/blob/master/lib/vagrant-aws/provider.rb) as well as the +[overall structure of the plugin](https://github.com/mitchellh/vagrant-aws) is recommended as a strong getting started point. + +Instead of going in depth over each method that needs to be implemented, +the documentation will cover high-level but important points to help you +create your provider. + +## Box Format + +Each provider is responsible for having its own box format. This is +actually an extremely simple step due to how generic boxes are. Before +explaining you should get familiar with the general +[box file format](/docs/boxes/format.html). + +The only requirement for your box format is that the `metadata.json` +file have a `provider` key which matches the name of your provider you +chose above. + +In addition to this, you may put any data in the metadata as well +as any files in the archive. Since Vagrant core itself does not care, +it is up to your provider to handle the data of the box. Vagrant core +just handles unpacking and verifying the box is for the proper +provider. + +As an example of a couple box formats that are actually in use: + +- The `virtualbox` box format is just a flat directory of the contents + of a `VBoxManage export` command. + +- The `vmware_fusion` box format is just a flat directory of the + contents of a `vmwarevm` folder, but only including the bare essential + files for VMware to function. + +- The `aws` box format is just a Vagrantfile defaulting some configuration. + You can see an [example aws box unpacked here](https://github.com/mitchellh/vagrant-aws/tree/master/example_box). + +Before anything with your provider is even written, you can verify +your box format works by doing `vagrant box add` with it. When you do +a `vagrant box list` you can see what boxes for what providers are installed. + +You do _not need_ the provider plugin installed to add a box for that +provider. + + + +## Actions + +Probably the most important concept to understand when building a +provider is the provider "action" interface. It is the secret sauce that +makes providers do the magic they do. + +Actions are built on top of the concept of +[middleware](https://github.com/mitchellh/middleware), which +allow providers to execute multiple distinct steps, have error recovery +mechanics, as well as before/after behaviors, and much more. + +Vagrant core requests specific actions from your provider through the +`action` method on your provider class. The full list of actions requested +is listed in the comments of that method on the superclass. If your +provider does not implement a certain action, then Vagrant core will show +a friendly error, so do not worry if you miss any, things will not explode +or crash spectacularly. + +Take a look at how the VirtualBox provider +[uses actions to build up complicated multi-step processes](https://github.com/hashicorp/vagrant/blob/master/plugins/providers/virtualbox/action.rb#L287). The AWS provider [uses a similar process](https://github.com/mitchellh/vagrant-aws/blob/master/lib/vagrant-aws/action.rb). + +## Built-in Middleware + +To assist with common tasks, Vagrant ships with a set of +[built-in middleware](https://github.com/hashicorp/vagrant/tree/master/lib/vagrant/action/builtin). Each of the middleware is well commented on the behavior and options +for each, and using these built-in middleware is critical to building +a well-behaved provider. + +These built-in middleware can be thought of as a standard library for +your actions on your provider. The core VirtualBox provider uses these +built-in middleware heavily. + +## Persisting State + +In the process of creating and managing a machine, providers generally need +to store some sort of state somewhere. Vagrant provides each machine with +a directory to store this state. + +As a use-case example for this, the VirtualBox provider stores the UUID +of the VirtualBox virtual machine created. This allows the provider to track +whether the machine is created, running, suspended, etc. + +The VMware provider actually copies the entire virtual machine into this +state directory, complete with virtual disk drives and everything. + +The directory is available from the `data_dir` attribute of the `Machine` +instance given to initialize your provider. Within middleware actions, the +machine is always available via the `:machine` key on the environment. The +`data_dir` attribute is a Ruby [Pathname](http://www.ruby-doc.org/stdlib-1.9.3/libdoc/pathname/rdoc/Pathname.html) object. + +It is important for providers to carefully manage all the contents of +this directory. Vagrant core itself does little to clean up this directory. +Therefore, when a machine is destroyed, be sure to clean up all the state +from this directory. + +## Configuration + +Vagrant supports [provider-specific configuration](/docs/providers/configuration.html), +allowing for users to finely tune and control specific providers from +Vagrantfiles. It is easy for your custom provider to expose custom configuration +as well. + +Provider-specific configuration is a special case of a normal +[configuration plugin](/docs/plugins/configuration.html). When defining the +configuration component, name the configuration the same as the provider, +and as a second parameter, specify `:provider`, like so: + +```ruby +config("my_cloud", :provider) do + require_relative "config" + Config +end +``` + +As long as the name matches your provider, and the second `:provider` +parameter is given, Vagrant will automatically expose this as provider-specific +configuration for your provider. Users can now do the following in their +Vagrantfiles: + +```ruby +config.vm.provider :my_cloud do |config| + # Your specific configuration! +end +``` + +The configuration class returned from the `config` component in the plugin +is the same as any other [configuration plugin](/docs/plugins/configuration.html), +so read that page for more information. Vagrant automatically handles +configuration validation and such just like any other configuration piece. + +The provider-specific configuration is available on the machine object +via the `provider_config` attribute. So within actions or your provider class, +you can access the config via `machine.provider_config`. + +
+ Best practice: Your provider should not require + provider-specific configuration to function, if possible. Vagrant + practices a strong convention over configuration + philosophy. When a user installs your provider, they should ideally + be able to vagrant up --provider=your_provider and + have it just work. +
+ +## Parallelization + +Vagrant supports parallelizing some actions, such as `vagrant up`, if the +provider explicitly supports it. By default, Vagrant will not parallelize a +provider. + +When parallelization is enabled, multiple [actions](#actions) may be run +in parallel. Therefore, providers must be certain that their action stacks +are thread-safe. The core of Vagrant itself (such as box collections, SSH, +etc.) is thread-safe. + +Providers can explicitly enable parallelization by setting the `parallel` +option on the provider component: + +```ruby +provider("my_cloud", parallel: true) do + require_relative "provider" + Provider +end +``` + +That is the only change that is needed to enable parallelization. diff --git a/website/pages/docs/plugins/provisioners.html.md b/website/pages/docs/plugins/provisioners.html.md new file mode 100644 index 000000000..ad5b63182 --- /dev/null +++ b/website/pages/docs/plugins/provisioners.html.md @@ -0,0 +1,68 @@ +--- +layout: 'docs' +page_title: 'Custom Provisioners - Plugin Development' +sidebar_current: 'plugins-provisioners' +script: |- + This page documents how to add new provisioners to Vagrant, allowing Vagrant + to automatically install software and configure software using a custom + provisioner. Prior to reading this, you should be familiar with the plugin + development basics. +--- + +# Plugin Development: Provisioners + +This page documents how to add new [provisioners](/docs/provisioning/) to Vagrant, +allowing Vagrant to automatically install software and configure software +using a custom provisioner. Prior to reading this, you should be familiar +with the [plugin development basics](/docs/plugins/development-basics.html). + +
+ Warning: Advanced Topic! Developing plugins is an + advanced topic that only experienced Vagrant users who are reasonably + comfortable with Ruby should approach. +
+ +## Definition Component + +Within the context of a plugin definition, new provisioners can be defined +like so: + +```ruby +provisioner "custom" do + require_relative "provisioner" + Provisioner +end +``` + +Provisioners are defined with the `provisioner` method, which takes a +single argument specifying the name of the provisioner. This is the +name that used with `config.vm.provision` when configuring and enabling +the provisioner. So in the case above, the provisioner would be enabled +using `config.vm.provision :custom`. + +The block argument then lazily loads and returns a class that implements +the `Vagrant.plugin(2, :provisioner)` interface, which is covered next. + +## Provisioner Class + +The provisioner class should subclass and implement +`Vagrant.plugin(2, :provisioner)` which is an upgrade-safe way to let +Vagrant return the proper parent class for provisioners. + +This class and the methods that need to be implemented are +[very well documented](https://github.com/hashicorp/vagrant/blob/master/lib/vagrant/plugin/v2/provisioner.rb). +The documentation on the class in the comments should be enough +to understand what needs to be done. + +There are two main methods that need to be implemented: the +`configure` method and the `provision` method. + +The `configure` method is called early in the machine booting process +to allow the provisioner to define new configuration on the machine, such +as sharing folders, defining networks, etc. As an example, the +[Chef solo provisioner](https://github.com/hashicorp/vagrant/blob/master/plugins/provisioners/chef/provisioner/chef_solo.rb#L24) +uses this to define shared folders. + +The `provision` method is called when the machine is booted and ready +for SSH connections. In this method, the provisioner should execute +any commands that need to be executed. diff --git a/website/pages/docs/plugins/usage.html.md b/website/pages/docs/plugins/usage.html.md new file mode 100644 index 000000000..924ef1aa6 --- /dev/null +++ b/website/pages/docs/plugins/usage.html.md @@ -0,0 +1,74 @@ +--- +layout: 'docs' +page_title: 'Plugin Usage - Plugins' +sidebar_current: 'plugins-usage' +description: |- + Installing a Vagrant plugin is easy, and should not take more than a few + seconds. +--- + +# Plugin Usage + +Installing a Vagrant plugin is easy, and should not take more than a few seconds. + +Please refer to the documentation of any plugin you plan on using for +more information on how to use it, but there is one common method for +installation and plugin activation. + +
+ Warning! 3rd party plugins can introduce instabilities + into Vagrant due to the nature of them being written by non-core users. +
+ +## Installation + +Plugins are installed using `vagrant plugin install`: + +```shell +# Installing a plugin from a known gem source +$ vagrant plugin install my-plugin + +# Installing a plugin from a local file source +$ vagrant plugin install /path/to/my-plugin.gem +``` + +Once a plugin is installed, it will automatically be loaded by Vagrant. +Plugins which cannot be loaded should not crash Vagrant. Instead, +Vagrant will show an error message that a plugin failed to load. + +## Usage + +Once a plugin is installed, you should refer to the plugin's documentation +to see exactly how to use it. Plugins which add commands should be instantly +available via `vagrant`, provisioners should be available via +`config.vm.provision`, etc. + +**Note:** In the future, the `vagrant plugin` command will include a +subcommand that will document the components that each plugin installs. + +## Updating + +Plugins can be updated by running `vagrant plugin update`. This will +update every installed plugin to the latest version. You can update a +specific plugin by calling `vagrant plugin update NAME`. Vagrant will +output what plugins were updated and to what version. + +To determine the changes in a specific version of a plugin, refer to +the plugin's homepage (usually a GitHub page or similar). It is the +plugin author's responsibility to provide a change log if he or she +chooses to. + +## Uninstallation + +Uninstalling a plugin is as easy as installing it. Just use the +`vagrant plugin uninstall` command and the plugin will be removed. Example: + +```shell +$ vagrant plugin uninstall my-plugin +``` + +## Listing Plugins + +To view what plugins are installed into your Vagrant environment at +any time, use the `vagrant plugin list` command. This will list the plugins +that are installed along with their version. diff --git a/website/pages/docs/providers/basic_usage.html.md b/website/pages/docs/providers/basic_usage.html.md new file mode 100644 index 000000000..b0d79833f --- /dev/null +++ b/website/pages/docs/providers/basic_usage.html.md @@ -0,0 +1,111 @@ +--- +layout: 'docs' +page_title: 'Basic Usage - Providers' +sidebar_current: 'providers-basic-usage' +description: |- + Vagrant boxes are all provider-specific. A box for VirtualBox is incompatible + with the VMware Fusion provider, or any other provider. A box must be + installed for each provider, and can share the same name as other boxes as + long as the providers differ. So you can have both a VirtualBox and VMware + Fusion "bionic64" box. +--- + +# Basic Provider Usage + +## Boxes + +Vagrant boxes are all provider-specific. A box for VirtualBox is incompatible +with the VMware Fusion provider, or any other provider. A box must be installed +for each provider, and can share the same name as other boxes as long +as the providers differ. So you can have both a VirtualBox and VMware Fusion +"bionic64" box. + +Installing boxes has not changed at all: + +``` +$ vagrant box add hashicorp/bionic64 +``` + +Vagrant now automatically detects what provider a box is for. This is +visible when listing boxes. Vagrant puts the provider in parentheses next +to the name, as can be seen below. + +``` +$ vagrant box list +bionic64 (virtualbox) +bionic64 (vmware_fusion) +``` + +## Vagrant Up + +Once a provider is installed, you can use it by calling `vagrant up` +with the `--provider` flag. This will force Vagrant to use that specific +provider. No other configuration is necessary! + +In normal day-to-day usage, the `--provider` flag is not necessary +since Vagrant can usually pick the right provider for you. More details +on how it does this is below. + +``` +$ vagrant up --provider=vmware_fusion +``` + +If you specified a `--provider` flag, you only need to do this for the +`up` command. Once a machine is up and running, Vagrant is able to +see what provider is backing a running machine, so commands such as +`destroy`, `suspend`, etc. do not need to be told what provider to use. + +
+ Vagrant currently restricts you to bringing up one provider per machine. + If you have a multi-machine environment, you can bring up one machine + backed by VirtualBox and another backed by VMware Fusion, for example, but you + cannot back the same machine with both VirtualBox and + VMware Fusion. This is a limitation that will be removed in a future + version of Vagrant. +
+ +## Default Provider + +As mentioned earlier, you typically do not need to specify `--provider` +_ever_. Vagrant is smart enough about being able to detect the provider +you want for a given environment. + +Vagrant attempts to find the default provider in the following order: + +1. The `--provider` flag on a `vagrant up` is chosen above all else, if + it is present. + +2. If the `VAGRANT_DEFAULT_PROVIDER` environmental variable is set, + it takes next priority and will be the provider chosen. + +3. Vagrant will go through all of the `config.vm.provider` calls in the + Vagrantfile and try each in order. It will choose the first provider + that is usable. For example, if you configure Hyper-V, it will never + be chosen on Mac this way. It must be both configured and usable. + +4. Vagrant will go through all installed provider plugins (including the + ones that come with Vagrant), and find the first plugin that reports + it is usable. There is a priority system here: systems that are known + better have a higher priority than systems that are worse. For example, + if you have the VMware provider installed, it will always take priority + over VirtualBox. + +5. If Vagrant still has not found any usable providers, it will error. + +Using this method, there are very few cases that Vagrant does not find the +correct provider for you. This also allows each +[Vagrantfile](/docs/vagrantfile/) to define what providers +the development environment is made for by ordering provider configurations. + +A trick is to use `config.vm.provider` with no configuration at the top of +your Vagrantfile to define the order of providers you prefer to support: + +```ruby +Vagrant.configure("2") do |config| + # ... other config up here + + # Prefer VMware Fusion before VirtualBox + config.vm.provider "vmware_fusion" + config.vm.provider "virtualbox" +end +``` diff --git a/website/pages/docs/providers/configuration.html.md b/website/pages/docs/providers/configuration.html.md new file mode 100644 index 000000000..c8b815909 --- /dev/null +++ b/website/pages/docs/providers/configuration.html.md @@ -0,0 +1,91 @@ +--- +layout: 'docs' +page_title: 'Configuration - Providers' +sidebar_current: 'providers-configuration' +description: |- + While well-behaved Vagrant providers should work with any Vagrantfile with + sane defaults, providers generally expose unique configuration options so that + you can get the most out of each provider +--- + +# Configuration + +While well-behaved Vagrant providers should work with any Vagrantfile with sane +defaults, providers generally expose unique configuration +options so that you can get the most out of each provider. + +This provider-specific configuration is done within the Vagrantfile +in a way that is portable, easy to use, and easy to understand. + +## Portability + +An important fact is that even if you configure other providers within +a Vagrantfile, the Vagrantfile remains portable even to individuals who +do not necessarily have that provider installed. + +For example, if you configure VMware Fusion and send it to an individual +who does not have the VMware Fusion provider, Vagrant will silently ignore +that part of the configuration. + +## Provider Configuration + +Configuring a specific provider looks like this: + +```ruby +Vagrant.configure("2") do |config| + # ... + + config.vm.provider "virtualbox" do |vb| + vb.customize ["modifyvm", :id, "--cpuexecutioncap", "50"] + end +end +``` + +Multiple `config.vm.provider` blocks can exist to configure multiple +providers. + +The configuration format should look very similar to how provisioners +are configured. The `config.vm.provider` takes a single parameter: the +name of the provider being configured. Then, an inner block with custom +configuration options is exposed that can be used to configure that +provider. + +This inner configuration differs among providers, so please read the +documentation for your provider of choice to see available configuration +options. + +Remember, some providers do not require any provider-specific configuration +and work directly out of the box. Provider-specific configuration is meant +as a way to expose more options to get the most of the provider of your +choice. It is not meant as a roadblock to running against a specific provider. + +## Overriding Configuration + +Providers can also override non-provider specific configuration, such +as `config.vm.box` and any other Vagrant configuration. This is done by +specifying a second argument to `config.vm.provider`. This argument is +just like the normal `config`, so set any settings you want, and they will +be overridden only for that provider. + +Example: + +```ruby +Vagrant.configure("2") do |config| + config.vm.box = "bionic64" + + config.vm.provider "vmware_fusion" do |v, override| + override.vm.box = "bionic64_fusion" + end +end +``` + +In the above case, Vagrant will use the "bionic64" box by default, but +will use "bionic64_fusion" if the VMware Fusion provider is used. + +
+ The Vagrant Way: The proper "Vagrant way" is to + avoid any provider-specific overrides if possible by making boxes + for multiple providers that are as identical as possible, since box + names can map to multiple providers. However, this is not always possible, + and in those cases, overrides are available. +
diff --git a/website/pages/docs/providers/custom.html.md b/website/pages/docs/providers/custom.html.md new file mode 100644 index 000000000..19faf13a2 --- /dev/null +++ b/website/pages/docs/providers/custom.html.md @@ -0,0 +1,13 @@ +--- +layout: 'docs' +page_title: 'Custom Provider - Providers' +sidebar_current: 'providers-custom' +description: |- + To learn how to make your own custom Vagrant providers, read the Vagrant + plugin development guide on creating custom providers. +--- + +# Custom Provider + +To learn how to make your own custom Vagrant providers, read the Vagrant plugin +development guide on [creating custom providers](/docs/plugins/providers.html). diff --git a/website/pages/docs/providers/default.html.md b/website/pages/docs/providers/default.html.md new file mode 100644 index 000000000..915476967 --- /dev/null +++ b/website/pages/docs/providers/default.html.md @@ -0,0 +1,29 @@ +--- +layout: 'docs' +page_title: 'Default Provider - Providers' +sidebar_current: 'providers-default' +description: |- + By default, VirtualBox is the default provider for Vagrant. VirtualBox is + still the most accessible platform to use Vagrant: it is free, cross-platform, + and has been supported by Vagrant for years. With VirtualBox as the default + provider, it provides the lowest friction for new users to get started with + Vagrant. +--- + +# Default Provider + +By default, VirtualBox is the default provider for Vagrant. VirtualBox is +still the most accessible platform to use Vagrant: it is free, cross-platform, +and has been supported by Vagrant for years. With VirtualBox as the default +provider, it provides the lowest friction for new users to get started with +Vagrant. + +However, you may find after using Vagrant for some time that you prefer +to use another provider as your default. In fact, this is quite common. +To make this experience better, Vagrant allows specifying the default +provider to use by setting the `VAGRANT_DEFAULT_PROVIDER` environmental +variable. + +Just set `VAGRANT_DEFAULT_PROVIDER` to the provider you wish to be the +default. For example, if you use Vagrant with VMware Fusion, you can set +the environmental variable to `vmware_desktop` and it will be your default. diff --git a/website/pages/docs/providers/index.html.md b/website/pages/docs/providers/index.html.md new file mode 100644 index 000000000..257492763 --- /dev/null +++ b/website/pages/docs/providers/index.html.md @@ -0,0 +1,28 @@ +--- +layout: 'docs' +page_title: 'Providers' +sidebar_current: 'providers' +description: |- + While Vagrant ships out of the box with support for VirtualBox, Hyper-V, and + Docker. Vagrant has the ability to manage other types of machines as well. + This is done by using other providers with Vagrant. +--- + +# Providers + +While Vagrant ships out of the box with support for [VirtualBox](https://www.virtualbox.org), +[Hyper-V](https://www.microsoft.com/hyper-v), and [Docker](https://www.docker.io), +Vagrant has the ability to manage other types of machines as well. This is done +by using other _providers_ with Vagrant. + +Alternate providers can offer different features that make more sense in your use case. +For example, if you are using Vagrant for any real work, [VMware](https://www.vmware.com) +providers are recommended since they're well supported and generally more +stable and performant than VirtualBox. + +Before you can use another provider, you must install it. Installation of other providers +is done via the Vagrant plugin system. + +Once the provider is installed, usage is straightforward and simple, as +you would expect with Vagrant. Read into the relevant subsections found in +the navigation to the left for more information. diff --git a/website/pages/docs/providers/installation.html.md b/website/pages/docs/providers/installation.html.md new file mode 100644 index 000000000..12181040c --- /dev/null +++ b/website/pages/docs/providers/installation.html.md @@ -0,0 +1,16 @@ +--- +layout: 'docs' +page_title: 'Installation - Providers' +sidebar_current: 'providers-installation' +description: |- + Providers are distributed as Vagrant plugins, and are therefore installed + using standard plugin installation steps. After installing a plugin which + contains a provider, the provider should immediately be available. +--- + +# Provider Installation + +Providers are distributed as Vagrant plugins, and are therefore installed +using [standard plugin installation steps](/docs/plugins/usage.html). After +installing a plugin which contains a provider, the provider should +immediately be available. diff --git a/website/pages/docs/provisioning/ansible.html.md b/website/pages/docs/provisioning/ansible.html.md new file mode 100644 index 000000000..0cf32ee68 --- /dev/null +++ b/website/pages/docs/provisioning/ansible.html.md @@ -0,0 +1,151 @@ +--- +layout: 'docs' +page_title: 'Ansible - Provisioning' +sidebar_current: 'provisioning-ansible-provisioner' +description: |- + The Vagrant Ansible provisioner allows you to provision the guest using + Ansible playbooks by executing "ansible-playbook" from the Vagrant host. +--- + +# Ansible Provisioner + +**Provisioner name: `ansible`** + +The Vagrant Ansible provisioner allows you to provision the guest using [Ansible](http://ansible.com) playbooks by executing **`ansible-playbook` from the Vagrant host**. + +
+ Warning: + If you are not familiar with Ansible and Vagrant already, we recommend starting with the shell provisioner. However, if you are comfortable with Vagrant already, Vagrant is a great way to learn Ansible. +
+ +## Setup Requirements + +- **[Install Ansible](https://docs.ansible.com/intro_installation.html#installing-the-control-machine) on your Vagrant host**. + +- Your Vagrant host should ideally provide a recent version of OpenSSH that [supports ControlPersist](https://docs.ansible.com/faq.html#how-do-i-get-ansible-to-reuse-connections-enable-kerberized-ssh-or-have-ansible-pay-attention-to-my-local-ssh-config-file). + +If installing Ansible directly on the Vagrant host is not an option in your development environment, you might be looking for the Ansible Local provisioner alternative. + +## Usage + +This page only documents the specific parts of the `ansible` (remote) provisioner. General Ansible concepts like Playbook or Inventory are shortly explained in the [introduction to Ansible and Vagrant](/docs/provisioning/ansible_intro.html). + +### Simplest Configuration + +To run Ansible against your Vagrant guest, the basic `Vagrantfile` configuration looks like: + +```ruby +Vagrant.configure("2") do |config| + + # + # Run Ansible from the Vagrant Host + # + config.vm.provision "ansible" do |ansible| + ansible.playbook = "playbook.yml" + end + +end +``` + +## Options + +This section lists the _specific_ options for the Ansible (remote) provisioner. In addition to the options listed below, this provisioner supports the [**common options** for both Ansible provisioners](/docs/provisioning/ansible_common.html). + +- `ask_become_pass` (boolean) - require Ansible to [prompt for a password](https://docs.ansible.com/intro_getting_started.html#remote-connection-information) when switching to another user with the [become/sudo mechanism](http://docs.ansible.com/ansible/become.html). + + The default value is `false`. + +- `ask_sudo_pass` (boolean) - Backwards compatible alias for the [ask_become_pass](#ask_become_pass) option. + +
+ Deprecation: + The `ask_sudo_pass` option is deprecated and will be removed in a future release. Please use the [**`ask_become_pass`**](#ask_become_pass) option instead. +
+ +- `ask_vault_pass` (boolean) - require Ansible to [prompt for a vault password](https://docs.ansible.com/playbooks_vault.html#vault). + + The default value is `false`. + +- `force_remote_user` (boolean) - require Vagrant to set the `ansible_ssh_user` setting in the generated inventory, or as an extra variable when a static inventory is used. All the Ansible `remote_user` parameters will then be overridden by the value of `config.ssh.username` of the [Vagrant SSH Settings](/docs/vagrantfile/ssh_settings.html). + + If this option is set to `false` Vagrant will set the Vagrant SSH username as a default Ansible remote user, but `remote_user` parameters of your Ansible plays or tasks will still be taken into account and thus override the Vagrant configuration. + + The default value is `true`. + +
+ Compatibility Note: + This option was introduced in Vagrant 1.8.0. Previous Vagrant versions behave like if this option was set to `false`. +
+ +- `host_key_checking` (boolean) - require Ansible to [enable SSH host key checking](https://docs.ansible.com/intro_getting_started.html#host-key-checking). + + The default value is `false`. + +- `raw_ssh_args` (array of strings) - require Ansible to apply a list of OpenSSH client options. + + Example: `['-o ControlMaster=no']`. + + It is an _unsafe wildcard_ that can be used to pass additional SSH settings to Ansible via `ANSIBLE_SSH_ARGS` environment variable, overriding any other SSH arguments (e.g. defined in an [`ansible.cfg` configuration file](https://docs.ansible.com/intro_configuration.html#ssh-args)). + +## Tips and Tricks + +### Ansible Parallel Execution + +Vagrant is designed to provision [multi-machine environments](/docs/multi-machine) in sequence, but the following configuration pattern can be used to take advantage of Ansible parallelism: + +```ruby +# Vagrant 1.7+ automatically inserts a different +# insecure keypair for each new VM created. The easiest way +# to use the same keypair for all the machines is to disable +# this feature and rely on the legacy insecure key. +# config.ssh.insert_key = false +# +# Note: +# As of Vagrant 1.7.3, it is no longer necessary to disable +# the keypair creation when using the auto-generated inventory. + +N = 3 +(1..N).each do |machine_id| + config.vm.define "machine#{machine_id}" do |machine| + machine.vm.hostname = "machine#{machine_id}" + machine.vm.network "private_network", ip: "192.168.77.#{20+machine_id}" + + # Only execute once the Ansible provisioner, + # when all the machines are up and ready. + if machine_id == N + machine.vm.provision :ansible do |ansible| + # Disable default limit to connect to all the machines + ansible.limit = "all" + ansible.playbook = "playbook.yml" + end + end + end +end +``` + +
+ Tip: + If you apply this parallel provisioning pattern with a static Ansible inventory, you will have to organize the things so that [all the relevant private keys are provided to the `ansible-playbook` command](https://github.com/hashicorp/vagrant/pull/5765#issuecomment-120247738). The same kind of considerations applies if you are using multiple private keys for a same machine (see [`config.ssh.private_key_path` SSH setting](/docs/vagrantfile/ssh_settings.html)). +
+ +### Force Paramiko Connection Mode + +The Ansible provisioner is implemented with native OpenSSH support in mind, and there is no official support for [paramiko](https://github.com/paramiko/paramiko/) (A native Python SSHv2 protocol library). + +If you really need to use this connection mode though, it is possible to enable paramiko as illustrated in the following configuration examples: + +With auto-generated inventory: + +```ruby +ansible.raw_arguments = ["--connection=paramiko"] +``` + +With a custom inventory, the private key must be specified (e.g. via an `ansible.cfg` configuration file, `--private-key` argument, or as part of your inventory file): + +```ruby +ansible.inventory_path = "./my-inventory" +ansible.raw_arguments = [ + "--connection=paramiko", + "--private-key=/home/.../.vagrant/machines/.../private_key" +] +``` diff --git a/website/pages/docs/provisioning/ansible_common.html.md b/website/pages/docs/provisioning/ansible_common.html.md new file mode 100644 index 000000000..d23db76e2 --- /dev/null +++ b/website/pages/docs/provisioning/ansible_common.html.md @@ -0,0 +1,210 @@ +--- +layout: 'docs' +page_title: 'Common Ansible Options - Provisioning' +sidebar_current: 'provisioning-ansible-common' +description: |- + This page details the common options to the Vagrant Ansible provisioners. +--- + +# Shared Ansible Options + +The following options are available to both Vagrant Ansible provisioners: + +- [`ansible`](/docs/provisioning/ansible.html) +- [`ansible_local`](/docs/provisioning/ansible_local.html) + +These options get passed to the `ansible-playbook` command that ships with Ansible, either via command line arguments or environment variables, depending on Ansible own capabilities. + +Some of these options are for advanced usage only and should not be used unless you understand their purpose. + +- `become` (boolean) - Perform all the Ansible playbook tasks [as another user](http://docs.ansible.com/ansible/become.html), different from the user used to log into the guest system. + + The default value is `false`. + +- `become_user` (string) - Set the default username to be used by the Ansible `become` [privilege escalation](http://docs.ansible.com/ansible/become.html) mechanism. + + By default this option is not set, and the Ansible default value (`root`) will be used. + +- `compatibility_mode` (string) - Set the **minimal** version of Ansible to be supported. Vagrant will only use parameters that are compatible with the given version. + + Possible values: + + - `"auto"` _(Vagrant will automatically select the optimal compatibility mode by checking the Ansible version currently available)_ + - `"1.8"` _(Ansible versions prior to 1.8 should mostly work well, but some options might not be supported)_ + - `"2.0"` _(The generated Ansible inventory will be incompatible with Ansible 1.x)_ + + By default this option is set to `"auto"`. If Vagrant is not able to detect any supported Ansible version, it will fall back on the compatibility mode `"1.8"` with a warning. + + Vagrant will error if the specified compatibility mode is incompatible with the current Ansible version. + +
+ Attention: + Vagrant doesn't perform any validation between the `compatibility_mode` value and the value of the [`version`](#version) option. +
+ +
+ Compatibility Note: + This option was introduced in Vagrant 2.0. The behavior of previous Vagrant versions can be simulated by setting the `compatibility_mode` to `"1.8"`. +
+ +- `config_file` (string) - The path to an [Ansible Configuration file](https://docs.ansible.com/intro_configuration.html). + + By default, this option is not set, and Ansible will [search for a possible configuration file in some default locations](/docs/provisioning/ansible_intro.html#ANSIBLE_CONFIG). + +- `extra_vars` (string or hash) - Pass additional variables (with highest priority) to the playbook. + + This parameter can be a path to a JSON or YAML file, or a hash. + + Example: + + ```ruby + ansible.extra_vars = { + ntp_server: "pool.ntp.org", + nginx: { + port: 8008, + workers: 4 + } + } + ``` + + These variables take the highest precedence over any other variables. + +- `galaxy_command` (template string) - The command pattern used to install Galaxy roles when `galaxy_role_file` is set. + + The following (optional) placeholders can be used in this command pattern: + + - `%{role_file}` is replaced by the absolute path to the `galaxy_role_file` option + - `%{roles_path}` is + - replaced by the absolute path to the `galaxy_roles_path` option when such option is defined, or + - replaced by the absolute path to a `roles` subdirectory sitting in the `playbook` parent directory. + + By default, this option is set to + + `ansible-galaxy install --role-file=%{role_file} --roles-path=%{roles_path} --force` + +- `galaxy_role_file` (string) - The path to the Ansible Galaxy role file. + + By default, this option is set to `nil` and Galaxy support is then disabled. + + Note: if an absolute path is given, the `ansible_local` provisioner will assume that it corresponds to the exact location on the guest system. + + ```ruby + ansible.galaxy_role_file = "requirements.yml" + ``` + +- `galaxy_roles_path` (string) - The path to the directory where Ansible Galaxy roles must be installed + + By default, this option is set to `nil`, which means that the Galaxy roles will be installed in a `roles` subdirectory located in the parent directory of the `playbook` file. + +- `groups` (hash) - Set of inventory groups to be included in the [auto-generated inventory file](/docs/provisioning/ansible_intro.html). + + Example: + + ```ruby + ansible.groups = { + "web" => ["vm1", "vm2"], + "db" => ["vm3"] + } + ``` + + Example with [group variables](https://docs.ansible.com/ansible/intro_inventory.html#group-variables): + + ```ruby + ansible.groups = { + "atlanta" => ["host1", "host2"], + "atlanta:vars" => {"ntp_server" => "ntp.atlanta.example.com", + "proxy" => "proxy.atlanta.example.com"} + } + ``` + + Notes: + + - Alphanumeric patterns are not supported (e.g. `db-[a:f]`, `vm[01:10]`). + - This option has no effect when the `inventory_path` option is defined. + +- `host_vars` (hash) - Set of inventory host variables to be included in the [auto-generated inventory file](https://docs.ansible.com/ansible/intro_inventory.html#host-variables). + + Example: + + ```ruby + ansible.host_vars = { + "host1" => {"http_port" => 80, + "maxRequestsPerChild" => 808, + "comments" => "text with spaces"}, + "host2" => {"http_port" => 303, + "maxRequestsPerChild" => 909} + } + ``` + + Note: This option has no effect when the `inventory_path` option is defined. + +- `inventory_path` (string) - The path to an Ansible inventory resource (e.g. a [static inventory file](https://docs.ansible.com/intro_inventory.html), a [dynamic inventory script](https://docs.ansible.com/intro_dynamic_inventory.html) or even [multiple inventories stored in the same directory](https://docs.ansible.com/intro_dynamic_inventory.html#using-multiple-inventory-sources)). + + By default, this option is disabled and Vagrant generates an inventory based on the `Vagrantfile` information. + +- `limit` (string or array of strings) - Set of machines or groups from the inventory file to further control which hosts [are affected](https://docs.ansible.com/glossary.html#limit-groups). + + The default value is set to the machine name (taken from `Vagrantfile`) to ensure that `vagrant provision` command only affect the expected machine. + + Setting `limit = "all"` can be used to make Ansible connect to all machines from the inventory file. + +- `playbook_command` (string) - The command used to run playbooks. + + The default value is `ansible-playbook` + +- `raw_arguments` (array of strings) - a list of additional `ansible-playbook` arguments. + + It is an _unsafe wildcard_ that can be used to apply Ansible options that are not (yet) supported by this Vagrant provisioner. As of Vagrant 1.7, `raw_arguments` has the highest priority and its values can potentially override or break other Vagrant settings. + + Examples: + + - `['--check', '-M', '/my/modules']` + - `["--connection=paramiko", "--forks=10"]` + +
+ Attention: + The `ansible` provisioner does not support whitespace characters in `raw_arguments` elements. Therefore **don't write** something like `["-c paramiko"]`, which will result with an invalid `" paramiko"` parameter value. +
+ +- `skip_tags` (string or array of strings) - Only plays, roles and tasks that [_do not match_ these values will be executed](https://docs.ansible.com/playbooks_tags.html). + +- `start_at_task` (string) - The task name where the [playbook execution will start](https://docs.ansible.com/playbooks_startnstep.html#start-at-task). + +- `sudo` (boolean) - Backwards compatible alias for the [`become`](#become) option. + +
+ Deprecation: + The `sudo` option is deprecated and will be removed in a future release. Please use the [**`become`**](#become) option instead. +
+ +- `sudo_user` (string) - Backwards compatible alias for the [`become_user`](#become_user) option. + +
+ Deprecation: + The `sudo_user` option is deprecated and will be removed in a future release. Please use the [**`become_user`**](#become_user) option instead. +
+ +- `tags` (string or array of strings) - Only plays, roles and tasks [tagged with these values will be executed](https://docs.ansible.com/playbooks_tags.html) . + +- `vault_password_file` (string) - The path of a file containing the password used by [Ansible Vault](https://docs.ansible.com/playbooks_vault.html#vault). + +- `verbose` (boolean or string) - Set Ansible's verbosity to obtain detailed logging + + Default value is `false` (minimal verbosity). + + Examples: `true` (equivalent to `v`), `-vvv` (equivalent to `vvv`), `vvvv`. + + Note that when the `verbose` option is enabled, the `ansible-playbook` command used by Vagrant will be displayed. + +- `version` (string) - The expected Ansible version. + + This option is disabled by default. + + When an Ansible version is defined (e.g. `"2.1.6.0"`), the Ansible provisioner will be executed only if Ansible is installed at the requested version. + + When this option is set to `"latest"`, no version check is applied. + +
+ Tip: + With the `ansible_local` provisioner, it is currently possible to use this option to specify which version of Ansible must be automatically installed, but only in combination with the [**`install_mode`**](/docs/provisioning/ansible_local.html#install_mode) set to `:pip`. +
diff --git a/website/pages/docs/provisioning/ansible_intro.html.md b/website/pages/docs/provisioning/ansible_intro.html.md new file mode 100644 index 000000000..da62379c8 --- /dev/null +++ b/website/pages/docs/provisioning/ansible_intro.html.md @@ -0,0 +1,260 @@ +--- +layout: 'docs' +page_title: 'Ansible - Short Introduction' +sidebar_current: 'provisioning-ansible' +description: |- + This page includes options and information that is applicable to both Vagrant + Ansible provisioners. +--- + +# Ansible and Vagrant + +The information below is applicable to both Vagrant Ansible provisioners: + +- [`ansible`](/docs/provisioning/ansible.html), where Ansible is executed on the **Vagrant host** +- [`ansible_local`](/docs/provisioning/ansible_local.html), where Ansible is executed on the **Vagrant guest** + +The list of common options for these two provisioners is documented in a [separate documentation page](/docs/provisioning/ansible_common.html). + +This documentation page will not go into how to use Ansible or how to write Ansible playbooks, since Ansible is a complete deployment and configuration management system that is beyond the scope of Vagrant documentation. + +To learn more about Ansible, please consult the [Ansible Documentation Site](https://docs.ansible.com/). + +## The Playbook File + +The first component of a successful Ansible provisioner setup is the Ansible playbook which contains the steps that should be run on the guest. Ansible's +[playbook documentation](https://docs.ansible.com/playbooks.html) goes into great detail on how to author playbooks, and there are a number of [best practices](https://docs.ansible.com/playbooks_best_practices.html) that can be applied to use Ansible's powerful features effectively. + +A playbook that installs and starts (or restarts) the NTP daemon via YUM looks like: + +``` +--- +- hosts: all + tasks: + - name: ensure ntpd is at the latest version + yum: pkg=ntp state=latest + notify: + - restart ntpd + handlers: + - name: restart ntpd + service: name=ntpd state=restarted +``` + +You can of course target other operating systems that do not have YUM by changing the playbook tasks. Ansible ships with a number of [modules](https://docs.ansible.com/modules.html) that make running otherwise tedious tasks dead simple. + +### Running Ansible + +The `playbook` option is strictly required by both Ansible provisioners ([`ansible`](/docs/provisioning/ansible.html) and [`ansible_local`](/docs/provisioning/ansible_local.html)), as illustrated in this basic `Vagrantfile` configuration: + +```ruby +Vagrant.configure("2") do |config| + + # Use :ansible or :ansible_local to + # select the provisioner of your choice + config.vm.provision :ansible do |ansible| + ansible.playbook = "playbook.yml" + end +end +``` + +Since an Ansible playbook can include many files, you may also collect the related files in a [directory structure](https://docs.ansible.com/playbooks_best_practices.html#directory-layout) like this: + +``` +. +|-- Vagrantfile +|-- provisioning +| |-- group_vars +| |-- all +| |-- roles +| |-- bar +| |-- foo +| |-- playbook.yml +``` + +In such an arrangement, the `ansible.playbook` path should be adjusted accordingly: + +```ruby +Vagrant.configure("2") do |config| + config.vm.provision "ansible" do |ansible| + ansible.playbook = "provisioning/playbook.yml" + end +end +``` + +## The Inventory File + +When using Ansible, it needs to know on which machines a given playbook should run. It does this by way of an [inventory](https://docs.ansible.com/intro_inventory.html) file which lists those machines. In the context of Vagrant, there are two ways to approach working with inventory files. + +### Auto-Generated Inventory + +The first and simplest option is to not provide one to Vagrant at all. Vagrant will generate an inventory file encompassing all of the virtual machines it manages, and use it for provisioning machines. + +#### Example with the [`ansible`](/docs/provisioning/ansible.html) provisioner + +``` +# Generated by Vagrant + +default ansible_ssh_host=127.0.0.1 ansible_ssh_port=2200 ansible_ssh_user='vagrant' ansible_ssh_private_key_file='/home/.../.vagrant/machines/default/virtualbox/private_key' +``` + +Note that the generated inventory file is stored as part of your local Vagrant environment in +`.vagrant/provisioners/ansible/inventory/vagrant_ansible_inventory`. + +#### Example with the [`ansible_local`](/docs/provisioning/ansible_local.html) provisioner + +``` +# Generated by Vagrant + +default ansible_connection=local +``` + +Note that the generated inventory file is uploaded to the guest VM in a subdirectory of [`tmp_path`](/docs/provisioning/ansible_local.html), e.g. `/tmp/vagrant-ansible/inventory/vagrant_ansible_local_inventory`. + +#### Host Variables + +As of Vagrant 1.8.0, the [`host_vars`](/docs/provisioning/ansible_common.html#host_vars) option can be used to set [variables for individual hosts](https://docs.ansible.com/ansible/intro_inventory.html#host-variables) in the generated inventory file (see also the notes on group variables below). + +With this configuration example: + +``` +Vagrant.configure("2") do |config| + config.vm.define "host1" + config.vm.define "host2" + config.vm.provision "ansible" do |ansible| + ansible.playbook = "playbook.yml" + ansible.host_vars = { + "host1" => {"http_port" => 80, + "maxRequestsPerChild" => 808}, + "host2" => {"http_port" => 303, + "maxRequestsPerChild" => 909} + } + end +end +``` + +Vagrant would generate the following inventory file: + +``` +# Generated by Vagrant + +host1 ansible_ssh_host=... http_port=80 maxRequestsPerChild=808 +host2 ansible_ssh_host=... http_port=303 maxRequestsPerChild=909 +``` + +#### Groups and Group Variables + +The [`groups`](/docs/provisioning/ansible_common.html#groups) option can be used to pass a hash of group names and group members to be included in the generated inventory file. + +As of Vagrant 1.8.0, it is also possible to specify [group variables](https://docs.ansible.com/ansible/intro_inventory.html#group-variables), and group members as [host ranges (with numeric or alphabetic patterns)](https://docs.ansible.com/ansible/intro_inventory.html#hosts-and-groups). + +With this configuration example: + +``` +Vagrant.configure("2") do |config| + + config.vm.box = "ubuntu/trusty64" + + config.vm.define "machine1" + config.vm.define "machine2" + + config.vm.provision "ansible" do |ansible| + ansible.playbook = "playbook.yml" + ansible.groups = { + "group1" => ["machine1"], + "group2" => ["machine2"], + "group3" => ["machine[1:2]"], + "group4" => ["other_node-[a:d]"], # silly group definition + "all_groups:children" => ["group1", "group2"], + "group1:vars" => {"variable1" => 9, + "variable2" => "example"} + } + end +end +``` + +Vagrant would generate the following inventory file: + +``` +# Generated by Vagrant + +machine1 ansible_ssh_host=127.0.0.1 ansible_ssh_port=2200 ansible_ssh_user='vagrant' ansible_ssh_private_key_file='/home/.../.vagrant/machines/machine1/virtualbox/private_key' +machine2 ansible_ssh_host=127.0.0.1 ansible_ssh_port=2222 ansible_ssh_user='vagrant' ansible_ssh_private_key_file='/home/.../.vagrant/machines/machine2/virtualbox/private_key' + +[group1] +machine1 + +[group2] +machine2 + +[group3] +machine[1:2] + +[group4] +other_node-[a:d] + +[all_groups:children] +group1 +group2 + +[group1:vars] +variable1=9 +variable2=example +``` + +**Notes:** + +- Prior to Vagrant 1.7.3, the `ansible_ssh_private_key_file` variable was not set in generated inventory, but passed as command line argument to `ansible-playbook` command. +- The generation of group variables blocks (e.g. `[group1:vars]`) is only possible since Vagrant 1.8.0. Note however that setting variables directly in the inventory is not the [preferred practice in Ansible](https://docs.ansible.com/intro_inventory.html#splitting-out-host-and-group-specific-data). If possible, group (or host) variables should be set in `YAML` files stored in the `group_vars/` or `host_vars/` directories in the playbook (or inventory) directory instead. +- Unmanaged machines and undefined groups are not added to the inventory, to avoid useless Ansible errors (e.g. _unreachable host_ or _undefined child group_) + + For example, `machine3` and `group3` in the example below would not be added to the generated inventory file: + + ```ruby + ansible.groups = { + "group1" => ["machine1"], + "group2" => ["machine2", "machine3"], + "all_groups:children" => ["group1", "group2", "group3"] + } + ``` + +- [Host range patterns (numeric and alphabetic ranges)](https://docs.ansible.com/ansible/intro_inventory.html#hosts-and-groups) will not be validated by Vagrant. As of Vagrant 1.8.0, host range patterns will be added as group members to the inventory anyway, this might lead to errors in Ansible (e.g _unreachable host_). + +### Static Inventory + +The second option is for situations where you would like to have more control over the inventory management. + +With the [`inventory_path`](/docs/provisioning/ansible_common.html#inventory_path) option, you can reference a specific inventory resource (e.g. a static inventory file, a [dynamic inventory script](https://docs.ansible.com/intro_dynamic_inventory.html) or even [multiple inventories stored in the same directory](https://docs.ansible.com/intro_dynamic_inventory.html#using-multiple-inventory-sources)). Vagrant will then use this inventory information instead of generating it. + +A very simple inventory file for use with Vagrant might look like: + +``` +default ansible_ssh_host=192.168.111.222 +``` + +Where the above IP address is one set in your Vagrantfile: + +``` +config.vm.network :private_network, ip: "192.168.111.222" +``` + +**Notes:** + +- The machine names in `Vagrantfile` and `ansible.inventory_path` files should correspond, unless you use `ansible.limit` option to reference the correct machines. +- The `ansible.inventory_path` option by default is only scoped to apply to a single guest in the inventory file, and does not apply to all defined guests. To allow access to all available machines in the inventory, it is necessary to set `ansible.limit = "all"`. +- The SSH host addresses (and ports) must obviously be specified twice, in `Vagrantfile` and `ansible.inventory_path` files. +- Sharing hostnames across Vagrant host and guests might be a good idea (e.g. with some Ansible configuration task, or with a plugin like [`vagrant-hostmanager`](https://github.com/smdahlen/vagrant-hostmanager)). + +### The Ansible Configuration File + +Certain settings in Ansible are (only) adjustable via a [configuration file](https://docs.ansible.com/intro_configuration.html), and you might want to ship such a file in your Vagrant project. + +When shipping an Ansible configuration file it is good to know that: + +- as of Ansible 1.5, the lookup order is the following: + - any path set as `ANSIBLE_CONFIG` environment variable + - `ansible.cfg` in the runtime working directory + - `.ansible.cfg` in the user home directory + - `/etc/ansible/ansible.cfg` +- Ansible commands don't look for a configuration file relative to the playbook file location (e.g. in the same directory) +- an `ansible.cfg` file located in the same directory as your `Vagrantfile` will be used by default. +- it is also possible to reference any other location with the [config_file](/docs/provisioning/ansible_common.html#config_file) provisioner option. In this case, Vagrant will set the `ANSIBLE_CONFIG` environment variable accordingly. diff --git a/website/pages/docs/provisioning/ansible_local.html.md b/website/pages/docs/provisioning/ansible_local.html.md new file mode 100644 index 000000000..1672612d8 --- /dev/null +++ b/website/pages/docs/provisioning/ansible_local.html.md @@ -0,0 +1,247 @@ +--- +layout: 'docs' +page_title: 'Ansible Local - Provisioning' +sidebar_current: 'provisioning-ansible-local' +description: |- + The Vagrant Ansible Local provisioner allows you to provision the guest using Ansible playbooks by executing "ansible-playbook" directly on the guest + machine. +--- + +# Ansible Local Provisioner + +**Provisioner name: `ansible_local`** + +The Vagrant Ansible Local provisioner allows you to provision the guest using [Ansible](http://ansible.com) playbooks by executing **`ansible-playbook` directly on the guest machine**. + +
+ Warning: + If you are not familiar with Ansible and Vagrant already, we recommend starting with the shell provisioner. However, if you are comfortable with Vagrant already, Vagrant is a great way to learn Ansible. +
+ +## Setup Requirements + +The main advantage of the Ansible Local provisioner in comparison to the [Ansible (remote) provisioner](/docs/provisioning/ansible.html) is that it does not require any additional software on your Vagrant host. + +On the other hand, [Ansible must obviously be installed](https://docs.ansible.com/intro_installation.html#installing-the-control-machine) on your guest machine(s). + +**Note:** By default, Vagrant will _try_ to automatically install Ansible if it is not yet present on the guest machine (see the `install` option below for more details). + +## Usage + +This page only documents the specific parts of the `ansible_local` provisioner. General Ansible concepts like Playbook or Inventory are shortly explained in the [introduction to Ansible and Vagrant](/docs/provisioning/ansible_intro.html). + +The Ansible Local provisioner requires that all the Ansible Playbook files are available on the guest machine, at the location referred by the `provisioning_path` option. Usually these files are initially present on the host machine (as part of your Vagrant project), and it is quite easy to share them with a Vagrant [Synced Folder](/docs/synced-folders/). + +### Simplest Configuration + +To run Ansible from your Vagrant guest, the basic `Vagrantfile` configuration looks like: + +```ruby +Vagrant.configure("2") do |config| + # Run Ansible from the Vagrant VM + config.vm.provision "ansible_local" do |ansible| + ansible.playbook = "playbook.yml" + end +end +``` + +**Requirements:** + +- The `playbook.yml` file is stored in your Vagrant's project home directory. + +- The [default shared directory](/docs/synced-folders/basic_usage.html) is enabled (`.` → `/vagrant`). + +## Options + +This section lists the _specific_ options for the Ansible Local provisioner. In addition to the options listed below, this provisioner supports the [**common options** for both Ansible provisioners](/docs/provisioning/ansible_common.html). + +- `install` (boolean) - Try to automatically install Ansible on the guest system. + + This option is enabled by default. + + Vagrant will try to install (or upgrade) Ansible when one of these conditions are met: + + - Ansible is not installed (or cannot be found). + - The [`version`](/docs/provisioning/ansible_common.html#version) option is set to `"latest"`. + - The current Ansible version does not correspond to the [`version`](/docs/provisioning/ansible_common.html#version) option. + +
+ Attention: + There is no guarantee that this automated installation will replace a custom Ansible setup, that might be already present on the Vagrant box. +
+ +- `install_mode` (`:default`, `:pip`, or `:pip_args_only`) - Select the way to automatically install Ansible on the guest system. + + - `:default`: Ansible is installed from the operating system package manager. This mode doesn't support `version` selection. For many platforms (e.g Debian, FreeBSD, OpenSUSE) the official package repository is used, except for the following Linux distributions: + + - On Ubuntu-like systems, the latest Ansible release is installed from the `ppa:ansible/ansible` repository. The compatibility is maintained only for active long-term support (LTS) versions. + - On RedHat-like systems, the latest Ansible release is installed from the [EPEL](http://fedoraproject.org/wiki/EPEL) repository. + + - `:pip`: Ansible is installed from [PyPI](https://pypi.python.org/pypi) with [pip](https://pip.pypa.io) package installer. With this mode, Vagrant will systematically try to [install the latest pip version](https://pip.pypa.io/en/stable/installing/#installing-with-get-pip-py). With the `:pip` mode you can optionally install a specific Ansible release by setting the [`version`](/docs/provisioning/ansible_common.html#version) option. + + Example: + + ```ruby + config.vm.provision "ansible_local" do |ansible| + ansible.playbook = "playbook.yml" + ansible.install_mode = "pip" + ansible.version = "2.2.1.0" + end + ``` + + With this configuration, Vagrant will install `pip` and then execute the command + + ```shell + sudo pip install --upgrade ansible==2.2.1.0 + ``` + + As-is `pip` is installed if needed via a default command which looks like + + ```shell + curl https://bootstrap.pypa.io/get-pip.py | sudo python + ``` + + This can be problematic in certain scenarios, for example, when behind a proxy. It is possible to override this default command by providing an explicit command to run as part of the config using `pip_install_cmd`. For example: + + ```ruby + config.vm.provision "ansible_local" do |ansible| + ansible.playbook = "playbook.yml" + ansible.install_mode = "pip" + ansible.pip_install_cmd = "https_proxy=http://your.proxy.server:port curl -s https://bootstrap.pypa.io/get-pip.py | sudo https_proxy=http/your.proxy.server:port python" + ansible.version = "2.2.1.0" + end + ``` + + In this case case `pip` will be installed via the command: + + ```shell + https_proxy=http://your.proxy.server:port curl -s https://bootstrap.pypa.io/get-pip.py | sudo https_proxy=http://your.proxy.server:porpython + ``` + + If `pip_install_cmd` is not provided in the config, then `pip` is installed via the default command. + + - `:pip_args_only`: This mode is very similar to the `:pip` mode, with the difference that in this case no pip arguments will be automatically set by Vagrant. + + Example: + + ```ruby + config.vm.provision "ansible_local" do |ansible| + ansible.playbook = "playbook.yml" + ansible.install_mode = "pip_args_only" + ansible.pip_args = "-r /vagrant/requirements.txt" + end + ``` + + With this configuration, Vagrant will install `pip` and then execute the command + + ```shell + sudo pip install -r /vagrant/requirements.txt + ``` + + The default value of `install_mode` is `:default`, and any invalid value for this option will silently fall back to the default value. + +- `pip_args` (string) - When Ansible is installed via pip, this option allows the definition of additional pip arguments to be passed along on the command line (for example, [`--index-url`](https://pip.pypa.io/en/stable/reference/pip_install/#cmdoption-i)). + + By default, this option is not set. + + Example: + + ```ruby + config.vm.provision "ansible_local" do |ansible| + ansible.playbook = "playbook.yml" + ansible.install_mode = :pip + ansible.pip_args = "--index-url https://pypi.internal" + end + ``` + + With this configuration, Vagrant will install `pip` and then execute the command + + ```shell + sudo pip install --index-url https://pypi.internal --upgrade ansible + ``` + +- `provisioning_path` (string) - An absolute path on the guest machine where the Ansible files are stored. The `ansible-galaxy` and `ansible-playbook` commands are executed from this directory. This is the location to place an [ansible.cfg](http://docs.ansible.com/ansible/intro_configuration.html) file, in case you need it. + + The default value is `/vagrant`. + +- `tmp_path` (string) - An absolute path on the guest machine where temporary files are stored by the Ansible Local provisioner. + + The default value is `/tmp/vagrant-ansible` + +## Tips and Tricks + +### Install Galaxy Roles in a path owned by root + +
+ Disclaimer: This tip is not a recommendation to install galaxy roles out of the vagrant user space, especially if you rely on ssh agent forwarding to fetch the roles. +
+ +Be careful that `ansible-galaxy` command is executed by default as vagrant user. Setting `galaxy_roles_path` to a folder like `/etc/ansible/roles` will fail, and `ansible-galaxy` will extract the role a second time in `/home/vagrant/.ansible/roles/`. Then if your playbook uses `become` to run as `root`, it will fail with a _"role was not found"_ error. + +To work around that, you can use `ansible.galaxy_command` to prepend the command with `sudo`, as illustrated in the example below: + +```ruby +Vagrant.configure(2) do |config| + config.vm.box = "centos/7" + config.vm.provision "ansible_local" do |ansible| + ansible.become = true + ansible.playbook = "playbook.yml" + ansible.galaxy_role_file = "requirements.yml" + ansible.galaxy_roles_path = "/etc/ansible/roles" + ansible.galaxy_command = "sudo ansible-galaxy install --role-file=%{role_file} --roles-path=%{roles_path} --force" + end +end +``` + +### Ansible Parallel Execution from a Guest + +With the following configuration pattern, you can install and execute Ansible only on a single guest machine (the `"controller"`) to provision all your machines. + +```ruby +Vagrant.configure("2") do |config| + + config.vm.box = "ubuntu/trusty64" + + config.vm.define "node1" do |machine| + machine.vm.network "private_network", ip: "172.17.177.21" + end + + config.vm.define "node2" do |machine| + machine.vm.network "private_network", ip: "172.17.177.22" + end + + config.vm.define 'controller' do |machine| + machine.vm.network "private_network", ip: "172.17.177.11" + + machine.vm.provision :ansible_local do |ansible| + ansible.playbook = "example.yml" + ansible.verbose = true + ansible.install = true + ansible.limit = "all" # or only "nodes" group, etc. + ansible.inventory_path = "inventory" + end + end + +end +``` + +You need to create a static `inventory` file that corresponds to your `Vagrantfile` machine definitions: + +``` +controller ansible_connection=local +node1 ansible_host=172.17.177.21 ansible_ssh_private_key_file=/vagrant/.vagrant/machines/node1/virtualbox/private_key +node2 ansible_host=172.17.177.22 ansible_ssh_private_key_file=/vagrant/.vagrant/machines/node2/virtualbox/private_key + +[nodes] +node[1:2] +``` + +And finally, you also have to create an [`ansible.cfg` file](https://docs.ansible.com/intro_configuration.html#openssh-specific-settings) to fully disable SSH host key checking. More SSH configurations can be added to the `ssh_args` parameter (e.g. agent forwarding, etc.) + +``` +[defaults] +host_key_checking = no + +[ssh_connection] +ssh_args = -o ControlMaster=auto -o ControlPersist=60s -o UserKnownHostsFile=/dev/null -o IdentitiesOnly=yes +``` diff --git a/website/pages/docs/provisioning/basic_usage.html.md b/website/pages/docs/provisioning/basic_usage.html.md new file mode 100644 index 000000000..ebf96a0dd --- /dev/null +++ b/website/pages/docs/provisioning/basic_usage.html.md @@ -0,0 +1,367 @@ +--- +layout: 'docs' +page_title: 'Basic Usage - Provisioning' +sidebar_current: 'provisioning-basic' +description: |- + While Vagrant offers multiple options for how you are able to provision + your machine, there is a standard usage pattern as well as some important + points common to all provisioners that are important to know. +--- + +# Basic Usage of Provisioners + +While Vagrant offers multiple options for how you are able to provision +your machine, there is a standard usage pattern as well as some important +points common to all provisioners that are important to know. + +## Options + +Every Vagrant provisioner accepts a few base options. The only required +option is what type a provisioner is: + +- `name` (string) - The name of the provisioner. Note: if no `type` option is given, + this option _must_ be the type of provisioner it is. If you wish to give it a + different name you must also set the `type` option to define the kind of provisioner. +- `type` (string) - The class of provisioner to configure. (i.e. `"shell"` or `"file"`) +- `before` (string or symbol) - The exact name of an already defined provisioner + that _this_ provisioner should run before. If defined as a symbol, its only valid + values are `:each` or `:all`, which makes the provisioner run before each and + every root provisioner, or before all provisioners respectively. + **Note**: This option is currently experimental, so it needs to be explicitly + enabled to work. More info can be found [here](/docs/experimental/index.html). +- `after` (string or symbol) - The exact name of an already defined provisioner + that _this_ provisioner should run after. If defined as a symbol, its only valid + values are `:each` or `:all`, which makes the provisioner run after each and + every root provisioner, or before all provisioners respectively. + **Note**: This option is currently experimental, so it needs to be explicitly + enabled to work. More info can be found [here](/docs/experimental/index.html). + +More information about how to use `before` and `after` options can be read [below](#dependency-provisioners). + +## Configuration + +First, every provisioner is configured within your +[Vagrantfile](/docs/vagrantfile/) +using the `config.vm.provision` method call. For example, the Vagrantfile +below enables shell provisioning: + +```ruby +Vagrant.configure("2") do |config| + # ... other configuration + + config.vm.provision "shell", inline: "echo hello" +end +``` + +Every provisioner has a type, such as `"shell"`, used as the first +parameter to the provisioning configuration. Following that is basic key/value +for configuring that specific provisioner. Instead of basic key/value, you +can also use a Ruby block for a syntax that is more like variable assignment. +The following is effectively the same as the prior example: + +```ruby +Vagrant.configure("2") do |config| + # ... other configuration + + config.vm.provision "shell" do |s| + s.inline = "echo hello" + end +end +``` + +The benefit of the block-based syntax is that with more than a couple options +it can greatly improve readability. Additionally, some provisioners, like +the Chef provisioner, have special methods that can be called within that +block to ease configuration that cannot be done with the key/value approach, +or you can use this syntax to pass arguments to a shell script. + +The attributes that can be set in a single-line are the attributes that +are set with the `=` style, such as `inline = "echo hello"` above. If the +style is instead more of a function call, such as `add_recipe "foo"`, then +this cannot be specified in a single line. + +Provisioners can also be named (since 1.7.0). These names are used cosmetically for output +as well as overriding provisioner settings (covered further below). An example +of naming provisioners is shown below: + +```ruby +Vagrant.configure("2") do |config| + # ... other configuration + + config.vm.provision "bootstrap", type: "shell" do |s| + s.inline = "echo hello" + end +end +``` + +Naming provisioners is simple. The first argument to `config.vm.provision` +becomes the name, and then a `type` option is used to specify the provisioner +type, such as `type: "shell"` above. + +## Running Provisioners + +Provisioners are run in three cases: the initial `vagrant up`, `vagrant provision`, and `vagrant reload --provision`. + +A `--no-provision` flag can be passed to `up` and `reload` if you do not +want to run provisioners. Likewise, you can pass `--provision` to force +provisioning. + +The `--provision-with` flag can be used if you only want to run a +specific provisioner if you have multiple provisioners specified. For +example, if you have a shell and Puppet provisioner and only want to +run the shell one, you can do `vagrant provision --provision-with shell`. +The arguments to `--provision-with` can be the provisioner type (such as +"shell") or the provisioner name (such as "bootstrap" from above). + +## Run Once, Always or Never + +By default, provisioners are only run once, during the first `vagrant up` +since the last `vagrant destroy`, unless the `--provision` flag is set, +as noted above. + +Optionally, you can configure provisioners to run on every `up` or +`reload`. They will only be not run if the `--no-provision` flag is +explicitly specified. To do this set the `run` option to "always", +as shown below: + +```ruby +Vagrant.configure("2") do |config| + config.vm.provision "shell", inline: "echo hello", + run: "always" +end +``` + +You can also set `run:` to `"never"` if you have an optional provisioner +that you want to mention to the user in a "post up message" or that +requires some other configuration before it is possible, then call this +with `vagrant provision --provision-with bootstrap`. + +If you are using the block format, you must specify it outside +of the block, as shown below: + +```ruby +Vagrant.configure("2") do |config| + config.vm.provision "bootstrap", type: "shell", run: "never" do |s| + s.inline = "echo hello" + end +end +``` + +## Multiple Provisioners + +Multiple `config.vm.provision` methods can be used to define multiple +provisioners. These provisioners will be run in the order they're defined. +This is useful for a variety of reasons, but most commonly it is used so +that a shell script can bootstrap some of the system so that another provisioner +can take over later. + +If you define provisioners at multiple "scope" levels (such as globally +in the configuration block, then in a +[multi-machine](/docs/multi-machine/) definition, then maybe +in a [provider-specific override](/docs/providers/configuration.html)), +then the outer scopes will always run _before_ any inner scopes. For +example, in the Vagrantfile below: + +```ruby +Vagrant.configure("2") do |config| + config.vm.provision "shell", inline: "echo foo" + + config.vm.define "web" do |web| + web.vm.provision "shell", inline: "echo bar" + end + + config.vm.provision "shell", inline: "echo baz" +end +``` + +The ordering of the provisioners will be to echo "foo", "baz", then +"bar" (note the second one might not be what you expect!). Remember: +ordering is _outside in_. + +With multiple provisioners, use the `--provision-with` setting along +with names to get more fine grained control over what is run and when. + +## Overriding Provisioner Settings + +
+ Warning: Advanced Topic! Provisioner overriding is + an advanced topic that really only becomes useful if you are already + using multi-machine and/or provider overrides. If you are just getting + started with Vagrant, you can safely skip this. +
+ +When using features such as [multi-machine](/docs/multi-machine/) +or [provider-specific overrides](/docs/providers/configuration.html), +you may want to define common provisioners in the global configuration +scope of a Vagrantfile, but override certain aspects of them internally. +Vagrant allows you to do this, but has some details to consider. + +To override settings, you must assign a name to your provisioner. + +```ruby +Vagrant.configure("2") do |config| + config.vm.provision "foo", type: "shell", + inline: "echo foo" + + config.vm.define "web" do |web| + web.vm.provision "foo", type: "shell", + inline: "echo bar" + end +end +``` + +In the above, only "bar" will be echoed, because the inline setting +overloaded the outer provisioner. This overload is only effective +within that scope: the "web" VM. If there were another VM defined, +it would still echo "foo" unless it itself also overloaded the +provisioner. + +**Be careful with ordering.** When overriding a provisioner in +a sub-scope, the provisioner will run at _that point_. In the example +below, the output would be "foo" then "bar": + +```ruby +Vagrant.configure("2") do |config| + config.vm.provision "foo", type: "shell", + inline: "echo ORIGINAL!" + + config.vm.define "web" do |web| + web.vm.provision "shell", + inline: "echo foo" + web.vm.provision "foo", type: "shell", + inline: "echo bar" + end +end +``` + +If you want to preserve the original ordering, you can specify +the `preserve_order: true` flag: + +```ruby +Vagrant.configure("2") do |config| + config.vm.provision "do-this", + type: "shell", + preserve_order: true, + inline: "echo FIRST!" + config.vm.provision "then-this", + type: "shell", + preserve_order: true, + inline: "echo SECOND!" +end +``` + +## Dependency Provisioners + +
+ Warning: Advanced Topic! Dependency provisioners are + an advanced topic. If you are just getting started with Vagrant, you can + safely skip this. +
+ +
+ Warning! This feature is still experimental and may break or + change in between releases. Use at your own risk. + +This feature currently reqiures the experimental flag to be used. To explicitly enable this feature, you can set the experimental flag to: + +``` +VAGRANT_EXPERIMENTAL="dependency_provisioners" +``` + +Please note that `VAGRANT_EXPERIMENTAL` is an environment variable. For more +information about this flag visit the [Experimental docs page](/docs/experimental/) +for more info. Without this flag enabled, provisioners with the `before` and +`after` option will be ignored. + +
+ +If a provisioner has been configured using the `before` or `after` options, it +is considered a _Dependency Provisioner_. This means it has been configured to +run before or after a _Root Provisioner_, which does not have the `before` or +`after` options configured. + +Dependency provisioners also have two valid shortcuts: +`:each` and `:all`. + +**Note**: As of 2.2.6, dependency provisioners cannot rely on other dependency +provisioners and is considered a configuration state error in Vagrant. If you must +order dependency provisioners, you can still order them by the order they are defined +inside your Vagrantfile. + +An example of these dependency provisioners can be seen below: + +```ruby +Vagrant.configure("2") do |config| + config.vm.provision "C", after: "B", type: "shell", inline:<<-SHELL + echo 'C' + SHELL + config.vm.provision "B", type: "shell", inline:<<-SHELL + echo 'B' + SHELL + config.vm.provision "D", type: "shell", inline:<<-SHELL + echo 'D' + SHELL + config.vm.provision "A", before: "B", type: "shell", inline:<<-SHELL + echo 'A' + SHELL + config.vm.provision "Separate After", after: :each, type: "shell", inline:<<-SHELL + echo '==============================' + SHELL + config.vm.provision "Separate Before", before: :each, type: "shell", inline:<<-SHELL + echo '++++++++++++++++++++++++++++++' + SHELL + config.vm.provision "Hello", before: :all, type: "shell", inline:<<-SHELL + echo 'HERE WE GO!!' + SHELL + config.vm.provision "Goodbye", after: :all, type: "shell", inline:<<-SHELL + echo 'The end' + SHELL +end +``` + +The result of running `vagrant provision` with a guest configured above: + +``` +==> default: Running provisioner: Hello (shell)... + default: Running: inline script + default: HERE WE GO!! +==> default: Running provisioner: Separate Before (shell)... + default: Running: inline script + default: ++++++++++++++++++++++++++++++ +==> default: Running provisioner: A (shell)... + default: Running: inline script + default: A +==> default: Running provisioner: Separate After (shell)... + default: Running: inline script + default: ============================== +==> default: Running provisioner: Separate Before (shell)... + default: Running: inline script + default: ++++++++++++++++++++++++++++++ +==> default: Running provisioner: B (shell)... + default: Running: inline script + default: B +==> default: Running provisioner: Separate After (shell)... + default: Running: inline script + default: ============================== +==> default: Running provisioner: Separate Before (shell)... + default: Running: inline script + default: ++++++++++++++++++++++++++++++ +==> default: Running provisioner: C (shell)... + default: Running: inline script + default: C +==> default: Running provisioner: Separate After (shell)... + default: Running: inline script + default: ============================== +==> default: Running provisioner: Separate Before (shell)... + default: Running: inline script + default: ++++++++++++++++++++++++++++++ +==> default: Running provisioner: D (shell)... + default: Running: inline script + default: D +==> default: Running provisioner: Separate After (shell)... + default: Running: inline script + default: ============================== +==> default: Running provisioner: Goodbye (shell)... + default: Running: inline script + default: The end +``` diff --git a/website/pages/docs/provisioning/cfengine.html.md b/website/pages/docs/provisioning/cfengine.html.md new file mode 100644 index 000000000..15e63665f --- /dev/null +++ b/website/pages/docs/provisioning/cfengine.html.md @@ -0,0 +1,173 @@ +--- +layout: 'docs' +page_title: 'CFEngine Provisioner' +sidebar_current: 'provisioning-cfengine' +description: |- + The Vagrant CFEngine provisioner allows you to provision the guest using + CFEngine. It can set up both CFEngine policy servers and clients. You can + configure both the policy server and the clients in a single multi-machine + Vagrantfile. +--- + +# CFEngine Provisioner + +**Provisioner name: `cfengine`** + +The Vagrant CFEngine provisioner allows you to provision the guest using +[CFEngine](https://cfengine.com/). It can set up both CFEngine +policy servers and clients. You can configure both the policy server +and the clients in a single +[multi-machine `Vagrantfile`](/docs/multi-machine/). + +
+ Warning: If you are not familiar with CFEngine and Vagrant already, + it is recommended to start with the shell + provisioner. However, if you are comfortable with Vagrant + already, Vagrant is the best way to learn CFEngine. +
+ +Let us look at some common examples first. See the bottom of this +document for a comprehensive list of options. + +## Setting up a CFEngine server and client + +The CFEngine provisioner automatically installs the latest +[CFEngine Community packages](https://cfengine.com/cfengine-linux-distros) +on the VM, then configures and starts CFEngine according to your +specification. + +Configuring a VM as a CFEngine policy server is easy: + +```ruby +Vagrant.configure("2") do |config| + config.vm.provision "cfengine" do |cf| + cf.am_policy_hub = true + end +end +``` + +The host will automatically be +[bootstrapped](https://cfengine.com/docs/3.5/manuals-architecture-networking.html#bootstrapping) +to itself to become a policy server. + +If you already have a working CFEngine policy server, you can get a +CFEngine client installed and bootstrapped by specifying its IP +address: + +```ruby +Vagrant.configure("2") do |config| + config.vm.provision "cfengine" do |cf| + cf.policy_server_address = "10.0.2.15" + end +end +``` + +## Copying files to the VM + +If you have some policy or other files that you want to install by +default on a VM, you can use the `files_path` attribute: + +```ruby +Vagrant.configure("2") do |config| + config.vm.provision "cfengine" do |cf| + cf.am_policy_hub = true + cf.files_path = "cfengine_files" + end + end +``` + +Everything under `cfengine_files/` in the Vagrant project directory +will be recursively copied under `/var/cfengine/` in the VM, on top of +its default contents. + +A common use case is to add your own files to +`/var/cfengine/masterfiles/` in the policy server. Assuming your extra +files are stored under `cfengine_files/masterfiles/`, the line shown +above will add them to the VM after CFEngine is installed, but before +it is bootstrapped. + +## Modes of operation + +The default mode of operation is `:bootstrap`, which results in +CFEngine being bootstrapped according to the information provided in +the `Vagrantfile`. You can also set `mode` to `:single_run`, which +will run `cf-agent` once on the host to execute the file specified in +the `run_file` parameter, but will not bootstrap it, so it will not be +executed periodically. + +The recommended mode of operation is `:bootstrap`, as you get the full +benefits of CFEngine when you have it running periodically. + +## Running a standalone file + +If you want to run a standalone file, you can specify the `run_file` +parameter. The file will be copied to the VM and executed on its own +using `cf-agent`. Note that the file needs to be a standalone policy, +including its own +[`body common control`](https://cfengine.com/docs/3.5/reference-components.html#common-control). + +The `run_file` parameter is mandatory if `mode` is set to +`:single_run`, but can also be specified when `mode` is set to +`:bootstrap` - in this case the file will be executed after the host +has been bootstrapped. + +## Full Alphabetical List of Configuration Options + +- `am_policy_hub` (boolean, default `false`) determines whether the VM will be + configured as a CFEngine policy hub (automatically bootstrapped to + its own IP address). You can combine it with `policy_server_address` + if the VM has multiple network interfaces and you want to bootstrap + to a specific one. +- `extra_agent_args` (string, default `nil`) can be used to pass + additional arguments to `cf-agent` when it is executed. For example, + you could use it to pass the `-I` or `-v` options to enable + additional output from the agent. +- `classes` (array, default `nil`) can be used to define additional + classes during `cf-agent` runs. These classes will be defined using + the `-D` option to `cf-agent`. +- `deb_repo_file` (string, default + `"/etc/apt/sources.list.d/cfengine-community.list"`) specifies the + file in which the CFEngine repository information will be stored in + Debian systems. +- `deb_repo_line` (string, default `"deb https://cfengine.com/pub/apt $(lsb_release -cs) main"`) specifies the repository to use for + `.deb` packages. +- `files_path` (string, default `nil`) specifies a directory that will + be copied to the VM on top of the default + `/var/cfengine/` (the contents of `/var/cfengine/` will not + be replaced, the files will added to it). +- `force_bootstrap` (boolean, default `false`) specifies whether + CFEngine will be bootstrapped again even if the host has already + been bootstrapped. +- `install` (boolean or `:force`, default `true`) specifies whether + CFEngine will be installed on the VM if needed. If you set this + parameter to `:force`, then CFEngine will be reinstalled even if + it is already present on the machine. +- `mode` (`:bootstrap` or `:single_run`, default `:bootstrap`) + specifies whether CFEngine will be bootstrapped so that it executes + periodically, or will be run a single time. If `mode` is set to + `:single_run` you have to set `run_file`. +- `policy_server_address` (string, no default) specifies the IP + address of the policy server to which CFEngine will be + bootstrapped. If `am_policy_hub` is set to `true`, this parameter + defaults to the VM's IP address, but can still be set (for + example, if the VM has more than one network interface). +- `repo_gpg_key_url` (string, default + `"https://cfengine.com/pub/gpg.key"`) contains the URL to obtain the + GPG key used to verify the packages obtained from the repository. +- `run_file` (string, default `nil`) can be used to specify a file + inside the Vagrant project directory that will be copied to the VM + and executed once using `cf-agent`. This parameter is mandatory if + `mode` is set to `:single_run`, but can also be specified when + `mode` is set to `:bootstrap` - in this case the file will be + executed after the host has been bootstrapped. +- `upload_path` (string, default `"/tmp/vagrant-cfengine-file"`) + specifies the file to which `run_file` (if specified) will be copied + on the VM before being executed. +- `yum_repo_file` (string, default + `"/etc/yum.repos.d/cfengine-community.repo"`) specifies the file in + which the CFEngine repository information will be stored in RedHat + systems. +- `yum_repo_url` (string, default `"https://cfengine.com/pub/yum/"`) + specifies the URL of the repository to use for `.rpm` packages. +- `package_name` (string, default `"cfengine-community"`) specifies + the name of the package used to install CFEngine. diff --git a/website/pages/docs/provisioning/chef_apply.html.md b/website/pages/docs/provisioning/chef_apply.html.md new file mode 100644 index 000000000..71751fbbb --- /dev/null +++ b/website/pages/docs/provisioning/chef_apply.html.md @@ -0,0 +1,104 @@ +--- +layout: 'docs' +page_title: 'Chef Apply - Provisioning' +sidebar_current: 'provisioning-chefapply' +description: |- + The Vagrant Chef Apply provisioner allows you to provision the guest using + Chef with chef-apply. +--- + +# Chef Apply Provisioner + +**Provisioner name: `chef_apply`** + +The Vagrant Chef Apply provisioner allows you to provision the guest using +[Chef](https://www.getchef.com/), specifically with +[Chef Apply](https://docs.getchef.com/ctl_chef_apply.html). + +Chef Apply is ideal for people who are already experienced with Chef and the +Chef ecosystem. Specifically, this documentation page does not cover how use +Chef or how to write Chef recipes. + +
+ Warning: If you are not familiar with Chef and Vagrant already, + we recommend starting with the shell + provisioner. +
+ +## Options + +This section lists the complete set of available options for the Chef Apply +provisioner. More detailed examples of how to use the provisioner are +available below this section. + +- `recipe` (string) - The raw recipe contents to execute using Chef Apply on + the guest. + +- `log_level` (string) - The log level to use while executing `chef-apply`. The + default value is "info". + +- `upload_path` (string) - **Advanced!** The location on the guest where the + generated recipe file should be stored. For most use cases, it is unlikely you + will need to customize this value. The default value is + `/tmp/vagrant-chef-apply-#` where `#` is a unique counter generated by + Vagrant to prevent collisions. + +In addition to all the options listed above, the Chef Apply provisioner supports +the [common options for all Chef provisioners](/docs/provisioning/chef_common.html). + +## Specifying a Recipe + +The easiest way to get started with the Chef Apply provisioner is to just +specify an inline +[Chef recipe](https://docs.chef.io/recipes.html). For +example: + +```ruby +Vagrant.configure("2") do |config| + config.vm.provision "chef_apply" do |chef| + chef.recipe = "package[apache2]" + end +end +``` + +This causes Vagrant to run Chef Apply with the given recipe contents. If you are +familiar with Chef, you know this will install the apache2 package from the +system package provider. + +Since single-line Chef recipes are rare, you can also specify the recipe using a +"heredoc": + +```ruby +Vagrant.configure("2") do |config| + config.vm.provision "chef_apply" do |chef| + chef.recipe = <<-RECIPE + package "apache2" + + template "/etc/apache2/my.config" do + # ... + end + RECIPE + end +end +``` + +Finally, if you would prefer to store the recipe as plain-text, you can set the +recipe to the contents of a file: + +```ruby +Vagrant.configure("2") do |config| + config.vm.provision "chef_apply" do |chef| + chef.recipe = File.read("/path/to/my/recipe.rb") + end +end +``` + +## Roles + +The Vagrant Chef Apply provisioner does not support roles. Please use a +different Vagrant Chef provisioner if you need support for roles. + +## Data Bags + +The Vagrant Chef Apply provisioner does not support data_bags. Please use a +different Vagrant Chef provisioner if you need support for data_bags. diff --git a/website/pages/docs/provisioning/chef_client.html.md b/website/pages/docs/provisioning/chef_client.html.md new file mode 100644 index 000000000..87e3e4df9 --- /dev/null +++ b/website/pages/docs/provisioning/chef_client.html.md @@ -0,0 +1,123 @@ +--- +layout: 'docs' +page_title: 'Chef Client - Provisioning' +sidebar_current: 'provisioning-chefclient' +description: |- + The Vagrant Chef Client provisioner allows you to provision the guest using + Chef, specifically by connecting to an existing Chef Server and registering + the Vagrant machine as a node within your infrastructure. +--- + +# Chef Client Provisioner + +**Provisioner name: `chef_client`** + +The Vagrant Chef Client provisioner allows you to provision the guest using +[Chef](https://www.chef.io/chef/), specifically by connecting +to an existing Chef Server and registering the Vagrant machine as a +node within your infrastructure. + +If you are just learning Chef for the first time, you probably want +to start with the [Chef Solo](/docs/provisioning/chef_solo.html) +provisioner. + +
+ Warning: If you are not familiar with Chef and Vagrant already, + it is recommended to start with the shell + provisioner. +
+ +## Authenticating + +The minimum required to use provision using Chef Client is to provide +a URL to the Chef Server as well as the path to the validation key so +that the node can register with the Chef Server: + +```ruby +Vagrant.configure("2") do |config| + config.vm.provision "chef_client" do |chef| + chef.chef_server_url = "http://mychefserver.com" + chef.validation_key_path = "validation.pem" + end +end +``` + +The node will register with the Chef Server specified, download the +proper run list for that node, and provision. + +## Specifying a Run List + +Normally, the Chef Server is responsible for specifying the run list +for the node. However, you can override what the Chef Server sends +down by manually specifying a run list: + +```ruby +Vagrant.configure("2") do |config| + config.vm.provision "chef_client" do |chef| + # Add a recipe + chef.add_recipe "apache" + + # Or maybe a role + chef.add_role "web" + end +end +``` + +Remember, this will _override_ the run list specified on the Chef +server itself. + +## Environments + +You can specify the [environment](https://docs.chef.io/environments.html) +for the node to come up in using the `environment` configuration option: + +```ruby +Vagrant.configure("2") do |config| + config.vm.provision "chef_client" do |chef| + # ... + + chef.environment = "development" + end +end +``` + +## Other Configuration Options + +There are a few more configuration options available. These generally do not +need to be modified but are available if your Chef Server requires customization +of these variables. + +- `client_key_path` +- `node_name` +- `validation_client_name` + +In addition to all the options listed above, the Chef Client provisioner supports +the [common options for all Chef provisioners](/docs/provisioning/chef_common.html). + +## Cleanup + +When you provision your Vagrant virtual machine with Chef Server, it creates a +new Chef "node" entry and Chef "client" entry on the Chef Server, using the +hostname of the machine. After you tear down your guest machine, Vagrant can be +configured to do it automatically with the following settings: + +```ruby +chef.delete_node = true +chef.delete_client = true +``` + +If you do not specify it or set it to `false`, you must explicitly delete these +entries from the Chef Server before you provision a new one with Chef Server. +For example, using Chef's built-in `knife` tool: + +``` +$ knife node delete precise64 +$ knife client delete precise64 +``` + +If you fail to do so, you will get the following error when Vagrant +tries to provision the machine with Chef Client: + +``` +HTTP Request Returned 409 Conflict: Client already exists. +``` diff --git a/website/pages/docs/provisioning/chef_common.html.md b/website/pages/docs/provisioning/chef_common.html.md new file mode 100644 index 000000000..cfb648afc --- /dev/null +++ b/website/pages/docs/provisioning/chef_common.html.md @@ -0,0 +1,136 @@ +--- +layout: 'docs' +page_title: 'Common Chef Options - Provisioning' +sidebar_current: 'provisioning-chefcommon' +description: |- + The following options are available to all Vagrant Chef provisioners. Many of + these options are for advanced users only and should not be used unless you + understand their purpose. +--- + +# Shared Chef Options + +## All Chef Provisioners + +The following options are available to all Vagrant Chef provisioners. Many of +these options are for advanced users only and should not be used unless you +understand their purpose. + +- `binary_path` (string) - The path to Chef's `bin/` directory on the guest + machine. + +- `binary_env` (string) - Arbitrary environment variables to set before running + the Chef provisioner command. This should be of the format `KEY=value` as a + string. + +- `install` (boolean, string) - Install Chef on the system if it does not exist. + The default value is "true", which will use the official Omnibus installer + from Chef. This is a trinary attribute (it can have three values): + + - `true` (boolean) - install Chef + - `false` (boolean) - do not install Chef + - `"force"` (string) - install Chef, even if it is already installed at the + proper version on the guest + +- `installer_download_path` (string) - The path where the Chef installer will be + downloaded to. This option is only honored if the `install` attribute is + `true` or `"force"`. The default value is to use the path provided by Chef's + Omnibus installer, which varies between releases. This value has no effect on + Windows because Chef's omnibus installer lacks the option on Windows. + +- `log_level` (string) - The Chef log level. See the Chef docs for acceptable + values. + +- `product` (string) - The name of the Chef product to install. The default + value is "chef", which corresponds to the Chef Client. You can also specify + "chefdk", which will install the Chef Development Kit. At the time of this + writing, the ChefDK is only available through the "current" channel, so you + will need to update that value as well. + +- `channel` (string) - The release channel from which to pull the Chef Client + or the Chef Development Kit. The default value is `"stable"` which will pull + the latest stable version of the Chef Client. For newer versions, or if you + wish to install the Chef Development Kit, you may need to change the channel + to "current". Because Chef Software floats the versions that are contained in + the channel, they may change and Vagrant is unable to detect this. + +- `version` (string) - The version of Chef to install on the guest. If Chef is + already installed on the system, the installed version is compared with the + requested version. If they match, no action is taken. If they do not match, + the value specified in this attribute will be installed in favor of the + existing version (a message will be displayed). + You can also specify "latest" (default), which will install the latest + version of Chef on the system. In this case, Chef will use whatever + version is on the system. To force the newest version of Chef to be + installed on every provision, set the [`install`](#install) option to "force". + +- `omnibus_url` (string) - Location of Omnibus installation scripts. + This URL specifies the location of install.sh/install.ps1 for + Linux/Unix and Windows respectively. + It defaults to https://omnitruck.chef.io. The full URL is in this case: + + - Linux/Unix: https://omnitruck.chef.io/install.sh + - Windows: https://omnitruck.chef.io/install.ps1 + + If you want to have https://example.com/install.sh as Omnibus script + for your Linux/Unix installations, you should set this option to + https://example.com + +## Runner Chef Provisioners + +The following options are available to any of the Chef "runner" provisioners +which include [Chef Solo](/docs/provisioning/chef_solo.html), [Chef Zero](/docs/provisioning/chef_zero.html), and [Chef Client](/docs/provisioning/chef_client.html). + +- `arguments` (string) - A list of additional arguments to pass on the + command-line to Chef. Since these are passed in a shell-like environment, + be sure to properly quote and escape characters if necessary. By default, + no additional arguments are sent. + +- `attempts` (int) - The number of times Chef will be run if an error occurs. + This defaults to 1. This can be increased to a higher number if your Chef + runs take multiple runs to reach convergence. + +- `custom_config_path` (string) - A path to a custom Chef configuration local + on your machine that will be used as the Chef configuration. This Chef + configuration will be loaded _after_ the Chef configuration that Vagrant + generates, allowing you to override anything that Vagrant does. This is + also a great way to use new Chef features that may not be supported fully + by Vagrant's abstractions yet. + +- `encrypted_data_bag_secret_key_path` (string) - The path to the secret key + file to decrypt encrypted data bags. By default, this is not set. + +- `environment` (string) - The environment you want the Chef run to be + a part of. + +- `formatter` (string) - The formatter to use for output from Chef. + +- `http_proxy`, `http_proxy_user`, `http_proxy_pass`, `no_proxy` (string) - Settings + to configure HTTP and HTTPS proxies to use from Chef. These settings are + also available with `http` replaced with `https` to configure HTTPS proxies. + +- `json` (hash) - Custom node attributes to pass into the Chef run. + +- `log_level` (string) - The log level for Chef output. This defaults to + "info". + +- `node_name` (string) - The node name for the Chef Client. By default this + will be your hostname. + +- `provisioning_path` (string) - The path on the remote machine where Vagrant + will store all necessary files for provisioning such as cookbooks, configurations, + etc. This path must be world writable. By default this is + `/tmp/vagrant-chef-#` where "#" is replaced by a unique counter. + +- `run_list` (array) - The run list that will be executed on the node. + +- `file_cache_path` and `file_backup_path` (string) - Paths on the remote + machine where files will be cached and backed up. It is useful sometimes + to configure this to a synced folder address so that this can be shared + across many Vagrant runs. + +- `verbose_logging` (boolean) - Whether or not to enable the Chef + `verbose_logging` option. By default this is false. + +- `enable_reporting` (boolean) - Whether or not to enable the Chef + `enable_reporting` option. By default this is true. diff --git a/website/pages/docs/provisioning/chef_solo.html.md b/website/pages/docs/provisioning/chef_solo.html.md new file mode 100644 index 000000000..3869c7f97 --- /dev/null +++ b/website/pages/docs/provisioning/chef_solo.html.md @@ -0,0 +1,202 @@ +--- +layout: 'docs' +page_title: 'Chef Solo - Provisioning' +sidebar_current: 'provisioning-chefsolo' +description: |- + The Vagrant Chef Solo provisioner allows you to provision the guest using + Chef, specifically with chef-solo. +--- + +# Chef Solo Provisioner + +**Provisioner name: `chef_solo`** + +The Vagrant Chef Solo provisioner allows you to provision the guest using +[Chef](https://www.chef.io/chef/), specifically with +[Chef Solo](https://docs.chef.io/chef_solo.html). + +Chef Solo is ideal for people who are already experienced with Chef, +already have Chef cookbooks, or are looking to learn Chef. Specifically, +this documentation page will not go into how to use Chef or how to write +Chef cookbooks, since Chef is a complete system that is beyond the scope +of a single page of documentation. + +
+ Warning: If you are not familiar with Chef and Vagrant already, + it is recommended to start with the shell + provisioner. However, if you are comfortable with Vagrant already, Vagrant + is the best way to learn Chef. +
+ +## Options + +This section lists the complete set of available options for the Chef Solo +provisioner. More detailed examples of how to use the provisioner are +available below this section. + +- `cookbooks_path` (string or array) - A list of paths to where cookbooks + are stored. By default this is "cookbooks", expecting a cookbooks folder + relative to the Vagrantfile location. + +- `data_bags_path` (string or array) - A path where data bags are stored. By + default, no data bag path is set. Chef 12 or higher is required to use the + array option. Chef 11 and lower only accept a string value. + +- `environments_path` (string) - A path where environment definitions are + located. By default, no environments folder is set. + +- `nodes_path` (string or array) - A list of paths where node objects (in JSON format) are stored. By default, no + nodes path is set. + +- `environment` (string) - The environment you want the Chef run to be + a part of. This requires Chef 11.6.0 or later, and that `environments_path` + is set. + +- `recipe_url` (string) - URL to an archive of cookbooks that Chef will download + and use. + +- `roles_path` (string or array) - A list of paths where roles are defined. + By default this is empty. Multiple role directories are only supported by + Chef 11.8.0 and later. + +- `synced_folder_type` (string) - The type of synced folders to use when + sharing the data required for the provisioner to work properly. By default + this will use the default synced folder type. For example, you can set this + to "nfs" to use NFS synced folders. + +In addition to all the options listed above, the Chef Solo provisioner supports +the [common options for all Chef provisioners](/docs/provisioning/chef_common.html). + +## Specifying a Run List + +The easiest way to get started with the Chef Solo provisioner is to just +specify a [run list](https://docs.chef.io/nodes.html#about-run-lists). This looks like: + +```ruby +Vagrant.configure("2") do |config| + config.vm.provision "chef_solo" do |chef| + chef.add_recipe "apache" + end +end +``` + +This causes Vagrant to run Chef Solo with the "apache" cookbook. The cookbooks +by default are looked for in the "cookbooks" directory relative to your +project root. The directory structure ends up looking like this: + +``` +$ tree +. +|-- Vagrantfile +|-- cookbooks +|   |-- apache +|   |-- recipes +|   |-- default.rb +``` + +The order of the calls to `add_recipe` will specify the order of the run list. +Earlier recipes added with `add_recipe` are run before later recipes added. + +## Custom Cookbooks Path + +Instead of using the default "cookbooks" directory, a custom cookbooks +path can also be set via the `cookbooks_path` configuration directive: + +```ruby +Vagrant.configure("2") do |config| + config.vm.provision "chef_solo" do |chef| + chef.cookbooks_path = "my_cookbooks" + end +end +``` + +The path can be relative or absolute. If it is relative, it is relative +to the project root. + +The configuration value can also be an array of paths: + +```ruby +Vagrant.configure("2") do |config| + config.vm.provision "chef_solo" do |chef| + chef.cookbooks_path = ["cookbooks", "my_cookbooks"] + end +end +``` + +## Roles + +Vagrant also supports provisioning with [Chef roles](https://docs.chef.io/roles.html). +This is done by specifying a path to a roles folder where roles are defined +and by adding roles to your run list: + +```ruby +Vagrant.configure("2") do |config| + config.vm.provision "chef_solo" do |chef| + chef.roles_path = "roles" + chef.add_role("web") + end +end +``` + +Just like the cookbooks path, the roles path is relative to the project +root if a relative path is given. + +The configuration value can also be an array of paths on Chef 11.8.0 and newer. +On older Chef versions only the first path is used. + +**Note:** The name of the role file must be the same as the role name. +For example the `web` role must be in the `roles_path` as web.json or web.rb. +This is required by Chef itself, and is not a limitation imposed by +Vagrant. + +## Data Bags + +[Data bags](https://docs.chef.io/data_bags.html) are also +supported by the Chef Solo provisioner. This is done by specifying +a path to your data bags directory: + +```ruby +Vagrant.configure("2") do |config| + config.vm.provision "chef_solo" do |chef| + chef.data_bags_path = "data_bags" + end +end +``` + +## Custom JSON Data + +Additional configuration data for Chef attributes can be passed in +to Chef Solo. This is done by setting the `json` property with a Ruby +hash (dictionary-like object), which is converted to JSON and passed +in to Chef: + +```ruby +Vagrant.configure("2") do |config| + config.vm.provision "chef_solo" do |chef| + # ... + + chef.json = { + "apache" => { + "listen_address" => "0.0.0.0" + } + } + end +end +``` + +Hashes, arrays, etc. can be used with the JSON configuration object. Basically, +anything that can be turned cleanly into JSON works. + +## Custom Node Name + +You can specify a custom node name by setting the `node_name` property. This +is useful for cookbooks that may depend on this being set to some sort +of value. Example: + +```ruby +Vagrant.configure("2") do |config| + config.vm.provision "chef_solo" do |chef| + chef.node_name = "foo" + end +end +``` diff --git a/website/pages/docs/provisioning/chef_zero.html.md b/website/pages/docs/provisioning/chef_zero.html.md new file mode 100644 index 000000000..a83c5ad6e --- /dev/null +++ b/website/pages/docs/provisioning/chef_zero.html.md @@ -0,0 +1,91 @@ +--- +layout: 'docs' +page_title: 'Chef Zero - Provisioning' +sidebar_current: 'provisioning-chefzero' +description: |- + The Vagrant Chef Zero provisioner allows you to provision the guest using + Chef, specifically with chef-zero. +--- + +# Chef Zero Provisioner + +**Provisioner name: `chef_zero`** + +The Vagrant Chef Zero provisioner allows you to provision the guest using +[Chef](https://www.getchef.com/chef/), specifically with +[Chef Zero/local mode](https://docs.getchef.com/ctl_chef_client.html#run-in-local-mode). + +This new provisioner is a middle ground between running a full blown +Chef Server and using the limited [Chef Solo](/docs/provisioning/chef_solo.html) +provisioner. It runs a local in-memory Chef Server and fakes the validation +and client key registration. + +
+ Warning: If you are not familiar with Chef and Vagrant already, + we recommend starting with the shell + provisioner. However, if you are comfortable with Vagrant already, Vagrant + is the best way to learn Chef. +
+ +## Options + +This section lists the complete set of available options for the Chef Zero +provisioner. More detailed examples of how to use the provisioner are +available below this section. + +- `cookbooks_path` (string or array) - A list of paths to where cookbooks + are stored. By default this is "cookbooks", expecting a cookbooks folder + relative to the Vagrantfile location. + +- `data_bags_path` (string or array) - A path where data bags are stored. By + default, no data bag path is set. Chef 12 or higher is required to use the + array option. Chef 11 and lower only accept a string value. + +- `environments_path` (string) - A path where environment definitions are + located. By default, no environments folder is set. + +- `nodes_path` (string or array) - A list of paths where node objects + (in JSON format) are stored. By default, no nodes path is set. This value is + required. + +- `environment` (string) - The environment you want the Chef run to be + a part of. This requires Chef 11.6.0 or later, and that `environments_path` + is set. + +- `roles_path` (string or array) - A list of paths where roles are defined. + By default this is empty. Multiple role directories are only supported by + Chef 11.8.0 and later. + +- `synced_folder_type` (string) - The type of synced folders to use when + sharing the data required for the provisioner to work properly. By default + this will use the default synced folder type. For example, you can set this + to "nfs" to use NFS synced folders. + +In addition to all the options listed above, the Chef Zero provisioner supports +the [common options for all Chef provisioners](/docs/provisioning/chef_common.html). + +## Usage + +The Chef Zero provisioner is configured basically the same way as the Chef Solo +provisioner. See the [Chef Solo documentations](/docs/provisioning/chef_solo.html) +for more information. + +A basic example could look like this: + +```ruby +Vagrant.configure("2") do |config| + config.vm.provision "chef_zero" do |chef| + # Specify the local paths where Chef data is stored + chef.cookbooks_path = "cookbooks" + chef.data_bags_path = "data_bags" + chef.nodes_path = "nodes" + chef.roles_path = "roles" + + # Add a recipe + chef.add_recipe "apache" + + # Or maybe a role + chef.add_role "web" + end +end +``` diff --git a/website/pages/docs/provisioning/docker.html.md b/website/pages/docs/provisioning/docker.html.md new file mode 100644 index 000000000..97f569731 --- /dev/null +++ b/website/pages/docs/provisioning/docker.html.md @@ -0,0 +1,208 @@ +--- +layout: 'docs' +page_title: 'Docker - Provisioning' +sidebar_current: 'provisioning-docker' +description: |- + The Vagrant Docker provisioner can automatically install Docker, pull Docker + containers, and configure certain containers to run on boot. +--- + +# Docker Provisioner + +**Provisioner name: `"docker"`** + +The Vagrant Docker provisioner can automatically install +[Docker](https://www.docker.io), pull Docker containers, and configure certain +containers to run on boot. + +The docker provisioner is ideal for organizations that are using +Docker as a means to distribute things like their application or services. +Or, if you are just getting started with Docker, the Docker provisioner +provides the easiest possible way to begin using Docker since the provisioner +automates installing Docker for you. + +As with all provisioners, the Docker provisioner can be used along with +all the other provisioners Vagrant has in order to setup your working +environment the best way possible. For example, perhaps you use Puppet to +install services like databases or web servers but use Docker to house +your application runtime. You can use the Puppet provisioner along +with the Docker provisioner. + +
+ Note: This documentation is for the Docker + provisioner. If you are looking for the Docker + provider, visit the + Docker provider documentation. +
+ +## Options + +The docker provisioner takes various options. None are required. If +no options are required, the Docker provisioner will only install Docker +for you (if it is not already installed). + +- `images` (array) - A list of images to pull using `docker pull`. You + can also use the `pull_images` function. See the example below this + section for more information. + +In addition to the options that can be set, various functions are available +and can be called to configure other aspects of the Docker provisioner. Most +of these functions have examples in more detailed sections below. + +- `build_image` - Build an image from a Dockerfile. + +- `pull_images` - Pull the given images. This does not start these images. + +- `post_install_provisioner` - A [provisioner block](/docs/provisioning) that runs post docker + installation. + +- `run` - Run a container and configure it to start on boot. This can + only be specified once. + +## Building Images + +The provisioner can automatically build images. Images are built prior to +any configured containers to run, so you can build an image before running it. +Building an image is easy: + +```ruby +Vagrant.configure("2") do |config| + config.vm.provision "docker" do |d| + d.build_image "/vagrant/app" + end +end +``` + +The argument to build an image is the path to give to `docker build`. This +must be a path that exists within the guest machine. If you need to get data +to the guest machine, use a synced folder. + +The `build_image` function accepts options as a second parameter. Here +are the available options: + +- `args` (string) - Additional arguments to pass to `docker build`. Use this + to pass in things like `-t "foo"` to tag the image. + +## Pulling Images + +The docker provisioner can automatically pull images from the +Docker registry for you. There are two ways to specify images to +pull. The first is as an array using `images`: + +```ruby +Vagrant.configure("2") do |config| + config.vm.provision "docker", + images: ["ubuntu"] +end +``` + +This will cause Vagrant to pull the "ubuntu" image from the registry +for you automatically. + +The second way to pull images is to use the `pull_images` function. +Each call to `pull_images` will _append_ the images to be pulled. The +`images` variable, on the other hand, can only be used once. + +Additionally, the `pull_images` function cannot be used with the +simple configuration method for provisioners (specifying it all in one line). + +```ruby +Vagrant.configure("2") do |config| + config.vm.provision "docker" do |d| + d.pull_images "ubuntu" + d.pull_images "vagrant" + end +end +``` + +## Running Containers + +In addition to pulling images, the Docker provisioner can run and start +containers for you. This lets you automatically start services as part of +`vagrant up`. + +Running containers can only be configured using the Ruby block syntax with +the `do...end` blocks. An example of running a container is shown below: + +```ruby +Vagrant.configure("2") do |config| + config.vm.provision "docker" do |d| + d.run "rabbitmq" + end +end +``` + +This will `docker run` a container with the "rabbitmq" image. Note that +Vagrant uses the first parameter (the image name by default) to override any +settings used in a previous `run` definition. Therefore, if you need to run +multiple containers from the same image then you must specify the `image` +option (documented below) with a unique name. + +In addition to the name, the `run` method accepts a set of options, all optional: + +- `image` (string) - The image to run. This defaults to the first argument + but can also be given here as an option. + +- `cmd` (string) - The command to start within the container. If not specified, + then the container's default command will be used, such as the + "CMD" command [specified in the `Dockerfile`](https:/docs.docker.io/en/latest/use/builder/#cmd). + +- `args` (string) - Extra arguments for [`docker run`](https:/docs.docker.io/en/latest/commandline/cli/#run) + on the command line. These are raw arguments that are passed directly to Docker. + +- `auto_assign_name` (boolean) - If true, the `--name` of the container will + be set to the first argument of the run. By default this is true. If the + name set contains a "/" (because of the image name), it will be replaced + with "-". Therefore, if you do `d.run "foo/bar"`, then the name of the + container will be "foo-bar". + +- `daemonize` (boolean) - If true, the "-d" flag is given to `docker run` to + daemonize the containers. By default this is true. + +- `restart` (string) - The restart policy for the container. Defaults to + "always" + +For example, here is how you would configure Docker to run a container +with the Vagrant shared directory mounted inside of it: + +```ruby +Vagrant.configure("2") do |config| + config.vm.provision "docker" do |d| + d.run "ubuntu", + cmd: "bash -l", + args: "-v '/vagrant:/var/www'" + end +end +``` + +In case you need to run multiple containers based off the same image, you can do +so by providing different names and specifying the `image` parameter to it: + +```ruby +Vagrant.configure("2") do |config| + config.vm.provision "docker" do |d| + d.run "db-1", image: "user/mysql" + d.run "db-2", image: "user/mysql" + end +end +``` + +## Other + +This section documents some other things related to the Docker provisioner +that are generally useful to know if you are using this provisioner. + +### Customize `/etc/default/docker` + +To customize this file, use the `post_install_provisioner` shell provisioner. + +```ruby +Vagrant.configure("2") do |config| + config.vm.provision "docker" do |d| + d.post_install_provision "shell", inline:"echo export http_proxy='http://127.0.0.1:3128/' >> /etc/default/docker" + d.run "ubuntu", + cmd: "bash -l", + args: "-v '/vagrant:/var/www'" + end +end +``` diff --git a/website/pages/docs/provisioning/file.html.md b/website/pages/docs/provisioning/file.html.md new file mode 100644 index 000000000..7b9e4c19b --- /dev/null +++ b/website/pages/docs/provisioning/file.html.md @@ -0,0 +1,134 @@ +--- +layout: 'docs' +page_title: 'File Uploads - Provisioning' +sidebar_current: 'provisioning-file' +description: |- + The Vagrant file provisioner allows you to upload a file or directory from the + host machine to the guest machine. +--- + +# File Provisioner + +**Provisioner name: `"file"`** + +The Vagrant file provisioner allows you to upload a file or directory from the +host machine to the guest machine. + +File provisioning is a simple way to, for example, replicate your local +~/.gitconfig to the vagrant user's home directory on the guest machine so +you will not have to run `git config --global` every time you provision a +new VM. + +```ruby +Vagrant.configure("2") do |config| + # ... other configuration + + config.vm.provision "file", source: "~/.gitconfig", destination: ".gitconfig" +end +``` + +If you want to upload a folder to your guest system, it can be accomplished by +using a file provisioner seen below. When copied, the resulting folder on the guest will +replace `folder` as `newfolder` and place its on the guest machine. Note that if +you'd like the same folder name on your guest machine, make sure that the destination +path has the same name as the folder on your host. + +```ruby +Vagrant.configure("2") do |config| + # ... other configuration + + config.vm.provision "file", source: "~/path/to/host/folder", destination: "$HOME/remote/newfolder" +end +``` + +Prior to copying `~/path/to/host/folder` to the guest machine: + + folder + ├── script.sh + ├── otherfolder + │   └── hello.sh + ├── goodbye.sh + ├── hello.sh + └── woot.sh + + 1 directory, 5 files + +After to copying `~/path/to/host/folder` into `$HOME/remote/newfolder` to the guest machine: + + newfolder + ├── script.sh + ├── otherfolder + │   └── hello.sh + ├── goodbye.sh + ├── hello.sh + └── woot.sh + + 1 directory, 5 files + +Note that, unlike with synced folders, files or directories that are uploaded +will not be kept in sync. Continuing with the example above, if you make +further changes to your local ~/.gitconfig, they will not be immediately +reflected in the copy you uploaded to the guest machine. + +The file uploads by the file provisioner are done as the +_SSH or PowerShell user_. This is important since these users generally +do not have elevated privileges on their own. If you want to upload files to +locations that require elevated privileges, we recommend uploading them +to temporary locations and then using the +[shell provisioner](/docs/provisioning/shell.html) +to move them into place. + +## Options + +The file provisioner takes only two options, both of which are required: + +- `source` (string) - Is the local path of the file or directory to be + uploaded. + +- `destination` (string) - Is the remote path on the guest machine where + the source will be uploaded to. The file/folder is uploaded as the SSH user + over SCP, so this location must be writable to that user. The SSH user can be + determined by running `vagrant ssh-config`, and defaults to "vagrant". Both + forward and backward slash work for Windows guest. Variables like `$HOME` are + expanded by Vagrant, not by guest. + +## Caveats + +While the file provisioner does support trailing slashes or "globing", this can +lead to some confusing results due to the underlying tool used to copy files and +folders between the host and guests. For example, if you have a source and +destination with a trailing slash defined below: + +```ruby +config.vm.provision "file", source: "~/pathfolder", destination: "/remote/newlocation/" +``` + +You are telling vagrant to upload `~/pathfolder` under the remote dir `/remote/newlocation`, +which will look like: + + newlocation + ├── pathfolder + │   └── file.sh + + 1 directory, 2 files + +This behavior can also be achieved by defining your file provisioner below: + +```ruby +config.vm.provision "file", source: "~/pathfolder", destination: "/remote/newlocation/pathfolder" +``` + +Another example is using globing on the host machine to grab all files within a +folder, but not the top level folder itself: + +```ruby +config.vm.provision "file", source: "~/otherfolder/.", destination: "/remote/otherlocation" +``` + +The file provisioner is defined to include all files under `~/otherfolder` +to the new location `/remote/otherlocation`. This idea can be achieved by simply +having your destination folder differ from the source folder: + +```ruby +config.vm.provision "file", source: "/otherfolder", destination: "/remote/otherlocation" +``` diff --git a/website/pages/docs/provisioning/index.html.md b/website/pages/docs/provisioning/index.html.md new file mode 100644 index 000000000..1d5bfe42e --- /dev/null +++ b/website/pages/docs/provisioning/index.html.md @@ -0,0 +1,49 @@ +--- +layout: 'docs' +page_title: 'Provisioning' +sidebar_current: 'provisioning' +description: |- + Provisioners in Vagrant allow you to automatically install software, alter configurations, and more on the machine as part of the `vagrant up` process. +--- + +# Provisioning + +Provisioners in Vagrant allow you to automatically install software, alter configurations, +and more on the machine as part of the `vagrant up` process. + +This is useful since [boxes](/docs/boxes.html) typically are not +built _perfectly_ for your use case. Of course, if you want to just use +`vagrant ssh` and install the software by hand, that works. But by using +the provisioning systems built-in to Vagrant, it automates the process so +that it is repeatable. Most importantly, it requires no human interaction, +so you can `vagrant destroy` and `vagrant up` and have a fully ready-to-go +work environment with a single command. Powerful. + +Vagrant gives you multiple options for provisioning the machine, from +simple shell scripts to more complex, industry-standard configuration +management systems. + +If you've never used a configuration management system before, it is +recommended you start with basic [shell scripts](/docs/provisioning/shell.html) +for provisioning. + +You can find the full list of built-in provisioners and usage of these +provisioners in the navigational area to the left. + +## When Provisioning Happens + +Provisioning happens at certain points during the lifetime of your +Vagrant environment: + +- On the first `vagrant up` that creates the environment, provisioning is run. + If the environment was already created and the up is just resuming a machine + or booting it up, they will not run unless the `--provision` flag is explicitly + provided. + +- When `vagrant provision` is used on a running environment. + +- When `vagrant reload --provision` is called. The `--provision` flag must + be present to force provisioning. + +You can also bring up your environment and explicitly _not_ run provisioners +by specifying `--no-provision`. diff --git a/website/pages/docs/provisioning/podman.html.md b/website/pages/docs/provisioning/podman.html.md new file mode 100644 index 000000000..50c87a20c --- /dev/null +++ b/website/pages/docs/provisioning/podman.html.md @@ -0,0 +1,176 @@ +--- +layout: 'docs' +page_title: 'Podman - Provisioning' +sidebar_current: 'provisioning-podman' +description: |- + The Vagrant Podman provisioner can automatically install Podman, and run it as a drop in replacement for Docker. +--- + +# Podman Provisioner + +**Provisioner name: `"podman"`** + +The Vagrant Podman provisioner can automatically install +[Podman](https://www.podman.io) to be used as a drop in Docker replacement. This includes the ability to pull Docker containers, and configure certain containers to run on boot. + +The podman provisioner is ideal for organizations that are using +Podman as a means to manage and run their OCI images. + +As with all provisioners, the Podman provisioner can be used along with +all the other provisioners Vagrant has in order to setup your working +environment the best way possible. For example, perhaps you use Puppet to +install services like databases or web servers but use Podman to house +your application runtime. You can use the Puppet provisioner along +with the Podman provisioner. + +## Options + +The podman provisioner takes various options. None are required. If +no options are provided, the Podman provisioner will only install Podman +for you (if it is not already installed). + +- `images` (array) - A list of images to pull using `podman pull`. You + can also use the `pull_images` function. See the example below this + section for more information. + +In addition to the options that can be set, various functions are available +and can be called to configure other aspects of the Podman provisioner. Most +of these functions have examples in more detailed sections below. + +- `build_image` - Build an image from a Dockerfile. + +- `pull_images` - Pull the given images. This does not start these images. + +- `post_install_provisioner` - A [provisioner block](/docs/provisioning) that runs post podman + installation. + +- `run` - Run a container and configure it to start on boot. This can + only be specified once. + +## Building Images + +The provisioner can automatically build images. Images are built prior to +any configured containers to run, so you can build an image before running it. +Building an image is easy: + +```ruby +Vagrant.configure("2") do |config| + config.vm.provision "podman" do |d| + d.build_image "/vagrant/app" + end +end +``` + +The argument to build an image is the path to give to `podman build`. This +must be a path that exists within the guest machine. If you need to get data +to the guest machine, use a synced folder. + +The `build_image` function accepts options as a second parameter. Here +are the available options: + +- `args` (string) - Additional arguments to pass to `podman build`. Use this + to pass in things like `-t "foo"` to tag the image. + +## Pulling Images + +The podman provisioner can automatically pull images from the +Docker registry for you. There are two ways to specify images to +pull. The first is as an array using `images`: + +```ruby +Vagrant.configure("2") do |config| + config.vm.provision "podman", + images: ["ubuntu"] +end +``` + +This will cause Vagrant to pull the "ubuntu" image from the registry +for you automatically. + +The second way to pull images is to use the `pull_images` function. +Each call to `pull_images` will _append_ the images to be pulled. The +`images` variable, on the other hand, can only be used once. + +Additionally, the `pull_images` function cannot be used with the +simple configuration method for provisioners (specifying it all in one line). + +```ruby +Vagrant.configure("2") do |config| + config.vm.provision "podman" do |d| + d.pull_images "ubuntu" + d.pull_images "vagrant" + end +end +``` + +## Running Containers + +In addition to pulling images, the Podman provisioner can run and start +containers for you. This lets you automatically start services as part of +`vagrant up`. + +Running containers can only be configured using the Ruby block syntax with +the `do...end` blocks. An example of running a container is shown below: + +```ruby +Vagrant.configure("2") do |config| + config.vm.provision "podman" do |d| + d.run "rabbitmq" + end +end +``` + +This will `podman run` a container with the "rabbitmq" image. Note that +Vagrant uses the first parameter (the image name by default) to override any +settings used in a previous `run` definition. Therefore, if you need to run +multiple containers from the same image then you must specify the `image` +option (documented below) with a unique name. + +In addition to the name, the `run` method accepts a set of options, all optional: + +- `image` (string) - The image to run. This defaults to the first argument + but can also be given here as an option. + +- `cmd` (string) - The command to start within the container. If not specified, + then the container's default command will be used, such as the + "CMD" command [specified in the `Dockerfile`](https:/docs.docker.io/en/latest/use/builder/#cmd). + +- `args` (string) - Extra arguments for `podman run` (same as the extra arguments that can be specified for [`docker run`](https:/docs.docker.io/en/latest/commandline/cli/#run)) + on the command line. These are raw arguments that are passed directly to Podman. + +- `auto_assign_name` (boolean) - If true, the `--name` of the container will + be set to the first argument of the run. By default this is true. If the + name set contains a "/" (because of the image name), it will be replaced + with "-". Therefore, if you do `d.run "foo/bar"`, then the name of the + container will be "foo-bar". + +- `daemonize` (boolean) - If true, the "-d" flag is given to `podman run` to + daemonize the containers. By default this is true. + +- `restart` (string) - The restart policy for the container. Defaults to + "always" + +For example, here is how you would configure Podman to run a container +with the Vagrant shared directory mounted inside of it: + +```ruby +Vagrant.configure("2") do |config| + config.vm.provision "podman" do |d| + d.run "ubuntu", + cmd: "bash -l", + args: "-v '/vagrant:/var/www'" + end +end +``` + +In case you need to run multiple containers based off the same image, you can do +so by providing different names and specifying the `image` parameter to it: + +```ruby +Vagrant.configure("2") do |config| + config.vm.provision "podman" do |d| + d.run "db-1", image: "user/mysql" + d.run "db-2", image: "user/mysql" + end +end +``` diff --git a/website/pages/docs/provisioning/puppet_agent.html.md b/website/pages/docs/provisioning/puppet_agent.html.md new file mode 100644 index 000000000..7f7825713 --- /dev/null +++ b/website/pages/docs/provisioning/puppet_agent.html.md @@ -0,0 +1,101 @@ +--- +layout: 'docs' +page_title: 'Puppet Agent - Provisioning' +sidebar_current: 'provisioning-puppetagent' +description: |- + The Vagrant Puppet agent provisioner allows you to provision the guest using + Puppet, specifically by calling "puppet agent", connecting to a Puppet master, + and retrieving the set of modules and manifests from there. +--- + +# Puppet Agent Provisioner + +**Provisioner name: `puppet_server`** + +The Vagrant Puppet agent provisioner allows you to provision the guest using +[Puppet](https://www.puppetlabs.com/puppet), specifically by +calling `puppet agent`, connecting to a Puppet master, and retrieving +the set of modules and manifests from there. + +
+ Warning: If you are not familiar with Puppet and Vagrant already, + it is recommended to start with the shell + provisioner. However, if you are comfortable with Vagrant already, Vagrant + is the best way to learn Puppet. +
+ +## Options + +The `puppet_server` provisioner takes various options. None are strictly +required. They are listed below: + +- `binary_path` (string) - Path on the guest to Puppet's `bin/` directory. + +- `client_cert_path` (string) - Path to the client certificate for the + node on your disk. This defaults to nothing, in which case a client + cert will not be uploaded. + +- `client_private_key_path` (string) - Path to the client private key for + the node on your disk. This defaults to nothing, in which case a client + private key will not be uploaded. + +- `facter` (hash) - Additional Facter facts to make available to the + Puppet run. + +- `options` (string or array) - Additional command line options to pass + to `puppet agent` when Puppet is ran. + +- `puppet_node` (string) - The name of the node. If this is not set, + this will attempt to use a hostname if set via `config.vm.hostname`. + Otherwise, the box name will be used. + +- `puppet_server` (string) - Hostname of the Puppet server. By default + "puppet" will be used. + +## Specifying the Puppet Master + +The quickest way to get started with the Puppet agent provisioner is to just +specify the location of the Puppet master: + +```ruby +Vagrant.configure("2") do |config| + config.vm.provision "puppet_server" do |puppet| + puppet.puppet_server = "puppet.example.com" + end +end +``` + +By default, Vagrant will look for the host named "puppet" on the +local domain of the guest machine. + +## Configuring the Node Name + +The node name that the agent registers as can be customized. Remember +this is important because Puppet uses the node name as part of the process +to compile the catalog the node will run. + +The node name defaults to the hostname of the guest machine, but can +be customized using the Vagrantfile: + +```ruby +Vagrant.configure("2") do |config| + config.vm.provision "puppet_server" do |puppet| + puppet.puppet_node = "node.example.com" + end +end +``` + +## Additional Options + +Puppet supports a lot of command-line flags. Basically any setting can +be overridden on the command line. To give you the most power and flexibility +possible with Puppet, Vagrant allows you to specify custom command line +flags to use: + +```ruby +Vagrant.configure("2") do |config| + config.vm.provision "puppet_server" do |puppet| + puppet.options = "--verbose --debug" + end +end +``` diff --git a/website/pages/docs/provisioning/puppet_apply.html.md b/website/pages/docs/provisioning/puppet_apply.html.md new file mode 100644 index 000000000..853881f66 --- /dev/null +++ b/website/pages/docs/provisioning/puppet_apply.html.md @@ -0,0 +1,238 @@ +--- +layout: 'docs' +page_title: 'Puppet Apply - Provisioning' +sidebar_current: 'provisioning-puppetapply' +description: |- + The Vagrant Puppet provisioner allows you to provision the guest using + Puppet, specifically by calling "puppet apply", without a Puppet Master. +--- + +# Puppet Apply Provisioner + +**Provisioner name: `puppet`** + +The Vagrant Puppet provisioner allows you to provision the guest using +[Puppet](https://www.puppetlabs.com/puppet), specifically by +calling `puppet apply`, without a Puppet Master. + +
+ Warning: If you are not familiar with Puppet and Vagrant already, + it is recommended to start with the shell + provisioner. However, if you are comfortable with Vagrant already, Vagrant + is the best way to learn Puppet. +
+ +## Options + +This section lists the complete set of available options for the Puppet +provisioner. More detailed examples of how to use the provisioner are +available below this section. + +- `binary_path` (string) - Path on the guest to Puppet's `bin/` directory. + +- `facter` (hash) - A hash of data to set as available facter variables + within the Puppet run. + +- `hiera_config_path` (string) - Path to the Hiera configuration on + the host. Read the section below on how to use Hiera with Vagrant. + +- `manifest_file` (string) - The name of the manifest file that will serve + as the entrypoint for the Puppet run. This manifest file is expected to + exist in the configured `manifests_path` (see below). This defaults + to "default.pp" + +- `manifests_path` (string) - The path to the directory which contains the + manifest files. This defaults to "manifests" + +- `module_path` (string or array of strings) - Path or paths, on the host, to the directory which + contains Puppet modules, if any. + +- `environment` (string) - Name of the Puppet environment. + +- `environment_path` (string) - Path to the directory that contains environment + files on the host disk. + +- `environment_variables` (hash) - A hash of string key/value pairs to be set as + environment variables before the puppet apply run. + +- `options` (array of strings) - Additionally options to pass to the + Puppet executable when running Puppet. + +- `synced_folder_type` (string) - The type of synced folders to use when + sharing the data required for the provisioner to work properly. By default + this will use the default synced folder type. For example, you can set this + to "nfs" to use NFS synced folders. + +- `synced_folder_args` (array) - Arguments that are passed to the folder sync. + For example ['-a', '--delete', '--exclude=fixtures'] for the rsync sync + command. + +- `temp_dir` (string) - The directory where all the data associated with + the Puppet run (manifest files, modules, etc.) will be stored on the + guest machine. + +- `working_directory` (string) - Path in the guest that will be the working + directory when Puppet is executed. This is usually only set because relative + paths are used in the Hiera configuration. + +~> If only `environment` and `environment_path` are specified, it will parse +and use the manifest specified in the `environment.conf` file. If +`manifests_path` and `manifest_file` is specified along with the environment +options, the manifest from the environment will be overridden by the specified `manifest_file`. If `manifests_path` and `manifest_file` are specified without +environments, the old non-environment mode will be used (which will fail on +Puppet 4+). + +## Bare Minimum + +The quickest way to get started with the Puppet provisioner is to just +enable it: + +```ruby +Vagrant.configure("2") do |config| + config.vm.provision "puppet" +end +``` + +~> `puppet` need to be installed in the guest vm. + +By default, Vagrant will configure Puppet to look for manifests in the +"manifests" folder relative to the project root, and will use the +"default.pp" manifest as an entry-point. This means, if your directory +tree looks like the one below, you can get started with Puppet with +just that one line in your Vagrantfile. + +``` +$ tree +. +|-- Vagrantfile +|-- manifests +|   |-- default.pp +``` + +## Custom Manifest Settings + +Of course, you are able to put and name your manifests whatever you would +like. You can override both the directory where Puppet looks for +manifests with `manifests_path`, and the manifest file used as the +entry-point with `manifest_file`: + +```ruby +Vagrant.configure("2") do |config| + config.vm.provision "puppet" do |puppet| + puppet.manifests_path = "my_manifests" + puppet.manifest_file = "default.pp" + end +end +``` + +The path can be relative or absolute. If it is relative, it is relative +to the project root. + +You can also specify a manifests path that is on the remote machine +already, perhaps put in place by a shell provisioner. In this case, Vagrant +will not attempt to upload the manifests directory. To specify a remote +manifests path, use the following syntax: + +```ruby +Vagrant.configure("2") do |config| + config.vm.provision "puppet" do |puppet| + puppet.manifests_path = ["vm", "/path/to/manifests"] + puppet.manifest_file = "default.pp" + end +end +``` + +It is a somewhat odd syntax, but the tuple (two-element array) says +that the path is located in the "vm" at "/path/to/manifests". + +## Environments + +If you are using Puppet 4 or higher, you can provision using +[Puppet Environments](https://docs.puppetlabs.com/puppet/latest/reference/environments.html) by specifying the name of the environment and the path on the +local disk to the environment files: + +```ruby +Vagrant.configure("2") do |config| + config.vm.provision "puppet" do |puppet| + puppet.environment_path = "../puppet/environments" + puppet.environment = "testenv" + end +end +``` + +The default manifest is the environment's `manifests` directory. +If the environment has an `environment.conf` the manifest path is parsed +from there. Relative paths are assumed to be relative to the directory of +the environment. If the manifest setting in `environment.conf` use +the Puppet variables `$codedir` or `$environment` they are resolved to +the parent directory of `environment_path` and `environment` respectively. + +## Modules + +Vagrant also supports provisioning with [Puppet modules](https://docs.puppetlabs.com/guides/modules.html). +This is done by specifying a path to a modules folder where modules are located. +The manifest file is still used as an entry-point. + +```ruby +Vagrant.configure("2") do |config| + config.vm.provision "puppet" do |puppet| + puppet.module_path = "modules" + end +end +``` + +Just like the manifests path, the modules path is relative to the project +root if a relative path is given. + +## Custom Facts + +Custom facts to be exposed by [Facter](https://puppetlabs.com/facter) +can be specified as well: + +```ruby +Vagrant.configure("2") do |config| + config.vm.provision "puppet" do |puppet| + puppet.facter = { + "vagrant" => "1" + } + end +end +``` + +Now, the `$vagrant` variable in your Puppet manifests will equal "1". + +## Configuring Hiera + +[Hiera](https://docs.puppetlabs.com/hiera/1/) configuration is also supported. +`hiera_config_path` specifies the path to the Hiera configuration file stored on +the host. If the `:datadir` setting in the Hiera configuration file is a +relative path, `working_directory` should be used to specify the directory in +the guest that path is relative to. + +```ruby +Vagrant.configure("2") do |config| + config.vm.provision "puppet" do |puppet| + puppet.hiera_config_path = "hiera.yaml" + puppet.working_directory = "/tmp/vagrant-puppet" + end +end +``` + +`hiera_config_path` can be relative or absolute. If it is relative, it is +relative to the project root. `working_directory` is an absolute path within the +guest. + +## Additional Options + +Puppet supports a lot of command-line flags. Basically any setting can +be overridden on the command line. To give you the most power and flexibility +possible with Puppet, Vagrant allows you to specify custom command line +flags to use: + +```ruby +Vagrant.configure("2") do |config| + config.vm.provision "puppet" do |puppet| + puppet.options = "--verbose --debug" + end +end +``` diff --git a/website/pages/docs/provisioning/salt.html.md b/website/pages/docs/provisioning/salt.html.md new file mode 100644 index 000000000..4f886f612 --- /dev/null +++ b/website/pages/docs/provisioning/salt.html.md @@ -0,0 +1,203 @@ +--- +layout: 'docs' +page_title: 'Salt - Provisioning' +sidebar_current: 'provisioning-salt' +description: |- + The Vagrant Salt provisioner allows you to provision the guest using + Salt states. +--- + +# Salt Provisioner + +**Provisioner name: `salt`** + +The Vagrant Salt provisioner allows you to provision the guest using +[Salt](http://saltstack.com/) states. + +Salt states are [YAML](https://en.wikipedia.org/wiki/YAML) documents +that describes the current state a machine should be in, e.g. what +packages should be installed, which services are running, and the +contents of arbitrary files. + +_NOTE: The Salt provisioner is builtin to Vagrant. If the `vagrant-salt` +plugin is installed, it should be uninstalled to ensure expected behavior._ + +## Masterless Quickstart + +What follows is a basic Vagrantfile that will get salt working +on a single minion, without a master: + +```ruby + Vagrant.configure("2") do |config| + ## Choose your base box + config.vm.box = "bionic64" + + ## For masterless, mount your salt file root + config.vm.synced_folder "salt/roots/", "/srv/salt/" + + ## Use all the defaults: + config.vm.provision :salt do |salt| + + salt.masterless = true + salt.minion_config = "salt/minion" + salt.run_highstate = true + + end + end +``` + +This sets up a shared folder for the salt root, and copies +the minion file over, then runs `state.highstate` on the +machine. Your minion file must contain the line +`file_client: local` in order to work in a +masterless setup. + +## Install Options + +The Salt provisioner uses the [Salt bootstrap script](https://github.com/saltstack/salt-bootstrap) +for installing Salt on your guest. These options build up the arguments used to +for the bootstrap script. + +- `install_master` (boolean) - Should vagrant install the salt-master + on this machine. Not supported on Windows guest machines. + +- `no_minion` (boolean) - Do not install the minion, default `false`. Not supported on Windows guest machines. + +- `install_syndic` (boolean) - Install the salt-syndic, default + `false`. Not supported on Windows guest machines. + +- `install_type` (stable | git | daily | testing) - Whether to install from a + distribution's stable package manager, git tree-ish, daily ppa, or testing repository. Not supported on Windows guest machines. + +- `install_args` (string, default: "develop") - When performing a git install, you can specify a branch, tag, or any treeish. Not supported on Windows. + +- `always_install` (boolean) - Installs salt binaries even + if they are already detected, default `false` + +- `bootstrap_script` (string) - Path to your customized salt-bootstrap.sh script. Not supported on Windows guest machines. + +- `bootstrap_options` (string) - Additional command-line options to + pass to the bootstrap script. + +- `version` (string) - Version of minion to be installed. Defaults to latest version. When specifying `version` you must also specify a `install_type`. + +- `python_version` (string, default: "2") - Major Python version of minion to be installed. Only valid for minion versions >= 2017.7.0. Only supported on Windows guest machines. + +## Minion Options + +These only make sense when `no_minion` is `false`. + +- `minion_config` (string, default: "salt/minion") - Path to + a custom salt minion config file. + +- `minion_key` (string, default: "salt/key/minion.key") - Path to your minion key + +- `minion_id` (string) - Unique identifier for minion. Used for masterless and preseeding keys. + +- `minion_pub` (string, default: "salt/key/minion.pub") - Path to your minion + public key + +- `grains_config` (string) - Path to a custom salt grains file. On Windows, the minion needs `ipc_mode: tcp` set otherwise it will [fail to communicate](https://github.com/saltstack/salt/issues/22796) with the master. + +- `masterless` (boolean) - Calls state.highstate in local mode. Uses `minion_id` and `pillar_data` when provided. + +- `minion_json_config` (string) - Valid json for configuring the salt minion + (`-j` in bootstrap-salt.sh). Not supported on Windows. + +- `salt_call_args` (array) - An array of additional command line flag arguments to be passed to the `salt-call` command when provisioning with masterless. + +## Master Options + +These only make sense when `install_master` is `true`. Not supported on Windows guest machines. + +- `master_config` (string, default: "salt/master") + Path to a custom salt master config file. + +- `master_key` (string, default: "salt/key/master.pem") - Path to your master key. + +- `master_pub` (string, default: "salt/key/master.pub") - Path to your master public key. + +- `seed_master` (dictionary) - Upload keys to master, thereby + pre-seeding it before use. Example: `{minion_name:/path/to/key.pub}` + +- `master_json_config` (string) - Valid json for configuring the salt master + (`-J` in bootstrap-salt.sh). Not supported on Windows. + +- `salt_args` (array) - An array of additional command line flag arguments to be passed to the `salt` command when provisioning with masterless. + +## Execute States + +Either of the following may be used to actually execute states +during provisioning. + +- `run_highstate` - (boolean) Executes `state.highstate` on + vagrant up. Can be applied to any machine. + +## Execute Runners + +Either of the following may be used to actually execute runners +during provisioning. + +- `run_overstate` - (boolean) Executes `state.over` on + vagrant up. Can be applied to the master only. This is superseded by + orchestrate. Not supported on Windows guest machines. + +- `orchestrations` - (array of strings) Executes `state.orchestrate` on + vagrant up. Can be applied to the master only. This is superseded by + run_overstate. Not supported on Windows guest machines. + +## Output Control + +These may be used to control the output of state execution: + +- `colorize` (boolean) - If true, output is colorized. Defaults to false. + +- `log_level` (string) - The verbosity of the outputs. Defaults to "debug". + Can be one of "all", "garbage", "trace", "debug", "info", or + "warning". Requires `verbose` to be set to "true". + +- `verbose` (boolean) - The verbosity of the outputs. Defaults to "false". + Must be true for log_level taking effect and the output of the salt-commands being displayed. + +## Pillar Data + +You can export pillar data for use during provisioning by using the `pillar` +command. Each call will merge the data so you can safely call it multiple +times. The data passed in should only be hashes and lists. Here is an example:: + +```ruby + config.vm.provision :salt do |salt| + + # Export hostnames for webserver config + salt.pillar({ + "hostnames" => { + "www" => "www.example.com", + "intranet" => "intranet.example.com" + } + }) + + # Export database credentials + salt.pillar({ + "database" => { + "user" => "jdoe", + "password" => "topsecret" + } + }) + + salt.run_highstate = true + + end +``` + +On Windows guests, this requires PowerShell 3.0 or higher. + +## Preseeding Keys + +Preseeding keys is the recommended way to handle provisioning +using a master. +On a machine with salt installed, run +`salt-key --gen-keys=[minion_id]` to generate the necessary +.pub and .pem files + +For an example of a more advanced setup, look at the original +[plugin](https://github.com/saltstack/salty-vagrant/tree/develop/example). diff --git a/website/pages/docs/provisioning/shell.html.md b/website/pages/docs/provisioning/shell.html.md new file mode 100644 index 000000000..25e67a38a --- /dev/null +++ b/website/pages/docs/provisioning/shell.html.md @@ -0,0 +1,250 @@ +--- +layout: 'docs' +page_title: 'Shell Scripts - Provisioning' +sidebar_current: 'provisioning-shell' +description: |- + The Vagrant Shell provisioner allows you to upload and execute a script within + the guest machine. +--- + +# Shell Provisioner + +**Provisioner name: `"shell"`** + +The Vagrant Shell provisioner allows you to upload and execute a script within +the guest machine. + +Shell provisioning is ideal for users new to Vagrant who want to get up +and running quickly and provides a strong alternative for users who are not +comfortable with a full configuration management system such as Chef or +Puppet. + +For POSIX-like machines, the shell provisioner executes scripts with +SSH. For Windows guest machines that are configured to use WinRM, the +shell provisioner executes PowerShell and Batch scripts over WinRM. + +## Options + +The shell provisioner takes various options. One of `inline` or `path` +is required: + +- `inline` (string) - Specifies a shell command inline to execute on the + remote machine. See the [inline scripts](#inline-scripts) section below + for more information. + +- `path` (string) - Path to a shell script to upload and execute. It can be a + script relative to the project Vagrantfile or a remote script (like a [gist](https://gist.github.com)). + +The remainder of the available options are optional: + +- `args` (string or array) - Arguments to pass to the shell script when executing it + as a single string. These arguments must be written as if they were typed + directly on the command line, so be sure to escape characters, quote, + etc. as needed. You may also pass the arguments in using an array. In this + case, Vagrant will handle quoting for you. + +- `binary` (boolean) - Vagrant automatically replaces Windows line endings with + Unix line endings. If this is false, then Vagrant will not do this. By default + this is "false". If the shell provisioner is communicating over WinRM, this + defaults to "true". + +- `env` (hash) - List of key-value pairs to pass in as environment variables to + the script. Vagrant will handle quoting for environment variable values, but + the keys remain untouched. + +- `keep_color` (boolean) - Vagrant automatically colors output in green and + red depending on whether the output is from stdout or stderr. If this is + true, Vagrant will not do this, allowing the native colors from the script + to be outputted. + +- `md5` (string) - MD5 checksum used to validate remotely downloaded shell files. + +- `name` (string) - This value will be displayed in the output so that + identification by the user is easier when many shell provisioners are present. + +- `powershell_args` (string) - Extra arguments to pass to `PowerShell` + if you are provisioning with PowerShell on Windows. + +- `powershell_elevated_interactive` (boolean) - Run an elevated script in interactive mode + on Windows. By default this is "false". Must also be `privileged`. Be sure to + enable auto-login for Windows as the user must be logged in for interactive + mode to work. + +- `privileged` (boolean) - Specifies whether to execute the shell script + as a privileged user or not (`sudo`). By default this is "true". Windows + guests use a scheduled task to run as a true administrator without the + WinRM limitations. + +- `reboot` (boolean) - Reboot the guest. This requires the guest to have a + reboot capability implemented. + +- `reset` (boolean) - Reset the communicator to the machine after completion. This + is useful when a shell may need to be reloaded. + +- `sha1` (string) - SHA1 checksum used to validate remotely downloaded shell files. + +- `sha256` (string) - SHA256 checksum used to validate remotely downloaded shell files. + +- `sha384` (string) - SHA384 checksum used to validate remotely downloaded shell files. + +- `sha512` (string) - SHA512 checksum used to validate remotely downloaded shell files. + +- `sensitive` (boolean) - Marks the Hash values used in the `env` option as sensitive + and hides them from output. By default this is "false". + +- `upload_path` (string) - Is the remote path where the shell script will + be uploaded to. The script is uploaded as the SSH user over SCP, so this + location must be writable to that user. By default this is + "/tmp/vagrant-shell". On Windows, this will default to + "C:\tmp\vagrant-shell". + + + +## Inline Scripts + +Perhaps the easiest way to get started is with an inline script. An +inline script is a script that is given to Vagrant directly within +the Vagrantfile. An example is best: + +```ruby +Vagrant.configure("2") do |config| + config.vm.provision "shell", + inline: "echo Hello, World" +end +``` + +This causes `echo Hello, World` to be run within the guest machine when +provisioners are run. + +Combined with a little bit more Ruby, this makes it very easy to embed +your shell scripts directly within your Vagrantfile. Another example below: + +```ruby +$script = <<-SCRIPT +echo I am provisioning... +date > /etc/vagrant_provisioned_at +SCRIPT + +Vagrant.configure("2") do |config| + config.vm.provision "shell", inline: $script +end +``` + +In the code block above, the script block starts with `<<-SCRIPT` and ends with `SCRIPT`. +This is known as a "Here Document" or a "heredoc". Additionally, if your script +relies on quotes and you do not wish for Ruby to escape your quotes, you may +want to use this style of heredoc where `SCRIPT` is surrounded in single quotes: + +```ruby +$script = <<-'SCRIPT' +echo "These are my \"quotes\"! I am provisioning my guest." +date > /etc/vagrant_provisioned_at +SCRIPT + +Vagrant.configure("2") do |config| + config.vm.provision "shell", inline: $script +end +``` + +Now that our "heredoc" is quoted, our script will preserve the quotes in the string to `echo`: + +``` +==> default: Running provisioner: shell... + default: Running: inline script + default: These are my "quotes"! I am provisioning my guest. +``` + +For more examples of how to use "heredoc" in Ruby, please refer to the +[Ruby documentation](https://ruby-doc.org/core-2.5.0/doc/syntax/literals_rdoc.html#label-Here+Documents). + +It is understandable that if you are not familiar with Ruby, the above may seem very +advanced or foreign. But do not fear, what it is doing is quite simple: +the script is assigned to a global variable `$script`. This global variable +contains a string which is then passed in as the inline script to the +Vagrant configuration. + +Of course, if any Ruby in your Vagrantfile outside of basic variable assignment +makes you uncomfortable, you can use an actual script file, documented in +the next section. + +For Windows guest machines, the supported inline script is dependent upon the +communicator in use. When using the `winrm` communicator, the inline script +_must_ be PowerShell. Batch scripts are not allowed as inline scripts when +using the `winrm` communicator. When using the `winssh` communicator, the +inline script will be run using the configured `shell` which defaults to +PowerShell. + +## External Script + +The shell provisioner can also take an option specifying a path to +a shell script on the host machine. Vagrant will then upload this script +into the guest and execute it. An example: + +```ruby +Vagrant.configure("2") do |config| + config.vm.provision "shell", path: "script.sh" +end +``` + +Relative paths, such as above, are expanded relative to the location +of the root Vagrantfile for your project. Absolute paths can also be used, +as well as shortcuts such as `~` (home directory) and `..` (parent directory). + +If you use a remote script as part of your provisioning process, you can pass in +its URL as the `path` argument as well: + +```ruby +Vagrant.configure("2") do |config| + config.vm.provision "shell", path: "https://example.com/provisioner.sh" +end +``` + +If you are running a Batch or PowerShell script for Windows, make sure +that the external path has the proper extension (".bat" or ".ps1"), because +Windows uses this to determine what kind of file it is to execute. Additionally, +if you are running Vagrant on something like Cygwin or WSL where bash is +available, then you should be able to use an extension like ".sh". + +```ruby +Vagrant.configure("2") do |config| + config.vm.provision "shell", path: "scripts/PowershellScript.ps1" +end +``` + +To run a script already available on the guest you can use an inline script to +invoke the remote script on the guest. + +```ruby +Vagrant.configure("2") do |config| + config.vm.provision "shell", + inline: "/bin/sh /path/to/the/script/already/on/the/guest.sh" +end +``` + +## Script Arguments + +You can parameterize your scripts as well like any normal shell script. +These arguments can be specified to the shell provisioner. They should +be specified as a string as they'd be typed on the command line, so +be sure to properly escape anything: + +```ruby +Vagrant.configure("2") do |config| + config.vm.provision "shell" do |s| + s.inline = "echo $1" + s.args = "'hello, world!'" + end +end +``` + +You can also specify arguments as an array if you do not want to worry about +quoting: + +```ruby +Vagrant.configure("2") do |config| + config.vm.provision "shell" do |s| + s.inline = "echo $1" + s.args = ["hello, world!"] + end +end +``` diff --git a/website/pages/docs/push/ftp.html.md b/website/pages/docs/push/ftp.html.md new file mode 100644 index 000000000..562167403 --- /dev/null +++ b/website/pages/docs/push/ftp.html.md @@ -0,0 +1,63 @@ +--- +layout: 'docs' +page_title: 'Vagrant Push - FTP & SFTP Strategy' +sidebar_current: 'push-ftp' +description: |- + Vagrant Push FTP and SFTP strategy pushes the code in your Vagrant development + environment to a remote FTP or SFTP server. +--- + +# Vagrant Push + +## FTP & SFTP Strategy + +Vagrant Push FTP and SFTP strategy pushes the code in your Vagrant development +environment to a remote FTP or SFTP server. + +The Vagrant Push FTP And SFTP strategy supports the following configuration +options: + +- `host` - The address of the remote (S)FTP server. If the (S)FTP server is + running on a non-standard port, you can specify the port after the address + (`host:port`). + +- `username` - The username to use for authentication with the (S)FTP server. + +- `password` - The password to use for authentication with the (S)FTP server. + +- `passive` - Use passive FTP (default is true). + +- `secure` - Use secure (SFTP) (default is false). + +- `destination` - The root destination on the target system to sync the files + (default is `/`). + +- `exclude` - Add a file or file pattern to exclude from the upload, relative to + the `dir`. This value may be specified multiple times and is additive. + `exclude` take precedence over `include` values. + +- `include` - Add a file or file pattern to include in the upload, relative to + the `dir`. This value may be specified multiple times and is additive. + +- `dir` - The base directory containing the files to upload. By default this is + the same directory as the Vagrantfile, but you can specify this if you have + a `src` folder or `bin` folder or some other folder you want to upload. + +### Usage + +The Vagrant Push FTP and SFTP strategy is defined in the `Vagrantfile` using the +`ftp` key: + +```ruby +config.push.define "ftp" do |push| + push.host = "ftp.company.com" + push.username = "username" + push.password = "password" +end +``` + +And then push the application to the FTP or SFTP server: + +```shell +$ vagrant push +``` diff --git a/website/pages/docs/push/heroku.html.md b/website/pages/docs/push/heroku.html.md new file mode 100644 index 000000000..ad6413ab8 --- /dev/null +++ b/website/pages/docs/push/heroku.html.md @@ -0,0 +1,61 @@ +--- +layout: 'docs' +page_title: 'Vagrant Push - Heroku Strategy' +sidebar_current: 'push-heroku' +description: |- + The Vagrant Push Heroku strategy pushes your application's code to Heroku. + Only files which are committed to the Git repository are pushed to Heroku. +--- + +# Vagrant Push + +## Heroku Strategy + +[Heroku][] is a public PAAS provider that makes it easy to deploy an +application. The Vagrant Push Heroku strategy pushes your application's code to +Heroku. + +
+ Warning: The Vagrant Push Heroku strategy requires you + have configured your Heroku credentials and created the Heroku application. + This documentation will not cover these prerequisites, but you can read more + about them in the Heroku documentation. +
+ +Only files which are committed to the Git repository will be pushed to Heroku. +Additionally, the current working branch is always pushed to the Heroku, even if +it is not the "master" branch. + +The Vagrant Push Heroku strategy supports the following configuration options: + +- `app` - The name of the Heroku application. If the Heroku application does not + exist, an exception will be raised. If this value is not specified, the + basename of the directory containing the `Vagrantfile` is assumed to be the + name of the Heroku application. Since this value can change between users, it + is highly recommended that you add the `app` setting to your `Vagrantfile`. + +- `dir` - The base directory containing the Git repository to upload to Heroku. + By default this is the same directory as the Vagrantfile, but you can specify + this if you have a nested Git directory. + +- `remote` - The name of the Git remote where Heroku is configured. The default + value is "heroku". + +### Usage + +The Vagrant Push Heroku strategy is defined in the `Vagrantfile` using the +`heroku` key: + +```ruby +config.push.define "heroku" do |push| + push.app = "my_application" +end +``` + +And then push the application to Heroku: + +```shell +$ vagrant push +``` + +[heroku]: https://heroku.com/ 'Heroku' diff --git a/website/pages/docs/push/index.html.md b/website/pages/docs/push/index.html.md new file mode 100644 index 000000000..26e1a4ec7 --- /dev/null +++ b/website/pages/docs/push/index.html.md @@ -0,0 +1,59 @@ +--- +layout: 'docs' +page_title: 'Vagrant Push' +sidebar_current: 'push' +description: |- + Vagrant Push is a revolutionary feature that allows users to push the code in + their Vagrant environment to a remote location. +--- + +# Vagrant Push + +As of version 1.7, Vagrant is capable of deploying or "pushing" application code +in the same directory as your Vagrantfile to a remote such as an FTP server. + +Pushes are defined in an application's `Vagrantfile` and are invoked using the +`vagrant push` subcommand. Much like other components of Vagrant, each Vagrant +Push plugin has its own configuration options. Please consult the documentation +for your Vagrant Push plugin for more information. Here is an example Vagrant +Push configuration section in a `Vagrantfile`: + +```ruby +config.push.define "ftp" do |push| + push.host = "ftp.company.com" + push.username = "..." + # ... +end +``` + +When the application is ready to be deployed to the FTP server, just run a +single command: + +```shell +$ vagrant push +``` + +Much like [Vagrant Providers][], Vagrant Push also supports multiple backend +declarations. Consider the common scenario of a staging and QA environment: + +```ruby +config.push.define "staging", strategy: "ftp" do |push| + # ... +end + +config.push.define "qa", strategy: "ftp" do |push| + # ... +end +``` + +In this scenario, the user must pass the name of the Vagrant Push to the +subcommand: + +```shell +$ vagrant push staging +``` + +Vagrant Push is the easiest way to deploy your application. You can read more +in the documentation links on the sidebar. + +[vagrant providers]: /docs/providers/ 'Vagrant Providers' diff --git a/website/pages/docs/push/local-exec.html.md b/website/pages/docs/push/local-exec.html.md new file mode 100644 index 000000000..eafbbed75 --- /dev/null +++ b/website/pages/docs/push/local-exec.html.md @@ -0,0 +1,80 @@ +--- +layout: 'docs' +page_title: 'Vagrant Push - Local Exec Strategy' +sidebar_current: 'push-local-exec' +description: |- + The Vagrant Push Local Exec strategy pushes your application's code using a + user-defined script. +--- + +# Vagrant Push + +## Local Exec Strategy + +The Vagrant Push Local Exec strategy allows the user to invoke an arbitrary +shell command or script as part of a push. + +
+ Warning: The Vagrant Push Local Exec strategy does not + perform any validation on the correctness of the shell script. +
+ +The Vagrant Push Local Exec strategy supports the following configuration +options: + +- `script` - The path to a script on disk (relative to the `Vagrantfile`) to + execute. Vagrant will attempt to convert this script to an executable, but an + exception will be raised if that fails. +- `inline` - The inline script to execute (as a string). +- `args` (string or array) - Optional arguments to pass to the shell script when executing it + as a single string. These arguments must be written as if they were typed + directly on the command line, so be sure to escape characters, quote, + etc. as needed. You may also pass the arguments in using an array. In this + case, Vagrant will handle quoting for you. + +Please note - only one of the `script` and `inline` options may be specified in +a single push definition. + +### Usage + +The Vagrant Push Local Exec strategy is defined in the `Vagrantfile` using the +`local-exec` key: + +Remote path: + +```ruby +config.push.define "local-exec" do |push| + push.inline = <<-SCRIPT + scp -r . server:/var/www/website + SCRIPT +end +``` + +Local path: + +```ruby +config.push.define "local-exec" do |push| + push.inline = <<-SCRIPT + cp -r . /var/www/website + SCRIPT +end +``` + +For more complicated scripts, you may store them in a separate file and read +them from the `Vagrantfile` like so: + +```ruby +config.push.define "local-exec" do |push| + push.script = "my-script.sh" +end +``` + +And then invoke the push with Vagrant: + +```shell +$ vagrant push +``` + +### Script Arguments + +Refer to [Shell Provisioner](/docs/provisioning/shell.html). diff --git a/website/pages/docs/share/connect.html.md b/website/pages/docs/share/connect.html.md new file mode 100644 index 000000000..1a97960f3 --- /dev/null +++ b/website/pages/docs/share/connect.html.md @@ -0,0 +1,54 @@ +--- +layout: 'docs' +page_title: 'Vagrant Connect - Vagrant Share' +sidebar_current: 'share-connect' +description: |- + Vagrant can share any or every port to your Vagrant environment, not + just SSH and HTTP. +--- + +# Vagrant Connect + +Vagrant can share any or _every_ port to your Vagrant environment, not +just SSH and HTTP. The `vagrant connect` command gives the connecting person +a static IP they can use to communicate to the shared Vagrant environment. +Any TCP traffic sent to this IP is sent to the shared Vagrant environment. + +## Usage + +Just call `vagrant share --full`. This will automatically share as many ports as +possible for remote connections. Please see +[the Vagrant share security page](/docs/share/security.html) for more +information. + +Note the share name at the end of calling `vagrant share --full`, and give this to +the person who wants to connect to your machine. They simply have to call +`vagrant connect NAME`. This will give them a static IP they can use to access +your Vagrant environment. + +## How does it work? + +`vagrant connect` works by doing what Vagrant does best: managing virtual +machines. `vagrant connect` creates a tiny virtual machine that takes up +only around 20 MB in RAM, using VirtualBox or VMware (more provider support +is coming soon). + +Any traffic sent to this tiny virtual machine is then proxied through to +the shared Vagrant environment as if it were directed at it. + +## Beware: Vagrant Insecure Key + +If the Vagrant environment or box you are using is protected with the +Vagrant insecure keypair (most public boxes are), then SSH will be easily +available to anyone who connects. + +While hopefully you are sharing with someone you trust, in certain environments +you might be sharing with a class, or a conference, and you do not want them +to be able to SSH in. + +In this case, we recommend changing or removing the insecure key from +the Vagrant machine. + +Finally, we want to note that we are working on making it so that when +Vagrant share is used, the Vagrant private key is actively rejected unless +explicitly allowed. This feature is not yet done, however. diff --git a/website/pages/docs/share/http.html.md b/website/pages/docs/share/http.html.md new file mode 100644 index 000000000..77a1eb4ca --- /dev/null +++ b/website/pages/docs/share/http.html.md @@ -0,0 +1,88 @@ +--- +layout: 'docs' +page_title: 'HTTP Sharing - Vagrant Share' +sidebar_current: 'share-http' +description: |- + Vagrant Share can create a publicly accessible URL endpoint to access an + HTTP server running in your Vagrant environment. This is known as "HTTP + sharing," and is enabled by default when "vagrant share" is used. +--- + +# HTTP Sharing + +Vagrant Share can create a publicly accessible URL endpoint to access an +HTTP server running in your Vagrant environment. This is known as "HTTP +sharing," and is enabled by default when `vagrant share` is used. + +Because this mode of sharing creates a publicly accessible URL, the accessing +party does not need to have Vagrant installed in order to view your environment. + +This has a number of useful use cases: you can test webhooks by exposing +your Vagrant environment to the internet, you can show your work to clients, +teammates, or managers, etc. + +## Usage + +To use HTTP sharing, simply run `vagrant share`: + +``` +$ vagrant share +==> default: Detecting network information for machine... +default: Local machine address: 192.168.84.130 +default: Local HTTP port: 9999 +default: Local HTTPS port: disabled +==> default: Creating Vagrant Share session... +==> default: HTTP URL: http://b1fb1f3f.ngrok.io +``` + +Vagrant detects where your HTTP server is running in your Vagrant environment +and outputs the endpoint that can be used to access this share. Just give +this URL to anyone you want to share it with, and they will be able to access +your Vagrant environment! + +If Vagrant has trouble detecting the port of your servers in your environment, +use the `--http` and/or `--https` flags to be more explicit. + +The share will be accessible for the duration that `vagrant share` is running. +Press `Ctrl-C` to quit the sharing session. + +
+ Warning: This URL is accessible by anyone + who knows it, so be careful if you are sharing sensitive information. +
+ +## Disabling + +If you want to disable the creation of the publicly accessible endpoint, +run `vagrant share` with the `--disable-http` flag. This will share your +environment using one of the other methods available, and will not create +the URL endpoint. + +## Missing Assets + +Shared web applications must use **relative paths** for loading any +local assets such as images, stylesheets, javascript. + +The web application under development will be accessed remotely. This means +that if you have any hardcoded asset (images, stylesheets, etc.) URLs +such as ``, then they will not load +for people accessing your share. + +Most web frameworks or toolkits have settings or helpers to generate +relative paths. For example, if you are a WordPress developer, the +[Root Relative URLs](http://wordpress.org/plugins/root-relative-urls/) plugin +will automatically do this for you. + +Relative URLs to assets is generally a best practice in general, so you +should do this anyways! + +## HTTPS (SSL) + +Vagrant Share can also expose an SSL port that can be accessed over +SSL. Creating an HTTPS share requires a non-free ngrok account. + +`vagrant share` by default looks for any SSL traffic on port 443 in your +development environment. If it cannot find any, then SSL is disabled by +default. + +The HTTPS share can be explicitly disabled using the `--disable-https` flag. diff --git a/website/pages/docs/share/index.html.md b/website/pages/docs/share/index.html.md new file mode 100644 index 000000000..3eaaa71e6 --- /dev/null +++ b/website/pages/docs/share/index.html.md @@ -0,0 +1,51 @@ +--- +layout: 'docs' +page_title: 'Vagrant Share' +sidebar_current: 'share' +description: |- + Vagrant Share allows you to share your Vagrant environment with anyone in + the world, enabling collaboration directly in your Vagrant environment + in almost any network environment with just a single command- "vagrant share". +--- + +# Vagrant Share + +Vagrant Share allows you to share your Vagrant environment with anyone in +the world, enabling collaboration directly in your Vagrant environment +in almost any network environment with just a single command: +`vagrant share`. + +Vagrant share has three primary modes or features. These features are not +mutually exclusive, meaning that any combination of them can be active +at any given time: + +- **HTTP sharing** will create a URL that you can give to anyone. This + URL will route directly into your Vagrant environment. The person using + this URL does not need Vagrant installed, so it can be shared with anyone. + This is useful for testing webhooks or showing your work to clients, + teammates, managers, etc. + +- **SSH sharing** will allow instant SSH access to your Vagrant environment + by anyone by running `vagrant connect --ssh` on the remote side. This + is useful for pair programming, debugging ops problems, etc. + +- **General sharing** allows anyone to access any exposed port of your + Vagrant environment by running `vagrant connect` on the remote side. + This is useful if the remote side wants to access your Vagrant + environment as if it were a computer on the LAN. + +The details of each are covered in their specific section in the sidebar +to the left. We also have a section where we go into detail about the +security implications of this feature. + +## Installation + +Vagrant Share is a Vagrant plugin that must be installed. It is not +included with Vagrant system packages. To install the Vagrant Share +plugin, run the following command: + +```shell +$ vagrant plugin install vagrant-share +``` + +Vagrant Share requires [ngrok](https://ngrok.com) to be used. diff --git a/website/pages/docs/share/provider.html.md b/website/pages/docs/share/provider.html.md new file mode 100644 index 000000000..3655ea2a1 --- /dev/null +++ b/website/pages/docs/share/provider.html.md @@ -0,0 +1,28 @@ +--- +layout: 'docs' +page_title: 'Custom Provider - Vagrant Share' +sidebar_current: 'share-provider' +description: |- + If you are developing a custom Vagrant provider, you will need to do a tiny + bit more work in order for it to work well with Vagrant Share. +--- + +# Custom Provider + +
+ Warning: Advanced Topic! This topic is related to + developing Vagrant plugins. If you are not interested in this or + you are just starting with Vagrant, it is safe to skip this page. +
+ +If you are developing a [custom Vagrant provider](/docs/plugins/providers.html), +you will need to do a tiny bit more work in order for it to work well with +Vagrant Share. + +For now, this is only one step: + +- `public_address` provider capability - You must implement this capability + to return a string that is an address that can be used to access the + guest from Vagrant. This does not need to be a globally routable address, + it only needs to be accessible from the machine running Vagrant. If you + cannot detect an address, return `nil`. diff --git a/website/pages/docs/share/security.html.md b/website/pages/docs/share/security.html.md new file mode 100644 index 000000000..b840a1be0 --- /dev/null +++ b/website/pages/docs/share/security.html.md @@ -0,0 +1,37 @@ +--- +layout: 'docs' +page_title: 'Security - Vagrant Share' +sidebar_current: 'share-security' +description: |- + Sharing your Vagrant environment understandably raises a number of security + concerns. +--- + +# Security + +Sharing your Vagrant environment understandably raises a number of security +concerns. + +The primary security mechanism for Vagrant +Share is security through obscurity along with an encryption key for SSH. +Additionally, there are several configuration options made available to +help control access and manage security: + +- `--disable-http` will not create a publicly accessible HTTP URL. When + this is set, the only way to access the share is with `vagrant connect`. + +In addition to these options, there are other features we've built to help: + +- Vagrant share uses end-to-end TLS for non-HTTP connections. So even unencrypted + TCP streams are encrypted through the various proxies and only unencrypted during + the final local communication between the local proxy and the Vagrant environment. + +- SSH keys are encrypted by default, using a password that is not transmitted + to our servers or across the network at all. + +- SSH is not shared by default, it must explicitly be shared with the + `--ssh` flag. + +Most importantly, you must understand that by running `vagrant share`, +you are making your Vagrant environment accessible by anyone who knows +the share name. When share is not running, it is not accessible. diff --git a/website/pages/docs/share/ssh.html.md b/website/pages/docs/share/ssh.html.md new file mode 100644 index 000000000..1abe05f49 --- /dev/null +++ b/website/pages/docs/share/ssh.html.md @@ -0,0 +1,101 @@ +--- +layout: 'docs' +page_title: 'SSH Sharing - Vagrant Share' +sidebar_current: 'share-ssh' +description: |- + Vagrant share makes it trivially easy to allow remote SSH access to your + Vagrant environment by supplying the "--ssh" flag to "vagrant share". +--- + +# SSH Sharing + +Vagrant share makes it trivially easy to allow remote SSH access to your +Vagrant environment by supplying the `--ssh` flag to `vagrant share`. + +Easy SSH sharing is incredibly useful if you want to give access to +a colleague for troubleshooting ops issues. Additionally, it enables +pair programming with a Vagrant environment, if you want! + +SSH sharing is disabled by default as a security measure. To enable +SSH sharing, simply supply the `--ssh` flag when calling `vagrant share`. + +## Usage + +Just run `vagrant share --ssh`! + +When SSH sharing is enabled, Vagrant generates a brand new keypair for +SSH access. The public key portion is automatically inserted +into the Vagrant machine, and the private key portion is provided to the +user connecting to the Vagrant share. This private key is encrypted using +a password that you will be prompted for. This password is _never_ transmitted +across the network by Vagrant, and is an extra layer of security preventing +anyone who may know your share name from easily accessing your machine. + +After running `vagrant share --ssh`, it will output the name of your share: + +``` +$ vagrant share --ssh +==> default: Detecting network information for machine... +default: Local machine address: 192.168.84.130 +==> default: Generating new SSH key... +default: Please enter a password to encrypt the key: +default: Repeat the password to confirm: +default: Inserting generated SSH key into machine... +default: Local HTTP port: disabled +default: Local HTTPS port: disabled +default: SSH Port: 2200 +==> default: Creating Vagrant Share session... +share: Cloning VMware VM: 'hashicorp/vagrant-share'. This can take some time... +share: Verifying vmnet devices are healthy... +share: Preparing network adapters... +share: Starting the VMware VM... +share: Waiting for machine to boot. This may take a few minutes... +share: SSH address: 192.168.84.134:22 +share: SSH username: tc +share: SSH auth method: password +share: +share: Inserting generated public key within guest... +share: Removing insecure key from the guest if it's present... +share: Key inserted! Disconnecting and reconnecting using new SSH key... +share: Machine booted and ready! +share: Forwarding ports... +share: -- 31338 => 65534 +share: -- 22 => 2202 +share: SSH address: 192.168.84.134:22 +share: SSH username: tc +share: SSH auth method: password +share: Configuring network adapters within the VM... +==> share: +==> share: Your Vagrant Share is running! Name: bazaar_wolf:sultan_oasis +==> share: +==> share: You're sharing with SSH access. This means that another can SSH to +==> share: your Vagrant machine by running: +==> share: +==> share: vagrant connect --ssh bazaar_wolf:sultan_oasis +==> share: +``` + +Anyone can then SSH directly to your Vagrant environment by running +`vagrant connect --ssh NAME` where NAME is the name of the share outputted +previously. + +``` +$ vagrant connect --ssh bazaar_wolf:sultan_oasis +Loading share 'bazaar_wolf:sultan_oasis'... +The SSH key to connect to this share is encrypted. You will +require the password entered when creating the share to +decrypt it. Verify you have access to this password before +continuing. + +Press enter to continue, or Ctrl-C to exit now. +Password for the private key: +Executing SSH... +Welcome to Ubuntu 12.04.3 LTS (GNU/Linux 3.8.0-29-generic x86_64) + + * Documentation: https://help.ubuntu.com/ +Last login: Fri Mar 7 17:44:50 2014 from 192.168.163.1 +vagrant@vagrant:~$ +``` + +If the private key is encrypted (the default behavior), then the connecting +person will be prompted for the password to decrypt the private key. diff --git a/website/pages/docs/synced-folders/basic_usage.html.md b/website/pages/docs/synced-folders/basic_usage.html.md new file mode 100644 index 000000000..59f612ccf --- /dev/null +++ b/website/pages/docs/synced-folders/basic_usage.html.md @@ -0,0 +1,128 @@ +--- +layout: 'docs' +page_title: 'Basic Usage - Synced Folders' +sidebar_current: 'syncedfolder-basic' +description: |- + Synced folders are configured within your Vagrantfile using the + "config.vm.synced_folder" method. +--- + +# Basic Usage + +## Configuration + +Synced folders are configured within your Vagrantfile using the +`config.vm.synced_folder` method. Usage of the configuration directive +is very simple: + +```ruby +Vagrant.configure("2") do |config| + # other config here + + config.vm.synced_folder "src/", "/srv/website" +end +``` + +The first parameter is a path to a directory on the host machine. If +the path is relative, it is relative to the project root. The second +parameter must be an absolute path of where to share the folder within +the guest machine. This folder will be created (recursively, if it must) +if it does not exist. By default, Vagrant mounts the synced folders with +the owner/group set to the SSH user and any parent folders set to root. + +## Options + +You may also specify additional optional parameters when configuring +synced folders. These options are listed below. More detailed examples of using +some of these options are shown below this section, note the owner/group example +supplies two additional options separated by commas. + +In addition to these options, the specific synced folder type might +allow more options. See the documentation for your specific synced folder +type for more details. The built-in synced folder types are documented +in other pages available in the navigation for these docs. + +- `create` (boolean) - If true, the host path will be created if it + does not exist. Defaults to false. + +- `disabled` (boolean) - If true, this synced folder will be disabled and + will not be setup. This can be used to disable a previously defined synced + folder or to conditionally disable a definition based on some external + factor. + +- `group` (string) - The group that will own the synced folder. By default + this will be the SSH user. Some synced folder types do not support + modifying the group. + +- `mount_options` (array) - A list of additional mount options to pass + to the `mount` command. + +- `owner` (string) - The user who should be the owner of this synced folder. + By default this will be the SSH user. Some synced folder types do not + support modifying the owner. + +- `type` (string) - The type of synced folder. If this is not specified, + Vagrant will automatically choose the best synced folder option for your + environment. Otherwise, you can specify a specific type such as "nfs". + +- `id` (string) - The name for the mount point of this synced folder in the + guest machine. This shows up when you run `mount` in the guest machine. + +## Enabling + +Synced folders are automatically setup during `vagrant up` and +`vagrant reload`. + +## Disabling + +Synced folders can be disabled by adding the `disabled` option to +any definition: + +```ruby +Vagrant.configure("2") do |config| + config.vm.synced_folder "src/", "/srv/website", disabled: true +end +``` + +Disabling the default `/vagrant` share can be done as follows: + +```ruby +config.vm.synced_folder ".", "/vagrant", disabled: true +``` + +## Modifying the Owner/Group + +Sometimes it is preferable to mount folders with a different owner/group than +the default SSH user. Keep in mind that these options will only affect the +synced folder itself. If you want to modify the owner/group of the synced +folder's parent folders use a script. It is possible to set these options: + +```ruby +config.vm.synced_folder "src/", "/srv/website", + owner: "root", group: "root" +``` + +_NOTE: Owner and group IDs defined within `mount_options` will have precedence +over the `owner` and `group` options._ + +For example, given the following configuration: + +```ruby +config.vm.synced_folder ".", "/vagrant", owner: "vagrant", + group: "vagrant", mount_options: ["uid=1234", "gid=1234"] +``` + +the mounted synced folder will be owned by the user with ID `1234` and the +group with ID `1234`. The `owner` and `group` options will be ignored. + +## Symbolic Links + +Support for symbolic links across synced folder implementations and +host/guest combinations is not consistent. Vagrant does its best to +make sure symbolic links work by configuring various hypervisors (such +as VirtualBox), but some host/guest combinations still do not work +properly. This can affect some development environments that rely on +symbolic links. + +The recommendation is to make sure to test symbolic links on all the +host/guest combinations you sync folders on if this is important to you. diff --git a/website/pages/docs/synced-folders/index.html.md b/website/pages/docs/synced-folders/index.html.md new file mode 100644 index 000000000..26329d554 --- /dev/null +++ b/website/pages/docs/synced-folders/index.html.md @@ -0,0 +1,23 @@ +--- +layout: 'docs' +page_title: 'Synced Folders' +sidebar_current: 'syncedfolder' +description: |- + Synced folders enable Vagrant to sync a folder on the host machine to the + guest machine, allowing you to continue working on your project's files + on your host machine, but use the resources in the guest machine to + compile or run your project. +--- + +# Synced Folders + +Synced folders enable Vagrant to sync a folder on the host machine to the +guest machine, allowing you to continue working on your project's files +on your host machine, but use the resources in the guest machine to +compile or run your project. + +By default, Vagrant will share your project directory (the directory +with the [Vagrantfile](/docs/vagrantfile/)) to `/vagrant`. + +Read the [basic usage](/docs/synced-folders/basic_usage.html) page to get started +with synced folders. diff --git a/website/pages/docs/synced-folders/nfs.html.md b/website/pages/docs/synced-folders/nfs.html.md new file mode 100644 index 000000000..f75ed9893 --- /dev/null +++ b/website/pages/docs/synced-folders/nfs.html.md @@ -0,0 +1,233 @@ +--- +layout: 'docs' +page_title: 'NFS - Synced Folders' +sidebar_current: 'syncedfolder-nfs' +description: |- + In some cases the default shared folder implementations such as VirtualBox + shared folders have high performance penalties. If you are seeing less than + ideal performance with synced folders, NFS can offer a solution. Vagrant has + built-in support to orchestrate the configuration of the NFS server on the host + and guest for you. +--- + +# NFS + +In some cases the default shared folder implementations (such as VirtualBox +shared folders) have high performance penalties. If you are seeing less +than ideal performance with synced folders, [NFS](https://en.wikipedia.org/wiki/Network_File_System_%28protocol%29) +can offer a solution. Vagrant has built-in support to orchestrate the +configuration of the NFS server on the host and guest for you. + +~> **Windows users:** NFS folders do not work on Windows hosts. Vagrant will +ignore your request for NFS synced folders on Windows. + +## Prerequisites + +Before using synced folders backed by NFS, the host machine must have +`nfsd` installed, the NFS server daemon. This comes pre-installed on Mac +OS X, and is typically a simple package install on Linux. + +Additionally, the guest machine must have NFS support installed. This is +also usually a simple package installation away. + +If you are using the VirtualBox provider, you will also need to make sure you +have a +[private network set up](/docs/networking/private_network.html). This is due to a limitation of VirtualBox's built-in networking. With +VMware, you do not need this. + +## Enabling NFS Synced Folders + +To enable NFS, just add the `type: "nfs"` flag onto your synced folder: + +```ruby +Vagrant.configure("2") do |config| + config.vm.synced_folder ".", "/vagrant", type: "nfs" +end +``` + +If you add this to an existing Vagrantfile that has a running guest machine, +be sure to `vagrant reload` to see your changes. + +## NFS Synced Folder Options + +NFS synced folders have a set of options that can be specified that are +unique to NFS. These are listed below. These options can be specified in +the final part of the `config.vm.synced_folder` definition, along with the +`type` option. + +- `nfs_export` (boolean) - If this is false, then Vagrant will not modify + your `/etc/exports` automatically and assumes you've done so already. + +- `nfs_udp` (boolean) - Whether or not to use UDP as the transport. UDP + is faster but has some limitations (see the NFS documentation for more + details). This defaults to true. + +- `nfs_version` (string | integer) - The NFS protocol version to use when + mounting the folder on the guest. This defaults to 3. + +## NFS Global Options + +There are also more global NFS options you can set with `config.nfs` in +the Vagrantfile. These are documented below: + +- `functional` (bool) - Defaults to true. If false, then NFS will not be used + as a synced folder type. If a synced folder specifically requests NFS, + it will error. + +- `map_uid` and `map_gid` (int) - The UID/GID, respectively, to map all + read/write requests too. This will not affect the owner/group within the + guest machine itself, but any writes will behave as if they were written + as this UID/GID on the host. This defaults to the current user running + Vagrant. + +- `verify_installed` (bool) - Defaults to true. If this is false, then + Vagrant will skip checking if NFS is installed. + +## Specifying NFS Arguments + +In addition to the options specified above, it is possible for Vagrant to +specify alternate NFS arguments when mounting the NFS share by using the +`mount_options` key. For example, to use the `actimeo=2` client mount option: + +```ruby +config.vm.synced_folder ".", "/vagrant", + type: "nfs", + mount_options: ['actimeo=2'] +``` + +This would result in the following `mount` command being executed on the guest: + +``` +mount -o 'actimeo=2' 172.28.128.1:'/path/to/vagrantfile' /vagrant +``` + +You can also tweak the arguments specified in the `/etc/exports` template +when the mount is added, by using the OS-specific `linux__nfs_options` or +`bsd__nfs_options` keys. Note that these options completely override the default +arguments that are added by Vagrant automatically. For example, to make the +NFS share asynchronous: + +```ruby +config.vm.synced_folder ".", "/vagrant", + type: "nfs", + linux__nfs_options: ['rw','no_subtree_check','all_squash','async'] +``` + +This would result in the following content in `/etc/exports` on the host (note +the added `async` flag): + +``` +# VAGRANT-BEGIN: 21171 5b8f0135-9e73-4166-9bfd-ac43d5f14261 +"/path/to/vagrantfile" 172.28.128.5(rw,no_subtree_check,all_squash,async,anonuid=21171,anongid=660,fsid=3382034405) +# VAGRANT-END: 21171 5b8f0135-9e73-4166-9bfd-ac43d5f14261 +``` + +## Root Privilege Requirement + +To configure NFS, Vagrant must modify system files on the host. Therefore, +at some point during the `vagrant up` sequence, you may be prompted for +administrative privileges (via the typical `sudo` program). These +privileges are used to modify `/etc/exports` as well as to start and +stop the NFS server daemon. + +If you do not want to type your password on every `vagrant up`, Vagrant +uses thoughtfully crafted commands to make fine-grained sudoers modifications +possible to avoid entering your password. + +Below, we have a couple example sudoers entries. Note that you may +have to modify them _slightly_ on certain hosts because the way Vagrant +modifies `/etc/exports` changes a bit from OS to OS. If the commands below +are located in non-standard paths, modify them as appropriate. + +Also note that in the sudoer file format, entries are applied in order. If you've added the appropriate entries but still have to type in your password, make sure the entries aren't inserted too early. From the sudoers man page: "When multiple entries match for a user, they are applied in order. Where there are multiple matches, the last match is used (which is not necessarily the most specific match)." + +For \*nix users, make sure to edit your `/etc/sudoers` file with `visudo`. It protects you against syntax errors which could leave you without the ability to gain elevated privileges. + +All of the snippets below require Vagrant version 1.7.3 or higher. + + + +For OS X, sudoers should have this entry: + +``` +Cmnd_Alias VAGRANT_EXPORTS_ADD = /usr/bin/tee -a /etc/exports +Cmnd_Alias VAGRANT_NFSD = /sbin/nfsd restart +Cmnd_Alias VAGRANT_EXPORTS_REMOVE = /usr/bin/sed -E -e /*/ d -ibak /etc/exports +%admin ALL=(root) NOPASSWD: VAGRANT_EXPORTS_ADD, VAGRANT_NFSD, VAGRANT_EXPORTS_REMOVE +``` + +For Ubuntu Linux , sudoers should look like this: + +``` +Cmnd_Alias VAGRANT_EXPORTS_CHOWN = /bin/chown 0\:0 /tmp/* +Cmnd_Alias VAGRANT_EXPORTS_MV = /bin/mv -f /tmp/* /etc/exports +Cmnd_Alias VAGRANT_NFSD_CHECK = /etc/init.d/nfs-kernel-server status +Cmnd_Alias VAGRANT_NFSD_START = /etc/init.d/nfs-kernel-server start +Cmnd_Alias VAGRANT_NFSD_APPLY = /usr/sbin/exportfs -ar +%sudo ALL=(root) NOPASSWD: VAGRANT_EXPORTS_CHOWN, VAGRANT_EXPORTS_MV, VAGRANT_NFSD_CHECK, VAGRANT_NFSD_START, VAGRANT_NFSD_APPLY +``` + +For Fedora Linux, sudoers might look like this (given your user +belongs to the vagrant group): + +``` +Cmnd_Alias VAGRANT_EXPORTS_CHOWN = /bin/chown 0\:0 /tmp/* +Cmnd_Alias VAGRANT_EXPORTS_MV = /bin/mv -f /tmp/* /etc/exports +Cmnd_Alias VAGRANT_NFSD_CHECK = /usr/bin/systemctl status --no-pager nfs-server.service +Cmnd_Alias VAGRANT_NFSD_START = /usr/bin/systemctl start nfs-server.service +Cmnd_Alias VAGRANT_NFSD_APPLY = /usr/sbin/exportfs -ar +%vagrant ALL=(root) NOPASSWD: VAGRANT_EXPORTS_CHOWN, VAGRANT_EXPORTS_MV, VAGRANT_NFSD_CHECK, VAGRANT_NFSD_START, VAGRANT_NFSD_APPLY +``` + +For SUSE Linux, sudoers might look like this (given your user +belongs to the vagrant group): + +``` +Cmnd_Alias VAGRANT_CHOWN = /usr/bin/chown 0\:0 /tmp/vagrant[a-z0-9-]* +Cmnd_Alias VAGRANT_MV = /usr/bin/mv -f /tmp/vagrant[a-z0-9-]* /etc/exports +Cmnd_Alias VAGRANT_START = /sbin/service nfsserver start +Cmnd_Alias VAGRANT_STATUS = /sbin/service nfsserver status +Cmnd_Alias VAGRANT_APPLY = /usr/sbin/exportfs -ar +%vagrant ALL=(root) NOPASSWD: VAGRANT_CHOWN, VAGRANT_MV, VAGRANT_START, VAGRANT_STATUS, VAGRANT_APPLY +``` + +If you don't want to edit `/etc/sudoers` directly, you can create +`/etc/sudoers.d/vagrant-syncedfolders` with the appropriate entries, +assuming `/etc/sudoers.d` has been enabled. + +## Other Notes + +**Encrypted folders:** If you have an encrypted disk, then NFS very often +will refuse to export the filesystem. The error message given by NFS is +often not clear. One error message seen is ` does not support NFS`. +There is no workaround for this other than sharing a directory which is not +encrypted. + +**Version 4:** UDP is generally not a valid transport protocol for NFSv4. +Early implementations of NFS 4.0 still allowed UDP which allows the UDP +transport protocol to be used in rare cases. RFC5661 explicitly states +UDP alone should not be used for the transport protocol in NFS 4.1. Errors +due to unsupported transport protocols for specific versions of NFS are +not always clear. A common error message when attempting to use UDP with +NFSv4: + +``` +mount.nfs: an incorrect mount option was specified +``` + +When using NFSv4, ensure the `nfs_udp` option is set to false. For example: + +```ruby +config.vm.synced_folder ".", "/vagrant", + type: "nfs", + nfs_version: 4, + nfs_udp: false +``` + +For more information about transport protocols and NFS version 4 see: + +- NFSv4.0 - [RFC7530](https://tools.ietf.org/html/rfc7530#section-3.1) +- NFSv4.1 - [RFC5661](https://tools.ietf.org/html/rfc5661#section-2.9.1) diff --git a/website/pages/docs/synced-folders/rsync.html.md b/website/pages/docs/synced-folders/rsync.html.md new file mode 100644 index 000000000..01a4ee884 --- /dev/null +++ b/website/pages/docs/synced-folders/rsync.html.md @@ -0,0 +1,106 @@ +--- +layout: 'docs' +page_title: 'RSync - Synced Folders' +sidebar_current: 'syncedfolder-rsync' +description: |- + Vagrant can use rsync as a mechanism to sync a folder to the guest machine. + This synced folder type is useful primarily in situations where other synced + folder mechanisms are not available, such as when NFS or VirtualBox shared + folders are not available in the guest machine. +--- + +# RSync + +**Synced folder type:** `rsync` + +Vagrant can use [rsync](https://en.wikipedia.org/wiki/Rsync) as a mechanism +to sync a folder to the guest machine. This synced folder type is useful +primarily in situations where other synced folder mechanisms are not available, +such as when NFS or VirtualBox shared folders are not available in the guest +machine. + +The rsync synced folder does a one-time one-way sync from the machine running +to the machine being started by Vagrant. + +The [rsync](/docs/cli/rsync.html) and [rsync-auto](/docs/cli/rsync-auto.html) +commands can be used to force a resync and to automatically resync when +changes occur in the filesystem. Without running these commands, Vagrant +only syncs the folders on `vagrant up` or `vagrant reload`. + +## Prerequisites + +To use the rsync synced folder type, the machine running Vagrant must have +`rsync` (or `rsync.exe`) on the path. This executable is expected to behave +like the standard rsync tool. + +On Windows, rsync installed with Cygwin or MinGW will be detected by +Vagrant and works well. + +The destination machine must also have rsync installed, but Vagrant +can automatically install rsync into many operating systems. If Vagrant +is unable to automatically install rsync for your operating system, +it will tell you. + +The destination folder will be created as the user initiating the connection, +this is `vagrant` by default. This user requires the appropriate permissions on +the destination folder. + +## Options + +The rsync synced folder type accepts the following options: + +- `rsync__args` (array of strings) - A list of arguments to supply + to `rsync`. By default this is `["--verbose", "--archive", "--delete", "-z", "--copy-links"]`. + +- `rsync__auto` (boolean) - If false, then `rsync-auto` will not + watch and automatically sync this folder. By default, this is true. **Note**: This + option will not automatically invoke the `rsync-auto` subcommand. + +- `rsync__chown` (boolean) - If false, then the + [`owner` and `group`](/docs/synced-folders/basic_usage.html) + options for the synced folder are ignored and Vagrant will not execute + a recursive `chown`. This defaults to true. This option exists because + the `chown` causes issues for some development environments. Note that + any `rsync__args` options for ownership **will be overridden** by + `rsync__chown`. + +- `rsync__exclude` (string or array of strings) - A list of files or directories + to exclude from the sync. The values can be any acceptable rsync exclude + pattern. By default, the ".vagrant/" directory is excluded. We recommend + excluding revision control directories such as ".git/" as well. + +- `rsync__rsync_ownership` (boolean) - If true, and rsync executables in use + are >= 3.1.0, then rsync will be used to set the owner and group instead + of a separate call to modify ownership. By default, this is false. + +- `rsync__rsync_path` (string) - The path on the remote host where rsync + is and how it is executed. This is platform specific but defaults to + "sudo rsync" for many guests. + +- `rsync__verbose` (boolean) - If true, then the output from the rsync + process will be echoed to the console. The output of rsync is subject + to `rsync__args` of course. By default, this is false. + +## Example + +The following is an example of using RSync to sync a folder: + +```ruby +Vagrant.configure("2") do |config| + config.vm.synced_folder ".", "/vagrant", type: "rsync", + rsync__exclude: ".git/" +end +``` + +## Rsync to a restricted folder + +If required to copy to a destination where `vagrant` user does not have +permissions, use `"--rsync-path='sudo rsync'"` to run rsync with sudo on the guest + +```ruby +Vagrant.configure("2") do |config| + config.vm.synced_folder "bin", "/usr/local/bin", type: "rsync", + rsync__exclude: ".git/", + rsync__args: ["--verbose", "--rsync-path='sudo rsync'", "--archive", "--delete", "-z"] +end +``` diff --git a/website/pages/docs/synced-folders/smb.html.md b/website/pages/docs/synced-folders/smb.html.md new file mode 100644 index 000000000..be524dd19 --- /dev/null +++ b/website/pages/docs/synced-folders/smb.html.md @@ -0,0 +1,131 @@ +--- +layout: 'docs' +page_title: 'SMB - Synced Folders' +sidebar_current: 'syncedfolder-smb' +description: |- + Vagrant can use SMB as a mechanism to create a bi-directional synced folder + between the host machine and the Vagrant machine. +--- + +# SMB + +**Synced folder type:** `smb` + +Vagrant can use [SMB](https://en.wikipedia.org/wiki/Server_Message_Block) +as a mechanism to create a bi-directional synced folder between the host +machine and the Vagrant machine. + +SMB is built-in to Windows machines and provides a higher performance +alternative to some other mechanisms such as VirtualBox shared folders. + +
+ SMB is currently only supported when the host machine is Windows or + macOS. The guest machine can be Windows, Linux, or macOS. +
+ +## Prerequisites + +### Windows Host + +To use the SMB synced folder type on a Windows host, the machine must have +PowerShell version 3 or later installed. In addition, when Vagrant attempts +to create new SMB shares, or remove existing SMB shares, Administrator +privileges will be required. Vagrant will request these privileges using UAC. + +### macOS Host + +To use the SMB synced folder type on a macOS host, file sharing must be enabled +for the local account. Enable SMB file sharing by following the instructions +below: + +- Open "System Preferences" +- Click "Sharing" +- Check the "On" checkbox next to "File Sharing" +- Click "Options" +- Check "Share files and folders using SMB" +- Check the "On" checkbox next to your username within "Windows File Sharing" +- Click "Done" + +When Vagrant attempts to create new SMB shares, or remove existing SMB shares, +root access will be required. Vagrant will request these privileges using +`sudo` to run the `/usr/sbin/sharing` command. Adding the following to +the system's `sudoers` configuration will allow Vagrant to manage SMB shares +without requiring a password each time: + +``` +Cmnd_Alias VAGRANT_SMB_ADD = /usr/sbin/sharing -a * -S * -s * -g * -n * +Cmnd_Alias VAGRANT_SMB_REMOVE = /usr/sbin/sharing -r * +Cmnd_Alias VAGRANT_SMB_LIST = /usr/sbin/sharing -l +Cmnd_Alias VAGRANT_SMB_PLOAD = /bin/launchctl load -w /System/Library/LaunchDaemons/com.apple.smb.preferences.plist +Cmnd_Alias VAGRANT_SMB_DLOAD = /bin/launchctl load -w /System/Library/LaunchDaemons/com.apple.smbd.plist +Cmnd_Alias VAGRANT_SMB_DSTART = /bin/launchctl start com.apple.smbd +%admin ALL=(root) NOPASSWD: VAGRANT_SMB_ADD, VAGRANT_SMB_REMOVE, VAGRANT_SMB_LIST, VAGRANT_SMB_PLOAD, VAGRANT_SMB_DLOAD, VAGRANT_SMB_DSTART +``` + +### Guests + +The destination machine must be able to mount SMB filesystems. On Linux +the package to do this is usually called `smbfs` or `cifs`. Vagrant knows +how to automatically install this for some operating systems. + +## Options + +The SMB synced folder type has a variety of options it accepts: + +- `smb_host` (string) - The host IP where the SMB mount is located. If this + is not specified, Vagrant will attempt to determine this automatically. + +- `smb_password` (string) - The password used for authentication to mount + the SMB mount. This is the password for the username specified by + `smb_username`. If this is not specified, Vagrant will prompt you for it. + It is highly recommended that you do not set this, since it would expose + your password directly in your Vagrantfile. + +- `smb_username` (string) - The username used for authentication to mount + the SMB mount. This is the username to access the mount, _not_ the username + of the account where the folder is being mounted to. This is usually your + Windows username. If you sign into a domain, specify it as `user@domain`. + If this option is not specified, Vagrant will prompt you for it. + +## Example + +The following is an example of using SMB to sync a folder: + +```ruby +Vagrant.configure("2") do |config| + config.vm.synced_folder ".", "/vagrant", type: "smb" +end +``` + +## Preventing Idle Disconnects + +On Windows, if a file is not accessed for some period of time, it may +disconnect from the guest and prevent the guest from accessing the SMB-mounted +share. To prevent this, the following command can be used in a superuser +shell. Note that you should research if this is the right option for you. + +``` +net config server /autodisconnect:-1 +``` + +## Common Issues + +### "wrong fs type" Error + +If during mounting on Linux you are seeing an error message that includes +the words "wrong fs type," this is because the SMB kernel extension needs to +be updated in the OS. + +If updating the kernel extension is not an option, you can workaround the +issue by specifying the following options on your synced folder: + +```ruby +mount_options: ["username=USERNAME","password=PASSWORD"] +``` + +Replace "USERNAME" and "PASSWORD" with your SMB username and password. + +Vagrant 1.8 changed SMB mounting to use the more secure credential file +mechanism. However, many operating systems ship with an outdated filesystem +type for SMB out of the box which does not support this. The above workaround +reverts Vagrant to the insecure before, but causes it work. diff --git a/website/pages/docs/synced-folders/virtualbox.html.md b/website/pages/docs/synced-folders/virtualbox.html.md new file mode 100644 index 000000000..c09ee2062 --- /dev/null +++ b/website/pages/docs/synced-folders/virtualbox.html.md @@ -0,0 +1,43 @@ +--- +layout: 'docs' +page_title: 'VirtualBox Shared Folders - Synced Folders' +sidebar_current: 'syncedfolder-virtualbox' +description: |- + If you are using the Vagrant VirtualBox provider, then VirtualBox shared + folders are the default synced folder type. These synced folders use the + VirtualBox shared folder system to sync file changes from the guest to the + host and vice versa. +--- + +# VirtualBox + +If you are using the Vagrant VirtualBox [provider](/docs/providers/), then +VirtualBox shared folders are the default synced folder type. These synced +folders use the VirtualBox shared folder system to sync file changes from +the guest to the host and vice versa. + +## Options + +- `automount` (boolean) - If true, the `--automount` flag will be used when + using the VirtualBox tools to share the folder with the guest vm. Defaults to false + if not present. + +- `SharedFoldersEnableSymlinksCreate` (boolean) - If false, will disable the + ability to create symlinks with the given virtualbox shared folder. Defaults to + true if the option is not present. + +## Caveats + +There is a [VirtualBox bug][sendfile bug] related to `sendfile` which can result +in corrupted or non-updating files. You should deactivate `sendfile` in any +web servers you may be running. + +In Nginx: + + sendfile off; + +In Apache: + + EnableSendfile Off + +[sendfile bug]: https://github.com/hashicorp/vagrant/issues/351#issuecomment-1339640 diff --git a/website/pages/docs/triggers/configuration.html.md b/website/pages/docs/triggers/configuration.html.md new file mode 100644 index 000000000..5492b99e5 --- /dev/null +++ b/website/pages/docs/triggers/configuration.html.md @@ -0,0 +1,208 @@ +--- +layout: 'docs' +page_title: 'Vagrant Triggers Configuration' +sidebar_current: 'triggers-configuration' +description: |- + Documentation of various configuration options for Vagrant Triggers +--- + +# Configuration + +Vagrant Triggers has a few options to define trigger behavior. + +## Execution Order + +The trigger config block takes two different operations that determine when a trigger +should fire: + +- `before` +- `after` + +These define _how_ the trigger behaves and when it should fire off during +the Vagrant life cycle. A simple example of a _before_ operation could look like: + +```ruby +config.trigger.before :up do |t| + t.info = "Bringing up your Vagrant guest machine!" +end +``` + +Triggers can also be used with [_commands_](#commands), [_actions_](#actions), or [_hooks_](#hooks). +By default triggers will be defined to run before or after a Vagrant guest. For more +detailed examples of how to use triggers, check out the [usage section](/docs/triggers/usage.html). + +## Trigger Options + +The trigger class takes various options. + +- `action` (symbol, array) - Expected to be a single symbol value, an array of symbols, or a _splat_ of symbols. The first argument that comes after either **before** or **after** when defining a new trigger. Can be any valid Vagrant command. It also accepts a special value `:all` which will make the trigger fire for every action. An action can be ignored with the `ignore` setting if desired. These are the valid action commands for triggers: + + - `destroy` + - `halt` + - `provision` + - `reload` + - `resume` + - `suspend` + - `up` + +- `ignore` (symbol, array) - Symbol or array of symbols corresponding to the action that a trigger should not fire on. + +- `info` (string) - A message that will be printed at the beginning of a trigger. + +- `name` (string) - The name of the trigger. If set, the name will be displayed when firing the trigger. + +- `on_error` (symbol) - Defines how the trigger should behave if it encounters an error. By default this will be `:halt`, but can be configured to ignore failures and continue on with `:continue`. + +- `only_on` (string, regex, array) - Limit the trigger to these guests. Values can be a string or regex that matches a guest name. + +- `ruby` (block) - A block of Ruby code to be executed on the host. The block accepts two arguments that can be used with your Ruby code: `env` and `machine`. These options correspond to the Vagrant environment used (note: these are not your shell's environment variables), and the Vagrant guest machine that the trigger is firing on. This option can only be a `Proc` type, which must be explicitly called out when using the hash syntax for a trigger. + + ```ruby + ubuntu.trigger.after :up do |trigger| + trigger.info = "More information" + trigger.ruby do |env,machine| + greetings = "hello there #{machine.id}!" + puts greetings + end + end + ``` + +- `run_remote` (hash) - A collection of settings to run a inline or remote script with on the guest. These settings correspond to the [shell provisioner](/docs/provisioning/shell.html). + +- `run` (hash) - A collection of settings to run a inline or remote script on the host. These settings correspond to the [shell provisioner](/docs/provisioning/shell.html). However, at the moment the only settings `run` takes advantage of are: + + - `args` + - `inline` + - `path` + + **Note:** The `run` option with `inline` is not entirely like a shell provisioner that runs bash. + It executes binaries on your machine rather than a bash script. For example: + If you wish you use bash to pipe some text to a file in your `run` option with `inline`, wrap + your inline script with _`bash -c " + + +<% end %> + +# Vagrant Cloud API + +## Using the API + +Vagrant Cloud provides an API for users to interact with Vagrant Cloud for experimentation, automation, or building new features and tools on top of our existing application. + +### Authentication + +Some API endpoints require authentication to create new resources, update or delete existing resources, or to read a private resource. + +Clients can authenticate using an authentication token. +The token can be passed to Vagrant Cloud one of two ways: + +1. (Preferred) Set the `Authorization` header to `"Bearer "` and the value of the authentication token. +2. Pass the authentication token as an `access_token` URL parameter. + +Examples below will set the header, but feel free to use whichever method is easier for your implementation. + +-> The `X-Atlas-Token` header is also supported for backwards-compatibility. + +### Request and Response Format + +Requests to Vagrant Cloud which include data attributes (`POST` or `PUT`/`PATCH`) should set the `Content-Type` header to `"application/json"`, and include a valid JSON body with the request. + +JSON responses may include an `errors` key, which will contain an array of error strings, as well as a `success` key. +For example: + +```json +{ + "errors": [ + "Resource not found!" + ], + "success": false +} +``` + +### Response Codes + +Vagrant Cloud may respond with the following response codes, depending on the status of the request and context: + +#### Success + +##### **200** OK +##### **201** Created +##### **204** No Content + +#### Client Errors + +##### **401** Unauthorized + +You do not have authorization to access the requested resource. + +##### **402** Payment Required + +You are trying to access a resource which is delinquent on billing. +Please contact the owner of the resource so that they can update their billing information. + +##### **403** Forbidden + +You are attempting to use the system in a way which is not allowed. +There could be required request parameters that are missing, or one of the parameters is invalid. +Please check the response `errors` key, and double-check the examples below for any discrepancies. + +##### **404** Not Found + +The resource you are trying to access does not exist. This may also be returned if you attempt to access a private resource that you don't have authorization to view. + +##### **422** Unprocessable Entity + +##### **429** Too Many Requests + +You are currently being rate-limited. Please decrease your frequency of usage, or contact us at [support+vagrantcloud@hashicorp.com](mailto:support+vagrantcloud@hashicorp.com) with a description of your use case so that we can consider creating an exception. + +#### Server Errors + +##### **500** Internal Server Error + +The server failed to respond to the request for an unknown reason. +Please contact [support+vagrantcloud@hashicorp.com](mailto:support+vagrantcloud@hashicorp.com) with a description of the problem so that we can investigate. + +##### **503** Service Unavailable + +Vagrant Cloud is temporarily in maintenance mode. +Please check the [HashiCorp Status Site](http://status.hashicorp.com) for more information. + +## Creating a usable box from scratch + +-> This assumes that you have a valid Vagrant Cloud authentication token. You can [create one via the API](#create-a-token), or [create one on the Vagrant Cloud website](https://app.vagrantup.com/settings/security). + +In order to create a usable box on Vagrant Cloud, perform the following steps: + +1. [Create a new box](#create-a-box) +1. [Create a new version](#create-a-version) +1. [Create a new provider](#create-a-provider) +1. [Upload a box image for that provider](#upload-a-provider) +1. [Release the version](#release-a-version) + +#### Example Requests + +
+ +
+ ```shell + # Create a new box + curl \ + --header "Content-Type: application/json" \ + --header "Authorization: Bearer $VAGRANT_CLOUD_TOKEN" \ + https://app.vagrantup.com/api/v1/boxes \ + --data '{ "box": { "username": "myuser", "name": "test" } }' + + # Create a new version + curl \ + --header "Content-Type: application/json" \ + --header "Authorization: Bearer $VAGRANT_CLOUD_TOKEN" \ + https://app.vagrantup.com/api/v1/box/myuser/test/versions \ + --data '{ "version": { "version": "1.2.3" } }' + + # Create a new provider + curl \ + --header "Content-Type: application/json" \ + --header "Authorization: Bearer $VAGRANT_CLOUD_TOKEN" \ + https://app.vagrantup.com/api/v1/box/myuser/test/version/1.2.3/providers \ + --data '{ "provider": { "name": "virtualbox" } }' + + # Prepare the provider for upload/get an upload URL + response=$(curl \ + --header "Authorization: Bearer $VAGRANT_CLOUD_TOKEN" \ + https://app.vagrantup.com/api/v1/box/myuser/test/version/1.2.3/provider/virtualbox/upload) + + # Extract the upload URL from the response (requires the jq command) + upload_path=$(echo "$response" | jq .upload_path) + + # Perform the upload + curl $upload_path --request PUT --upload-file virtualbox-1.2.3.box + + # Release the version + curl \ + --header "Authorization: Bearer $VAGRANT_CLOUD_TOKEN" \ + https://app.vagrantup.com/api/v1/box/myuser/test/version/1.2.3/release \ + --request PUT + ``` + + ```ruby + # gem install http, or add `gem "http"` to your Gemfile + require "http" + + api = HTTP.persistent("https://app.vagrantup.com").headers( + "Content-Type" => "application/json", + "Authorization" => "Bearer #{ENV['VAGRANT_CLOUD_TOKEN']}" + ) + + # Create a new box + api.post "/api/v1/boxes", + json: { box: { username: "myuser", name: "test" } } + + # Create a new version + api.post "/api/v1/box/myuser/test/versions", + json: { version: { version: "1.2.3" } } + + # Create a new provider + api.post "/api/v1/box/myuser/test/version/1.2.3/providers", + json: { provider: { name: "virtualbox" } } + + # Prepare the provider for upload + response = api.get("/api/v1/box/myuser/test/version/1.2.3/provider/virtualbox/upload") + + # Extract the upload URL + upload_path = response.parse['upload_path'] + + # Upload the box image + HTTP.put upload_path, body: File.open("virtualbox-1.2.3.box") + + # Release the version + api.put("/api/v1/box/myuser/test/version/1.2.3/release") + ``` +
+
+ +## Authentication + +### Create a token + +`POST /api/v1/authenticate` + +Creates a new token for the given user. + +#### Arguments + +* `token` + * `description` (Optional) - A description of the token. +* `two_factor` + * `code` - A two-factor authentication code. Required to use this API method if 2FA is enabled. See [Request a 2FA code](#request-a-2fa-code) if not using a TOTP application. +* `user` + * `login` - Username or email address of the user authenticating. + * `password` - The user's password. + +#### Example Request + +
+ +
+ ```shell + curl \ + --header "Content-Type: application/json" \ + https://app.vagrantup.com/api/v1/authenticate \ + --data ' + { + "token": { + "description": "Login from cURL" + }, + "user": { + "login": "myuser", + "password": "secretpassword" + } + } + ' + ``` + + ```ruby + # gem install http, or add `gem "http"` to your Gemfile + require "http" + + api = HTTP.persistent("https://app.vagrantup.com").headers( + "Content-Type" => "application/json" + ) + + response = api.post("/api/v1/authenticate", json: { + token: { description: "Login from Ruby" }, + user: { login: "myuser", password: "secretpassword" } + }) + + if response.status.success? + # Success, the response attributes are available here. + p response.parse + else + # Error, inspect the `errors` key for more information. + p response.code, response.body + end + ``` +
+
+ +#### Example Response + +```json +{ + "description": "Login from cURL", + "token": "qwlIE1qBVUafsg.atlasv1.FLwfJSSYkl49i4qZIu8R31GBnI9r8DrW4IQKMppkGq5rD264lRksTqaIN0zY9Bmy0zs", + "token_hash": "7598236a879ecb42cb0f25399d6f25d1d2cfbbc6333392131bbdfba325eb352795c169daa4a61a8094d44afe817a857e0e5fc7dc72a1401eb434577337d1246c", + "created_at": "2017-10-18T19:16:24.956Z" +} +``` + +### Validate a token + +`GET /api/v1/authenticate` + +Responds [`200 OK`](#200-ok) if the authentication request was successful, otherwise responds [`401 Unauthorized`](#401-unauthorized). + +#### Example Request + +
+ +
+ ```shell + curl \ + --header "Authorization: Bearer $VAGRANT_CLOUD_TOKEN" \ + https://app.vagrantup.com/api/v1/authenticate + ``` + + ```ruby + # gem install http, or add `gem "http"` to your Gemfile + require "http" + + api = HTTP.persistent("https://app.vagrantup.com").headers( + "Authorization" => "Bearer #{ENV['VAGRANT_CLOUD_TOKEN']}" + ) + + response = api.get("/api/v1/authenticate") + + if response.status.success? + # Success, the response attributes are available here. + p response.parse + else + # Error, inspect the `errors` key for more information. + p response.code, response.body + end + ``` +
+
+ +### Delete a token + +`DELETE /api/v1/authenticate` + +Responds [`204 OK`](#204-no-content) if the deletion request was successful, otherwise responds [`401 Unauthorized`](#401-unauthorized). + +#### Example Request + +
+ +
+ ```shell + curl \ + --header "Authorization: Bearer $VAGRANT_CLOUD_TOKEN" \ + --request DELETE \ + https://app.vagrantup.com/api/v1/authenticate + ``` + + ```ruby + # gem install http, or add `gem "http"` to your Gemfile + require "http" + + api = HTTP.persistent("https://app.vagrantup.com").headers( + "Authorization" => "Bearer #{ENV['VAGRANT_CLOUD_TOKEN']}" + ) + + response = api.delete("/api/v1/authenticate") + + if response.status.success? + # Success, the response attributes are available here. + p response.parse + else + # Error, inspect the `errors` key for more information. + p response.code, response.body + end + ``` +
+
+ +### Request a 2FA code + +`POST /api/v1/two-factor/request-code` + +Sends a 2FA code to the requested delivery method. + +#### Arguments + +* `two_factor` + * `delivery_method` - A valid 2FA delivery method. Currently only `sms` is supported. +* `user` + * `login` - Username or email address of the user authenticating. + * `password` - The user's password. + +#### Example Request + +
+ +
+ ```shell + curl \ + --header "Content-Type: application/json" \ + https://app.vagrantup.com/api/v1/authenticate \ + --data ' + { + "two_factor": { + "delivery_method": "sms" + }, + "user": { + "login": "myuser", + "password": "secretpassword" + } + } + ' + ``` + + ```ruby + # gem install http, or add `gem "http"` to your Gemfile + require "http" + + api = HTTP.persistent("https://app.vagrantup.com").headers( + "Content-Type" => "application/json" + ) + + response = api.post("/api/v1/two-factor/request-code", json: { + two_factor: { delivery_method: "sms" }, + user: { login: "myuser", password: "secretpassword" } + }) + + if response.status.success? + # Success, the response attributes are available here. + p response.parse + else + # Error, inspect the `errors` key for more information. + p response.code, response.body + end + ``` +
+
+ +#### Example Response + +```json +{ + "two_factor": { + "obfuscated_destination": "SMS number ending in 7890" + } +} +``` + +## Organizations + +### Read an organization + +`GET /api/v1/user/:username` + +#### Example Request + +
+ +
+ ```shell + curl \ + --header "Authorization: Bearer $VAGRANT_CLOUD_TOKEN" \ + https://app.vagrantup.com/api/v1/user/myuser + ``` + + ```ruby + # gem install http, or add `gem "http"` to your Gemfile + require "http" + + api = HTTP.persistent("https://app.vagrantup.com").headers( + "Authorization" => "Bearer #{ENV['VAGRANT_CLOUD_TOKEN']}" + ) + + response = api.get("/api/v1/user/myuser") + + if response.status.success? + # Success, the response attributes are available here. + p response.parse + else + # Error, inspect the `errors` key for more information. + p response.code, response.body + end + ``` +
+
+ +#### Example Response + +```json +{ + "username": "myuser", + "avatar_url": "https://www.gravatar.com/avatar/130a640278870c3dada38b3d912ee022?s=460&d=mm", + "profile_html": "

Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua.

\n", + "profile_markdown": "Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua.", + "boxes": [] +} +``` + +## Search + +### Search for boxes + +`GET /api/v1/search` + +#### Arguments + +* `q` - (Optional) The search query. Results will match the `username`, `name`, or `short_description` fields for a box. If omitted, the top boxes based on `sort` and `order` will be returned (defaults to "downloads desc"). +* `provider` - (Optional) Filter results to boxes supporting for a specific provider. +* `sort` - (Optional, default: `"downloads"`) The field to sort results on. Can be one of `"downloads"`, `"created"`, or `"updated"`. +* `order` - (Optional, default: `"desc"`) The order to return the sorted field in. Can be `"desc"` os `"asc"`. +* `limit` - (Optional, default: `10`) The number of results to return (max of 100). +* `page` - (Optional, default: `1`) + +#### Example Request + +
+ +
+ ```shell + curl \ + --header "Authorization: Bearer $VAGRANT_CLOUD_TOKEN" \ + https://app.vagrantup.com/api/v1/search?q=test&provider=virtualbox + ``` + + ```ruby + # gem install http, or add `gem "http"` to your Gemfile + require "http" + + api = HTTP.persistent("https://app.vagrantup.com").headers( + "Authorization" => "Bearer #{ENV['VAGRANT_CLOUD_TOKEN']}" + ) + + response = api.get("/api/v1/search", params: { + q: "test", + provider: "virtualbox" + }) + + if response.status.success? + # Success, the response attributes are available here. + p response.parse + else + # Error, inspect the `errors` key for more information. + p response.code, response.body + end + ``` +
+
+ +#### Example Response + +```json +{ + "boxes": [ + { + "created_at": "2017-10-20T14:19:59.842Z", + "updated_at": "2017-10-20T15:23:53.363Z", + "tag": "myuser/test", + "name": "test", + "short_description": "My dev box", + "description_html": "

My development Vagrant box

\n", + "username": "myuser", + "description_markdown": "My development Vagrant box", + "private": true, + "downloads": 123, + "current_version": { + "version": "1.2.3", + "status": "active", + "description_html": "

A new version

\n", + "description_markdown": "A new version", + "created_at": "2017-10-20T15:23:17.184Z", + "updated_at": "2017-10-20T15:23:53.355Z", + "number": "1.2.3", + "release_url": "https://app.vagrantup.com/api/v1/box/myuser/test/version/1.2.3/release", + "revoke_url": "https://app.vagrantup.com/api/v1/box/myuser/test/version/1.2.3/revoke", + "providers": [ + { + "name": "virtualbox", + "hosted": false, + "hosted_token": null, + "original_url": "https://example.com/virtualbox-1.2.3.box", + "created_at": "2017-10-20T15:23:35.718Z", + "updated_at": "2017-10-20T15:23:35.718Z", + "download_url": "https://vagrantcloud.com/myuser/boxes/test/versions/1.2.3/providers/virtualbox.box" + } + ] + } + } + ] +} +``` + +## Boxes + +### Read a box + +`GET /api/v1/box/:username/:name` + +#### Example Request + +
+ +
+ ```shell + curl \ + --header "Authorization: Bearer $VAGRANT_CLOUD_TOKEN" \ + https://app.vagrantup.com/api/v1/box/myuser/test + ``` + + ```ruby + # gem install http, or add `gem "http"` to your Gemfile + require "http" + + api = HTTP.persistent("https://app.vagrantup.com").headers( + "Authorization" => "Bearer #{ENV['VAGRANT_CLOUD_TOKEN']}" + ) + + response = api.get("/api/v1/box/myuser/test") + + if response.status.success? + # Success, the response attributes are available here. + p response.parse + else + # Error, inspect the `errors` key for more information. + p response.code, response.body + end + ``` +
+
+ +#### Example Response + +```json +{ + "created_at": "2017-10-20T14:19:59.842Z", + "updated_at": "2017-10-20T15:23:53.363Z", + "tag": "myuser/test", + "name": "test", + "short_description": "My dev box", + "description_html": "

My development Vagrant box

\n", + "username": "myuser", + "description_markdown": "My development Vagrant box", + "private": true, + "downloads": 123, + "current_version": { + "version": "1.2.3", + "status": "active", + "description_html": "

A new version

\n", + "description_markdown": "A new version", + "created_at": "2017-10-20T15:23:17.184Z", + "updated_at": "2017-10-20T15:23:53.355Z", + "number": "1.2.3", + "release_url": "https://app.vagrantup.com/api/v1/box/myuser/test/version/1.2.3/release", + "revoke_url": "https://app.vagrantup.com/api/v1/box/myuser/test/version/1.2.3/revoke", + "providers": [ + { + "name": "virtualbox", + "hosted": false, + "hosted_token": null, + "original_url": "https://example.com/virtualbox-1.2.3.box", + "created_at": "2017-10-20T15:23:35.718Z", + "updated_at": "2017-10-20T15:23:35.718Z", + "download_url": "https://vagrantcloud.com/myuser/boxes/test/versions/1.2.3/providers/virtualbox.box" + } + ] + }, + "versions": [ + { + "version": "1.2.3", + "status": "active", + "description_html": "

A new version

\n", + "description_markdown": "A new version", + "created_at": "2017-10-20T15:23:17.184Z", + "updated_at": "2017-10-20T15:23:53.355Z", + "number": "1.2.3", + "release_url": "https://app.vagrantup.com/api/v1/box/myuser/test/version/1.2.3/release", + "revoke_url": "https://app.vagrantup.com/api/v1/box/myuser/test/version/1.2.3/revoke", + "providers": [ + { + "name": "virtualbox", + "hosted": false, + "hosted_token": null, + "original_url": "https://example.com/virtualbox-1.2.3.box", + "created_at": "2017-10-20T15:23:35.718Z", + "updated_at": "2017-10-20T15:23:35.718Z", + "download_url": "https://vagrantcloud.com/myuser/boxes/test/versions/1.2.3/providers/virtualbox.box" + } + ] + } + ] +} +``` + +### Create a box + +`POST /api/v1/boxes` + +#### Arguments + +* `box` + * `username` - The username of the organization that will own this box. + * `name` - The name of the box. + * `short_description` - A short summary of the box. + * `description` - A longer description of the box. Can be formatted with [Markdown][markdown]. + * `is_private` (Optional, default: `true`) - Whether or not this box is private. + +#### Example Request + +
+ +
+ ```shell + curl \ + --header "Content-Type: application/json" \ + --header "Authorization: Bearer $VAGRANT_CLOUD_TOKEN" \ + https://app.vagrantup.com/api/v1/boxes \ + --data ' + { + "box": { + "username": "myuser", + "name": "test", + "short_description": "My dev box", + "description": "My development Vagrant box", + "is_private": true + } + } + ' + ``` + + ```ruby + # gem install http, or add `gem "http"` to your Gemfile + require "http" + + api = HTTP.persistent("https://app.vagrantup.com").headers( + "Content-Type" => "application/json", + "Authorization" => "Bearer #{ENV['VAGRANT_CLOUD_TOKEN']}" + ) + + response = api.post("/api/v1/boxes", json: { + box: { + username: "myuser", + name: "test", + short_description: "My dev box", + description: "My development Vagrant box", + is_private: true + } + }) + + if response.status.success? + # Success, the response attributes are available here. + p response.parse + else + # Error, inspect the `errors` key for more information. + p response.code, response.body + end + ``` +
+
+ +#### Example Response + +Response body is identical to [Reading a box](#read-a-box). + +### Update a box + +`PUT /api/v1/box/:username/:name` + +#### Arguments + +* `box` + * `name` - The name of the box. + * `short_description` - A short summary of the box. + * `description` - A longer description of the box. Can be formatted with [Markdown](https://daringfireball.net/projects/markdown/syntax). + * `is_private` (Optional, default: `true`) - Whether or not this box is private. + +#### Example Request + +
+ +
+ ```shell + curl \ + --header "Content-Type: application/json" \ + --header "Authorization: Bearer $VAGRANT_CLOUD_TOKEN" \ + https://app.vagrantup.com/api/v1/box/myuser/test \ + --request PUT \ + --data ' + { + "box": { + "name": "test", + "short_description": "My dev box", + "description": "My development Vagrant box", + "is_private": true + } + } + ' + ``` + + + ```ruby + # gem install http, or add `gem "http"` to your Gemfile + require "http" + + api = HTTP.persistent("https://app.vagrantup.com").headers( + "Content-Type" => "application/json", + "Authorization" => "Bearer #{ENV['VAGRANT_CLOUD_TOKEN']}" + ) + + response = api.put("/api/v1/box/myuser/test", json: { + box: { + name: "test", + short_description: "My dev box", + description: "My development Vagrant box", + is_private: true + } + }) + + if response.status.success? + # Success, the response attributes are available here. + p response.parse + else + # Error, inspect the `errors` key for more information. + p response.code, response.body + end + ``` +
+
+ +### Delete a box + +`DELETE /api/v1/box/:username/:name` + +#### Example Request + +
+ +
+ ```shell + curl \ + --header "Authorization: Bearer $VAGRANT_CLOUD_TOKEN" \ + --request DELETE \ + https://app.vagrantup.com/api/v1/box/myuser/test + ``` + + ```ruby + # gem install http, or add `gem "http"` to your Gemfile + require "http" + + api = HTTP.persistent("https://app.vagrantup.com").headers( + "Authorization" => "Bearer #{ENV['VAGRANT_CLOUD_TOKEN']}" + ) + + response = api.delete("/api/v1/box/myuser/test") + + if response.status.success? + # Success, the response attributes are available here. + p response.parse + else + # Error, inspect the `errors` key for more information. + p response.code, response.body + end + ``` +
+
+ +#### Example Response + +Response body is identical to [Reading a box](#read-a-box). + +## Versions + +### Read a version + +`GET /api/v1/box/:username/:name/version/:version` + +#### Example Request + +
+ +
+ ```shell + curl \ + --header "Authorization: Bearer $VAGRANT_CLOUD_TOKEN" \ + https://app.vagrantup.com/api/v1/box/myuser/test/version/1.2.3 + ``` + + ```ruby + # gem install http, or add `gem "http"` to your Gemfile + require "http" + + api = HTTP.persistent("https://app.vagrantup.com").headers( + "Authorization" => "Bearer #{ENV['VAGRANT_CLOUD_TOKEN']}" + ) + + response = api.get("/api/v1/box/myuser/test/version/1.2.3") + + if response.status.success? + # Success, the response attributes are available here. + p response.parse + else + # Error, inspect the `errors` key for more information. + p response.code, response.body + end + ``` +
+
+ +#### Example Response + +```json +{ + "version": "1.2.3", + "status": "active", + "description_html": "

A new version

\n", + "description_markdown": "A new version", + "created_at": "2017-10-20T15:23:17.184Z", + "updated_at": "2017-10-20T15:23:53.355Z", + "number": "1.2.3", + "release_url": "https://app.vagrantup.com/api/v1/box/myuser/test/version/1.2.3/release", + "revoke_url": "https://app.vagrantup.com/api/v1/box/myuser/test/version/1.2.3/revoke", + "providers": [ + { + "name": "virtualbox", + "hosted": false, + "hosted_token": null, + "original_url": "https://example.com/virtualbox-1.2.3.box", + "created_at": "2017-10-20T15:23:35.718Z", + "updated_at": "2017-10-20T15:23:35.718Z", + "download_url": "https://vagrantcloud.com/myuser/boxes/test/versions/1.2.3/providers/virtualbox.box" + } + ] +} +``` + +### Create a version + +`POST /api/v1/box/:username/:name/versions` + +-> New versions start as `unreleased`. You must create a valid provider before releasing a new version. + +#### Arguments + +* `version` + * `version` - The version number of this version. + * `description` - A description for this version. Can be formatted with [Markdown](https://daringfireball.net/projects/markdown/syntax). + +#### Example Request + +
+ +
+ ```shell + curl \ + --header "Content-Type: application/json" \ + --header "Authorization: Bearer $VAGRANT_CLOUD_TOKEN" \ + https://app.vagrantup.com/api/v1/box/myuser/test/versions \ + --data ' + { + "version": { + "version": "1.2.3", + "description": "A new version" + } + } + ' + ``` + + ```ruby + # gem install http, or add `gem "http"` to your Gemfile + require "http" + + api = HTTP.persistent("https://app.vagrantup.com").headers( + "Content-Type" => "application/json", + "Authorization" => "Bearer #{ENV['VAGRANT_CLOUD_TOKEN']}" + ) + + response = api.post("/api/v1/box/myuser/test/versions", json: { + version: { + version: "1.2.3", + description: "A new version" + } + }) + + if response.status.success? + # Success, the response attributes are available here. + p response.parse + else + # Error, inspect the `errors` key for more information. + p response.code, response.body + end + ``` +
+
+ +#### Example Response + +Response body is identical to [Reading a version](#read-a-version). + +### Update a version + +`PUT /api/v1/box/:username/:name/version/1.2.3` + +#### Arguments + +* `version` + * `version` - The version number of this version. + * `description` - A description for this version. Can be formatted with [Markdown][markdown]. + +#### Example Request + +
+ +
+ ```shell + curl \ + --header "Content-Type: application/json" \ + --header "Authorization: Bearer $VAGRANT_CLOUD_TOKEN" \ + https://app.vagrantup.com/api/v1/box/myuser/test/version/1.2.3 \ + --request PUT \ + --data ' + { + "version": { + "version": "1.2.3", + "description": "A new version" + } + } + ' + ``` + + ```ruby + # gem install http, or add `gem "http"` to your Gemfile + require "http" + + api = HTTP.persistent("https://app.vagrantup.com").headers( + "Content-Type" => "application/json", + "Authorization" => "Bearer #{ENV['VAGRANT_CLOUD_TOKEN']}" + ) + + response = api.put("/api/v1/box/myuser/test/version/1.2.3", json: { + version: { + name: "1.2.3", + description: "A new version" + } + }) + + if response.status.success? + # Success, the response attributes are available here. + p response.parse + else + # Error, inspect the `errors` key for more information. + p response.code, response.body + end + ``` +
+
+ +#### Example Response + +Response body is identical to [Reading a version](#read-a-version). + +### Delete a version + +`DELETE /api/v1/box/:username/:name/version/:version` + +#### Example Request + +
+ +
+ ```shell + curl \ + --header "Authorization: Bearer $VAGRANT_CLOUD_TOKEN" \ + --request DELETE \ + https://app.vagrantup.com/api/v1/box/myuser/test/version/1.2.3 + ``` + + ```ruby + # gem install http, or add `gem "http"` to your Gemfile + require "http" + + api = HTTP.persistent("https://app.vagrantup.com").headers( + "Authorization" => "Bearer #{ENV['VAGRANT_CLOUD_TOKEN']}" + ) + + response = api.delete("/api/v1/box/myuser/test/version/1.2.3") + + if response.status.success? + # Success, the response attributes are available here. + p response.parse + else + # Error, inspect the `errors` key for more information. + p response.code, response.body + end + ``` +
+
+ +#### Example Response + +Response body is identical to [Reading a version](#read-a-version). + +### Release a version + +`PUT /api/v1/box/:username/:name/version/1.2.3/release` + +#### Example Request + +
+ +
+ ```shell + curl \ + --header "Authorization: Bearer $VAGRANT_CLOUD_TOKEN" \ + https://app.vagrantup.com/api/v1/box/myuser/test/version/1.2.3/release \ + --request PUT + ``` + + ```ruby + # gem install http, or add `gem "http"` to your Gemfile + require "http" + + api = HTTP.persistent("https://app.vagrantup.com").headers( + "Authorization" => "Bearer #{ENV['VAGRANT_CLOUD_TOKEN']}" + ) + + response = api.put("/api/v1/box/myuser/test/version/1.2.3/release") + + if response.status.success? + # Success, the response attributes are available here. + p response.parse + else + # Error, inspect the `errors` key for more information. + p response.code, response.body + end + ``` +
+
+ +#### Example Response + +Response body is identical to [Reading a version](#read-a-version). + +### Revoke a version + +`PUT /api/v1/box/:username/:name/version/1.2.3/revoke` + +#### Example Request + +
+ +
+ ```shell + curl \ + --header "Authorization: Bearer $VAGRANT_CLOUD_TOKEN" \ + https://app.vagrantup.com/api/v1/box/myuser/test/version/1.2.3/revoke \ + --request PUT + ``` + + ```ruby + # gem install http, or add `gem "http"` to your Gemfile + require "http" + + api = HTTP.persistent("https://app.vagrantup.com").headers( + "Authorization" => "Bearer #{ENV['VAGRANT_CLOUD_TOKEN']}" + ) + + response = api.put("/api/v1/box/myuser/test/version/1.2.3/revoke") + + if response.status.success? + # Success, the response attributes are available here. + p response.parse + else + # Error, inspect the `errors` key for more information. + p response.code, response.body + end + ``` +
+
+ +#### Example Response + +Response body is identical to [Reading a version](#read-a-version). + +## Providers + +### Read a provider + +`GET /api/v1/box/:username/:name/version/:version/provider/:provider` + +#### Example Request + +
+ +
+ ```shell + curl \ + --header "Authorization: Bearer $VAGRANT_CLOUD_TOKEN" \ + https://app.vagrantup.com/api/v1/box/myuser/test/version/1.2.3/provider/virtualbox + ``` + + ```ruby + # gem install http, or add `gem "http"` to your Gemfile + require "http" + + api = HTTP.persistent("https://app.vagrantup.com").headers( + "Authorization" => "Bearer #{ENV['VAGRANT_CLOUD_TOKEN']}" + ) + + response = api.get("/api/v1/box/myuser/test/version/1.2.3/provider/virtualbox") + + if response.status.success? + # Success, the response attributes are available here. + p response.parse + else + # Error, inspect the `errors` key for more information. + p response.code, response.body + end + ``` +
+
+ + +#### Example Response + +```json +{ + "name": "virtualbox", + "hosted": false, + "hosted_token": null, + "original_url": "https://example.com/virtualbox-1.2.3.box", + "created_at": "2017-10-20T15:23:35.718Z", + "updated_at": "2017-10-20T15:23:35.718Z", + "download_url": "https://vagrantcloud.com/myuser/boxes/test/versions/1.2.3/providers/virtualbox.box" +} +``` + +### Create a provider + +`POST /api/v1/box/:username/:name/version/:version/providers` + +#### Arguments + +* `provider` + * `name` - The name of the provider. + * `url` - A valid URL to download this provider. If omitted, you must [upload](#upload-a-provider) the Vagrant box image for this provider to Vagrant Cloud before the provider can be used. + +#### Example Request + +
+ +
+ ```shell + curl \ + --header "Content-Type: application/json" \ + --header "Authorization: Bearer $VAGRANT_CLOUD_TOKEN" \ + https://app.vagrantup.com/api/v1/box/myuser/test/version/1.2.3/providers \ + --data ' + { + "provider": { + "name": "virtualbox", + "url": "https://example.com/virtualbox-1.2.3.box" + } + } + ' + ``` + + ```ruby + # gem install http, or add `gem "http"` to your Gemfile + require "http" + + api = HTTP.persistent("https://app.vagrantup.com").headers( + "Content-Type" => "application/json", + "Authorization" => "Bearer #{ENV['VAGRANT_CLOUD_TOKEN']}" + ) + + response = api.post("/api/v1/box/myuser/test/version/1.2.3/providers", json: { + provider: { + name: "virtualbox", + url: "https://example.com/virtualbox-1.2.3.box" + } + }) + + if response.status.success? + # Success, the response attributes are available here. + p response.parse + else + # Error, inspect the `errors` key for more information. + p response.code, response.body + end + ``` +
+
+ +#### Example Response + +Response body is identical to [Reading a provider](#read-a-provider). + +### Update a provider + +`PUT /api/v1/box/:username/:name/version/:version/provider/:provider` + +#### Arguments + +* `provider` + * `name` - The name of the provider. + * `url` - A valid URL to download this provider. If omitted, you must [upload](#upload-a-provider) the Vagrant box image for this provider to Vagrant Cloud before the provider can be used. + +#### Example Request + +
+ +
+ ```shell + curl \ + --header "Content-Type: application/json" \ + --header "Authorization: Bearer $VAGRANT_CLOUD_TOKEN" \ + https://app.vagrantup.com/api/v1/box/myuser/test/version/1.2.3/provider/virtualbox \ + --request PUT \ + --data ' + { + "provider": { + "name": "virtualbox", + "url": "https://example.com/virtualbox-1.2.3.box" + } + } + ' + ``` + + ```ruby + # gem install http, or add `gem "http"` to your Gemfile + require "http" + + api = HTTP.persistent("https://app.vagrantup.com").headers( + "Content-Type" => "application/json", + "Authorization" => "Bearer #{ENV['VAGRANT_CLOUD_TOKEN']}" + ) + + response = api.put("/api/v1/box/myuser/test/version/1.2.3/provider/virtualbox", json: { + provider: { + name: "virtualbox", + url: "https://example.com/virtualbox-1.2.3.box" + } + }) + + if response.status.success? + # Success, the response attributes are available here. + p response.parse + else + # Error, inspect the `errors` key for more information. + p response.code, response.body + end + ``` +
+
+ +#### Example Response + +Response body is identical to [Reading a provider](#read-a-provider). + +### Delete a provider + +`DELETE /api/v1/box/:username/:name/version/:version/provider/:provider` + +#### Example Request + +
+ +
+ ```shell + curl \ + --header "Authorization: Bearer $VAGRANT_CLOUD_TOKEN" \ + --request DELETE \ + https://app.vagrantup.com/api/v1/box/myuser/test/version/1.2.3/provider/virtualbox + ``` + + ```ruby + # gem install http, or add `gem "http"` to your Gemfile + require "http" + + api = HTTP.persistent("https://app.vagrantup.com").headers( + "Authorization" => "Bearer #{ENV['VAGRANT_CLOUD_TOKEN']}" + ) + + response = api.delete("/api/v1/box/myuser/test/version/1.2.3/provider/virtualbox") + + if response.status.success? + # Success, the response attributes are available here. + p response.parse + else + # Error, inspect the `errors` key for more information. + p response.code, response.body + end + ``` +
+
+ +#### Example Response + +Response body is identical to [Reading a provider](#read-a-provider). + +### Upload a provider + +`GET /api/v1/box/:username/:name/version/:version/provider/:provider/upload` + +Prepares the provider for upload, and returns a JSON blob containing an `upload_path`. + +~> The upload must begin shortly after the response is returned, otherwise the URL will expire. If the URL expires, you can request this same API method again for a new upload URL. + +#### Example Request + +
+ +
+ ```shell + response=$(curl \ + --header "Authorization: Bearer $VAGRANT_CLOUD_TOKEN" \ + https://app.vagrantup.com/api/v1/box/myuser/test/version/1.2.3/provider/virtualbox/upload) + + # Requires the jq command + upload_path=$(echo "$response" | jq .upload_path) + + curl \ + $upload_path \ + --request PUT \ + --upload-file virtualbox-1.2.3.box + ``` + + ```ruby + # gem install http, or add `gem "http"` to your Gemfile + require "http" + + api = HTTP.persistent("https://app.vagrantup.com").headers( + "Authorization" => "Bearer #{ENV['VAGRANT_CLOUD_TOKEN']}" + ) + + response = api.get("/api/v1/box/myuser/test/version/1.2.3/provider/virtualbox/upload") + + if response.status.success? + # Success, you can now upload the box image to the returned URL + upload_path = response.parse['upload_path'] + HTTP.post upload_path, body: File.open("virtualbox-1.2.3.box") + else + # Error, inspect the `errors` key for more information. + p response.code, response.body + end + ``` +
+
+ +#### Example Response + +```json +{ + "upload_path": "https://archivist.hashicorp.com/v1/object/630e42d9-2364-2412-4121-18266770468e" +} +``` + +[markdown]: https://daringfireball.net/projects/markdown/syntax diff --git a/website/pages/docs/vagrant-cloud/boxes/catalog.html.md b/website/pages/docs/vagrant-cloud/boxes/catalog.html.md new file mode 100644 index 000000000..5a1b43a7b --- /dev/null +++ b/website/pages/docs/vagrant-cloud/boxes/catalog.html.md @@ -0,0 +1,47 @@ +--- +layout: 'vagrant-cloud' +page_title: 'Discovering Vagrant Boxes' +sidebar_current: 'vagrant-cloud-boxes-catalog' +--- + +# Discovering Vagrant Boxes + +Vagrant Cloud serves a public, searchable index of Vagrant boxes. It's easy to find +boxes you can use with Vagrant that contain the technologies you need +for a Vagrant environment. + +You don't need a Vagrant Cloud account to use public boxes. + +1. Go to the [Box search page](https://vagrantcloud.com/boxes/search). + +1. Once you find a box, click its name to learn more about it. + +1. When you're ready to use it, copy the name, such as "hashicorp/bionic64" + and initialize your Vagrant project with `vagrant init hashicorp/bionic64`. + Or, if you already have a Vagrant project created, modify the Vagrantfile + to use the box: `config.vm.box = "hashicorp/bionic64"`. + +## Provider Support + +Not all boxes are available for all providers. You may need +to sort by a provider that you have on your local system +to narrow down your search. + +## Choosing the Right Box + +As with all software and configuration used from a public source, +it's important to keep in mind whose box you're using. Here +are some things to note when you're choosing a box: + +- **The username of the user**. If it's `bento` or `ubuntu`, you can likely + trust the box more than an anonymous user. +- **The number of downloads of the box**. Heavily downloaded boxes + are likely vetted more often by other members of the community. HashiCorp + responds to reports of malicious software distributed via Vagrant Cloud + by disabling and/or removing boxes. If you find a box which includes + malicious software, please report it to: support+vagrantcloud@hashicorp.com. +- **The latest release date**. Boxes which are updated periodically or which + have recent release dates will generally contain more up-to-date software. +- **Availability of the box download**. Vagrant Cloud periodically checks if a box + which is externally hosted (hosted by the box author, not Vagrant Cloud) is publicly + accessible. You can see this information on the box page next to the provider. diff --git a/website/pages/docs/vagrant-cloud/boxes/create-version.html.md b/website/pages/docs/vagrant-cloud/boxes/create-version.html.md new file mode 100644 index 000000000..d926aa582 --- /dev/null +++ b/website/pages/docs/vagrant-cloud/boxes/create-version.html.md @@ -0,0 +1,37 @@ +--- +layout: 'vagrant-cloud' +page_title: 'Create a New Box Version' +sidebar_current: 'vagrant-cloud-boxes-create-version' +--- + +# Create a New Box Version + +To release a new version of a box to the public or to your team: + +1. Click on the name of the box you want to release a new version for. + +2. To the right of the box name, there is a dropdown of all the available + versions. Click this, and click "Create a New Version" + +3. Enter details for your new version and click "Create Version." Note that + after clicking create version, the version is not yet _released_. + +4. Click "Create new provider" on this next page to add at least one + provider to the version. Specify the name of the provider (this is the + same value you specify to `--provider` when using Vagrant). Then + enter the URL to a self-hosted box file or upload a box to us. + +5. Once the provider is created, you now have the option to release the + version by clicking "Release now," or you can add more providers. + +Once you click "Release now," that version will be available for installation +with Vagrant. Before clicking this, Vagrant does not know the version even +exists. + +## Note About Public Boxes + +Be aware, when you create and upload a new version artifact on a public box in +Vagrant Cloud, even if that specific version has not been marked for "release", +it can be accessible if a user knows the box URL with the new version. Releasing +a box simply makes it publicly accessible through search, or through reference +using the `organization/box-name` syntax. diff --git a/website/pages/docs/vagrant-cloud/boxes/create.html.md b/website/pages/docs/vagrant-cloud/boxes/create.html.md new file mode 100644 index 000000000..4d8367e0d --- /dev/null +++ b/website/pages/docs/vagrant-cloud/boxes/create.html.md @@ -0,0 +1,80 @@ +--- +layout: 'vagrant-cloud' +page_title: 'Creating a New Vagrant Box' +sidebar_current: 'vagrant-cloud-boxes-create-x' +--- + +# Creating a New Vagrant Box + +This page will cover creating a new box in Vagrant Cloud and how to distribute +it to users. Boxes can be distributed without Vagrant Cloud, but +miss out on several [important features](/docs/vagrant-cloud/boxes). + +There are **three ways to create and upload Vagrant Boxes to Vagrant Cloud**. All +three options are outlined below. + +We recommend using Packer, as it is fully repeatable and keeps a strong +history of changes within Vagrant Cloud. However, for some situations, including +legacy workflows, the Web UI or API will work well. + +All three options require you [sign up for Vagrant Cloud](https://vagrantcloud.com/account/new). + +## Creating Boxes with Packer + +Using Packer requires more up front effort, but the repeatable and +automated builds will end any manual management of boxes. Additionally, +all boxes will be stored and served from Vagrant Cloud, keeping a history along +the way. + +## Creating Boxes via the Vagrant Cloud Web Interface + +You'll first need to create a box file. This can be done via +the [vagrant `package` command](http://docs.vagrantup.com/v2/boxes/base.html) +or with Packer locally. + +After you've created the `.box` file, this guide can be followed. + +1. Go to the [Create Box](https://vagrantcloud.com/boxes/new) page. + +1. Name the box and give it a simple description + +1. Create your first version for the box. This version + must match the format `[0-9].[0-9].[0-9]` + +1. Create a provider for the box, matching the provider you need + locally in Vagrant. `virtualbox` is the most common provider. + +1. Upload the `.box` file for each provider, or use a url to the `.box` + file that is publicly accessible + +You can find all of your boxes in the [Vagrant section](https://vagrantcloud.com/vagrant) of Vagrant Cloud. + +Once you've created and released a box, you can release new versions of +the box by clicking "Create New Version" under the versions sidebar on +a box page. For more information on the release lifecycle of boxes, see +the [help page dedicated to box lifecycle](/docs/vagrant-cloud/boxes/lifecycle.html). + +## Creating Boxes with the API + +This example uses the API to upload boxes with `curl`. To get started, you'll +need to get an [access token](https://vagrantcloud.com/settings/security). + +Then, prepare the upload: + + $ curl 'https://vagrantcloud.com/api/v1/box/USERNAME/BOX_NAME/version/VERSION/provider/PROVIDER_NAME/upload?access_token=ACCESS_TOKEN' + +This should return something like this: + + { + "upload_path": "https://archivist.hashicorp.com/v1/object/630e42d9-2364-2412-4121-18266770468e" + } + +Then, upload your box with the following command, with the filename in this case being `foo.box`: + + $ curl -X PUT --upload-file foo.box https://archivist.hashicorp.com/v1/object/630e42d9-2364-2412-4121-18266770468e + +When the upload finishes, you can verify it worked by making this request and matching the `hosted_token` it returns to the previously retrieved upload token. + + $ curl 'https://vagrantcloud.com/api/v1/box/USERNAME/BOX_NAME/version/VERSION_NUMBER/provider/PROVIDER_NAME?access_token=ACCESS_TOKEN' + +Your box should then be available for download. diff --git a/website/pages/docs/vagrant-cloud/boxes/distributing.html.md b/website/pages/docs/vagrant-cloud/boxes/distributing.html.md new file mode 100644 index 000000000..57614e3e6 --- /dev/null +++ b/website/pages/docs/vagrant-cloud/boxes/distributing.html.md @@ -0,0 +1,59 @@ +--- +layout: 'vagrant-cloud' +page_title: 'Distributing Boxes' +sidebar_current: 'vagrant-cloud-boxes-distributing' +--- + +## Distributing Boxes + +To distribute the box to your team, update your Vagrantfile to reference the +box on Vagrant Cloud. + + Vagrant.configure(2) do |config| + config.vm.box = "username/example-box" + end + +Now when a team member runs `vagrant up`, the box will be downloaded from Vagrant Cloud. +If the box is private, the team member will be prompted to authorize access. Users +are granted access to private resources by logging in with a Vagrant Cloud username and +password or by using a shared Vagrant Cloud token. +[Learn more about authorization options here](/docs/vagrant-cloud/users/authentication.html). + +## Private Boxes + +If you create a private box, only you (the owner) and collaborators +will be able to access it. This is valuable if you +have information, data or provisioning in your box +that cannot be public. + +Private boxes will be excluded from the box catalog. + +### Collaborators + +Collaborators can be both teams in +organizations or individual users. + +To add a collaborator: + +1. Go to the "Access" page of a box via the sidebar +2. Enter the username or team name and submit the form +3. You'll now see the user or team in the list of collaborators, + and if necessary a collaborator can be removed + +### Vagrant Login + +In order to access these private boxes from Vagrant, you'll need to first +authenticate with your Vagrant Cloud account. + +1. Run `vagrant login` +2. Enter your credentials + +You should now be logged in. We use these credentials to request +a unique authentication token that is stored locally by Vagrant. Your +username or password is never stored on your machine. + +### 404 Not Found + +If you don't authenticate, you will likely receive a `404 Not Found` +error in Vagrant. We return a 404 for security reasons, so a potential +attacker could not verify if a private box exists. diff --git a/website/pages/docs/vagrant-cloud/boxes/index.html.md b/website/pages/docs/vagrant-cloud/boxes/index.html.md new file mode 100644 index 000000000..9bf6882da --- /dev/null +++ b/website/pages/docs/vagrant-cloud/boxes/index.html.md @@ -0,0 +1,32 @@ +--- +layout: 'vagrant-cloud' +page_title: 'About Vagrant Boxes' +sidebar_current: 'vagrant-cloud-boxes' +--- + +# About Vagrant Boxes + +Boxes are the package format for [Vagrant](https://vagrantup.com) environments. +A box can be used on any Vagrant-supported platform to bring up an identical +working environment across a development team. + +## Vagrant Box Creation and Versioning + +Boxes support versioning so that members of your team using Vagrant can update +the underlying box easily, and the people who create boxes can push fixes and +communicate these fixes efficiently. + +Vagrant Cloud makes it easy to manage the versioning of boxes. Versioning boxes in +Vagrant Cloud allows for easy updates, transparent fixes, and clear communication in +changes made. Learn more about the [box release lifecycle +here](/docs/vagrant-cloud/boxes/lifecycle.html). + +## Vagrant Box Catalog and Discovery + +Vagrant Cloud hosts a catalog of publicly available Vagrant Boxes. These are boxes +created by both HashiCorp and community contributions. You can find an owner of +a box by selecting their username in the URL or on the box page. + +Public Vagrant boxes let you get up-and-running quickly in unfamiliar +environments. This is a popular way to set a base development environment +launchable in a single command within an organization or community. diff --git a/website/pages/docs/vagrant-cloud/boxes/lifecycle.html.md b/website/pages/docs/vagrant-cloud/boxes/lifecycle.html.md new file mode 100644 index 000000000..d47a52c5f --- /dev/null +++ b/website/pages/docs/vagrant-cloud/boxes/lifecycle.html.md @@ -0,0 +1,47 @@ +--- +layout: 'vagrant-cloud' +page_title: 'Box Versioning and Lifecycle' +sidebar_current: 'vagrant-cloud-boxes-lifecycle' +--- + +# Box Versioning and Lifecycle + +Boxes support versioning so that members of your team using Vagrant can +update the underlying box easily, and the people who create boxes can +push fixes and communicate these fixes efficiently. + +There are multiple components of a box: + +- The box itself, comprised of the box name and description. +- One or more box versions. +- One or more providers for each box version. + +## Vagrant Messaging + +Upon `vagrant up` or `vagrant box outdated`, an out-of-date box +user will see the following message in Vagrant: + + Bringing machine 'default' up with 'virtualbox' provider... + ==> default: Checking if box 'hashicorp/example' is up to date... + ==> default: A newer version of the box 'hashicorp/example' is available! You currently + ==> default: have version '0.0.5'. The latest is version '0.0.6'. Run + ==> default: `vagrant box update` to update. + ... + +## Box Version Release States + +Vagrant Cloud lets you create new versions of boxes without +releasing them or without Vagrant seeing the update. This lets you prepare +a box for release slowly. Box versions have three states: + +- `unreleased`: Vagrant cannot see this version yet, so it needs + to be released. Versions can be released by editing them and clicking + the release button at the top of the page +- `active`: Vagrant is able to add and use this box version +- `revoked`: Vagrant cannot see this version, and it cannot be re-released. + You must create the version again + +### Release Requirements + +A box can only be released if it has at least one of each component: a +box, a version, and a provider. diff --git a/website/pages/docs/vagrant-cloud/boxes/private.html.md b/website/pages/docs/vagrant-cloud/boxes/private.html.md new file mode 100644 index 000000000..79083290d --- /dev/null +++ b/website/pages/docs/vagrant-cloud/boxes/private.html.md @@ -0,0 +1,44 @@ +--- +layout: 'vagrant-cloud' +page_title: 'Private Boxes' +sidebar_current: 'vagrant-cloud-boxes-private' +--- + +# Private Boxes + +If you create a private box, only you (the owner) and collaborators +will be able to access it. + +## Collaborators + +To add a collaborator: + +1. Click the gear setting beside the boxes name in order to edit it. +2. Under the "Add Collaborator" section, enter their username and + submit the form. +3. You'll now see a list of collaborators, and if necessary a collaborator + can be removed. + +Collaborators can edit the box, versions and providers. The only +things they cannot do are: + +- Add another collaborator +- Delete the box + +## Vagrant Login + +In order to access these boxes from Vagrant, you'll need to first +authenticate with your Vagrant Cloud account. + +1. Run `vagrant login` +2. Enter your credentials + +You should now be logged in. We use these credentials to request +a unique authentication token that is stored locally by Vagrant. Your +username or password is never stored on your machine. + +## 404 Not Found + +If you don't authenticate, you will likely receive a `404 Not Found` +error in Vagrant. We return a 404 for security reasons, so a potential +attacker could not verify if a private box exists. diff --git a/website/pages/docs/vagrant-cloud/boxes/release-workflow.html.md b/website/pages/docs/vagrant-cloud/boxes/release-workflow.html.md new file mode 100644 index 000000000..1f8697a5e --- /dev/null +++ b/website/pages/docs/vagrant-cloud/boxes/release-workflow.html.md @@ -0,0 +1,24 @@ +--- +layout: 'vagrant-cloud' +page_title: 'API Release Workflow' +sidebar_current: 'vagrant-cloud-boxes-release-workflow' +--- + +# API Release Workflow + +Creating new boxes through their [release lifecycle](/docs/vagrant-cloud/boxes/lifecycle.html) +is possible through the Vagrant Cloud website, but you can also automate +the task via the Vagrant Cloud API. + +1. Create box, or locate a boxes `tag`, like `hashicorp/bionic64` +2. After some event, like the end of a CI build, you may want to + release a new version of the box. To do this, first use the API to + create a new version with a version number and a short description + of the changes +3. Then, create any providers associated with the version, like + `virtualbox` +4. Once your system has made the necessary requests to the API and the + version is ready, make a request to the `release` endpoint on the version +5. The version should now be available to users of the box via + the command `vagrant box outdated` or via the automated checks on + `vagrant up` diff --git a/website/pages/docs/vagrant-cloud/boxes/using.html.md b/website/pages/docs/vagrant-cloud/boxes/using.html.md new file mode 100644 index 000000000..4925f8041 --- /dev/null +++ b/website/pages/docs/vagrant-cloud/boxes/using.html.md @@ -0,0 +1,21 @@ +--- +layout: 'vagrant-cloud' +page_title: 'Finding and Using Boxes' +sidebar_current: 'vagrant-cloud-boxes-using' +--- + +# Finding and Using Boxes + +A primary use case of Vagrant Cloud by HashiCorp is to be able to easily find +boxes you can use with Vagrant that contain the technologies you need +for a Vagrant environment. We've made it extremely easy to do that: + +1. Go to the [Discover page](https://vagrantcloud.com/discover), and search for + any box you want. + +1. Once you find a box, click its name to learn more about it. + +1. When you're ready to use it, copy the name, such as "hashicorp/bionic64" + and initialize your Vagrant project with `vagrant init hashicorp/bionic64`. + Or, if you already have a Vagrant project created, modify the Vagrantfile + to use the box: `config.vm.box = "hashicorp/bionic64"` diff --git a/website/pages/docs/vagrant-cloud/index.html.md b/website/pages/docs/vagrant-cloud/index.html.md new file mode 100644 index 000000000..eaea70d76 --- /dev/null +++ b/website/pages/docs/vagrant-cloud/index.html.md @@ -0,0 +1,25 @@ +--- +layout: 'vagrant-cloud' +page_title: 'Vagrant Cloud' +sidebar_current: 'vagrant-cloud' +--- + +# Vagrant Cloud + +## Support + +For Vagrant Cloud questions, feedback, or feature requests, please email +HashiCorp Support at + +support+vagrantcloud@hashicorp.com +. + +[Click here](/docs/vagrant-cloud/support.html) for more support information. + +## Features + +Vagrant Cloud provides the following features for Vagrant: + +- [Vagrant Box Catalog](/docs/vagrant-cloud/boxes/catalog.html) +- [Vagrant Box Creation](/docs/vagrant-cloud/boxes/create.html) +- [Vagrant Box Versioning](/docs/vagrant-cloud/boxes/lifecycle.html) diff --git a/website/pages/docs/vagrant-cloud/organizations/authentication-policy.html.md b/website/pages/docs/vagrant-cloud/organizations/authentication-policy.html.md new file mode 100755 index 000000000..a747545d8 --- /dev/null +++ b/website/pages/docs/vagrant-cloud/organizations/authentication-policy.html.md @@ -0,0 +1,29 @@ +--- +layout: 'vagrant-cloud' +page_title: 'Organization Authentication Policy' +sidebar_current: 'vagrant-cloud-organizations-authentication-policy' +--- + +# Set an Organization Authentication Policy + +Because organization membership affords members access to potentially sensitive +resources, owners can set organization-wide authentication policy in Vagrant +Enterprise. + +## Requiring Two-Factor Authentication + +Organization owners can require that all organization team members use +[two-factor authentication](/docs/vagrant-cloud/users/authentication.html). +Those that lack two-factor authentication will be locked out of the web +interface until they enable it or leave the organization. + +Visit your organization's configuration page to enable this feature. All +organization owners must have two-factor authentication enabled to require the +practice organization-wide. Note: locked-out users are still be able to interact +with Vagrant Cloud using their `ATLAS_TOKEN`. + +## Disabling Two-Factor Authentication Requirement + +Organization owners can disable the two-factor authentication requirement from +their organization's configuration page. Locked-out team members (those who have +not enabled two-factor authentication) will have their memberships reinstated. diff --git a/website/pages/docs/vagrant-cloud/organizations/create.html.md b/website/pages/docs/vagrant-cloud/organizations/create.html.md new file mode 100755 index 000000000..52ddf13cf --- /dev/null +++ b/website/pages/docs/vagrant-cloud/organizations/create.html.md @@ -0,0 +1,15 @@ +--- +layout: 'vagrant-cloud' +page_title: 'Create an Organization' +sidebar_current: 'vagrant-cloud-organizations-create' +--- + +# Create an Organization + +To create an organization: + +1. Create a personal account. You'll use this to create and administrate the + organization. You'll be able to add other users as owners of the organization, + so it won't be tied solely to your account. + +1. Visit your new organization page to create the organization. diff --git a/website/pages/docs/vagrant-cloud/organizations/index.html.md b/website/pages/docs/vagrant-cloud/organizations/index.html.md new file mode 100755 index 000000000..c47602d92 --- /dev/null +++ b/website/pages/docs/vagrant-cloud/organizations/index.html.md @@ -0,0 +1,14 @@ +--- +layout: 'vagrant-cloud' +page_page_title: 'Organizations in Vagrant Cloud' +sidebar_current: 'vagrant-cloud-organizations' +--- + +## Organizations in Vagrant Cloud + +Organizations are a group of users in Vagrant Cloud that have access and +ownership over shared resources. When operating within a team, we recommend +creating an organization to manage access control, auditing, billing and +authorization. + +Each individual member of your organization should have their own account. diff --git a/website/pages/docs/vagrant-cloud/organizations/migrate.html.md b/website/pages/docs/vagrant-cloud/organizations/migrate.html.md new file mode 100755 index 000000000..ea4f2e1f6 --- /dev/null +++ b/website/pages/docs/vagrant-cloud/organizations/migrate.html.md @@ -0,0 +1,26 @@ +--- +layout: 'vagrant-cloud' +page_title: 'Migrate User to Organization' +sidebar_current: 'vagrant-cloud-organizations-migrate' +--- + +# Migrate User to Organization + +To migrate an existing user account to an organization: + +1. Create or retrieve the username of a new personal account. You'll add this + account as an "owner" for the new organization during the migration process. If + you already have another account, write down your username. + +2. Sign in as the account you wish to migrate. + +3. Go to [the account migration page](https://app.vagrantup.com/account/migrate). + +4. Put the username of the personal account you wish to make an owner of the + organization into the username text field and press "Migrate". + +5. You should now be logged out and receive a confirmation email with the + personal account you migrated to. + +6. Now, sign in with your personal account. If you visit you settings page, you + should see your migrated organization available to administrate. diff --git a/website/pages/docs/vagrant-cloud/request-limits.html.md b/website/pages/docs/vagrant-cloud/request-limits.html.md new file mode 100644 index 000000000..655fad81c --- /dev/null +++ b/website/pages/docs/vagrant-cloud/request-limits.html.md @@ -0,0 +1,34 @@ +--- +layout: 'vagrant-cloud' +page_title: 'Request Limits' +sidebar_current: 'vagrant-cloud-request-limits' +--- + +# Request Limits + +## What is Rate Limiting? + +Rate limiting is a process to protect our quality of service we provide to you. Rate limiting will limit the number of requests a client may send to services over a set time interval. We track requests by IP address origin of the request. + +## How many requests can I make? + +You can make a set amount of requests per minute from a single IP address. This rate can vary per resource but the current value is returned in the HTTP headers of your request. For the most up to date rate limiting for your requests please view the information in the headers of your response. + +## Why are you rate limiting my requests? + +We have detected a request rate in excess of our current threshold. To provide a high quality of services to all users, your request may have been rate limited. + +## How do I know if I have been rate limited? + +If you have received a 429 HTTP status code in the response to your request, your request has likely been rate limited. There is some additional information in the headers that will help you determine if this is the case. Each request response will include the headers: X-RateLimit-Limit, X-RateLimit-Remaining, and X-RateLimit-Reset. + +- **X-RateLimit-Limit**: The current maximum number of requests allowed from your client. +- **X-RateLimit-Remaining**: How many requests you have remaining in the time window. +- **X-RateLimit-Reset**: The unix timestamp for when the window resets. + +## My use case requires more requests. What do I do? + +Please contact + +support+vagrantcloud@hashicorp.com +. diff --git a/website/pages/docs/vagrant-cloud/support.html.md b/website/pages/docs/vagrant-cloud/support.html.md new file mode 100755 index 000000000..a328eccca --- /dev/null +++ b/website/pages/docs/vagrant-cloud/support.html.md @@ -0,0 +1,47 @@ +--- +layout: 'vagrant-cloud' +page_title: 'Vagrant Cloud Support' +sidebar_current: 'vagrant-cloud-support' +--- + +# Contacting Support + +All users of Vagrant Cloud are urged to email feedback, questions, and requests +to HashiCorp Support at + +support+vagrantcloud@hashicorp.com +. + +### Free Support + +We do not currently publish support SLAs for free accounts, but endeavor to +respond as quickly as possible. We respond to most requests within less than 24 +hours. + +## HashiCorp Tools Support + +It's often the case that Vagrant Cloud questions or feedback relates to +the HashiCorp tooling. We encourage all Vagrant Cloud users to search for +related issues and problems in the open source repositories and mailing lists +prior to contacting us to help make our support more efficient and to help +resolve problems faster. + +Visit the updating tools section for a list of our tools and their project +websites. + +## Documentation Feedback + +Due to the dynamic nature of Vagrant Cloud and the broad set of features +it provides, there may be information lacking in the documentation. + +Vagrant Cloud documentation is open source. +If you'd like to improve or correct the documentation, +please submit a pull-request to the +[Vagrant project on GitHub](https://github.com/hashicorp/vagrant/tree/master/website/source/docs/vagrant-cloud/). +The Vagrant Cloud documentation can be found in the `/website/source/vagrant-cloud/` directory. + +Otherwise, to make a suggestion or report an error in documentation, please +email feedback to + +support+vagrantcloud@hashicorp.com +. diff --git a/website/pages/docs/vagrant-cloud/users/authentication.html.md b/website/pages/docs/vagrant-cloud/users/authentication.html.md new file mode 100755 index 000000000..d14322c08 --- /dev/null +++ b/website/pages/docs/vagrant-cloud/users/authentication.html.md @@ -0,0 +1,56 @@ +--- +layout: 'vagrant-cloud' +page_title: 'Authentication' +sidebar_current: 'vagrant-cloud-users-authentication' +--- + +# Authentication + +Vagrant Cloud requires a username and password to sign up and login. +However, there are several ways to authenticate with your account. + +### Authentication Tokens + +Authentication tokens are keys used to access your account via tools or over the +various APIs used in Vagrant Cloud. + +You can create new tokens in the token section of your account settings. It's +important to keep tokens secure, as they are essentially a password and can be +used to access your account or resources. Additionally, token authentication +bypasses two factor authentication. + +### Authenticating Tools + +All HashiCorp tools look for the `ATLAS_TOKEN` environment variable: + +```shell +$ export ATLAS_TOKEN=TOKEN +``` + +This will automatically authenticate all requests against this token. This is +the recommended way to authenticate with our various tools. Care should be given +to how this token is stored, as it is as good as a password. + +### Two Factor Authentication + +You can optionally enable Two Factor authentication, requiring an SMS or TOTP +one-time code every time you log in, after entering your username and password. + +You can enable Two Factor authentication in the security section of your account +settings. + +Be sure to save the generated recovery codes. Each backup code can be used once +to sign in if you do not have access to your two-factor authentication device. + +### Sudo Mode + +When accessing certain admin-level pages (adjusting your user profile, for +example), you may notice that you're prompted for your password, even though +you're already logged in. This is by design, and aims to help guard protect you +if your screen is unlocked and unattended. + +### Session Management + +You can see a list of your active sessions on your security settings page. From +here, you can revoke sessions, in case you have lost access to a machine from +which you were accessing. diff --git a/website/pages/docs/vagrant-cloud/users/index.html.md b/website/pages/docs/vagrant-cloud/users/index.html.md new file mode 100755 index 000000000..b162ee862 --- /dev/null +++ b/website/pages/docs/vagrant-cloud/users/index.html.md @@ -0,0 +1,11 @@ +--- +layout: 'vagrant-cloud' +page_title: 'User Accounts' +sidebar_current: 'vagrant-cloud-users' +--- + +# User Accounts + +Users are the main identity system in Vagrant Cloud. A user can be a +member of multiple [organizations](/docs/vagrant-cloud/organizations/index.html), +as well as individually collaborate on various resources. diff --git a/website/pages/docs/vagrant-cloud/users/recovery.html.md b/website/pages/docs/vagrant-cloud/users/recovery.html.md new file mode 100755 index 000000000..32cf9cdec --- /dev/null +++ b/website/pages/docs/vagrant-cloud/users/recovery.html.md @@ -0,0 +1,13 @@ +--- +layout: 'vagrant-cloud' +page_title: 'Account Recovery' +sidebar_current: 'vagrant-cloud-users-recovery' +--- + +# Account Recovery + +If you have lost access to your Vagrant Cloud account, use the reset +password form on the login page to send yourself a link to reset your password. + +If an email is unknown, [contact us](mailto:support+vagrantcloud@hashicorp.com) +for further help. diff --git a/website/pages/docs/vagrantfile/index.html.md b/website/pages/docs/vagrantfile/index.html.md new file mode 100644 index 000000000..316434221 --- /dev/null +++ b/website/pages/docs/vagrantfile/index.html.md @@ -0,0 +1,87 @@ +--- +layout: 'docs' +page_title: 'Vagrantfile' +sidebar_current: 'vagrantfile' +description: |- + The primary function of the Vagrantfile is to describe the type + of machine required for a project, and how to configure and + provision these machines. Vagrantfiles are called Vagrantfiles because + the actual literal filename for the file is "Vagrantfile". +--- + +# Vagrantfile + +The primary function of the Vagrantfile is to describe the type +of machine required for a project, and how to configure and +provision these machines. Vagrantfiles are called Vagrantfiles because +the actual literal filename for the file is `Vagrantfile` (casing does not +matter unless your file system is running in a strict case sensitive mode). + +Vagrant is meant to run with one Vagrantfile per project, and the Vagrantfile +is supposed to be committed to version control. This allows other developers +involved in the project to check out the code, run `vagrant up`, and be on +their way. Vagrantfiles are portable across every platform Vagrant supports. + +The syntax of Vagrantfiles is [Ruby](http://www.ruby-lang.org), but knowledge +of the Ruby programming language is not necessary to make modifications to the +Vagrantfile, since it is mostly simple variable assignment. In fact, Ruby is not +even the most popular community Vagrant is used within, which should help show +you that despite not having Ruby knowledge, people are very successful with +Vagrant. + +## Lookup Path + +When you run any `vagrant` command, Vagrant climbs up the directory tree +looking for the first Vagrantfile it can find, starting first in the +current directory. So if you run `vagrant` in `/home/mitchellh/projects/foo`, +it will search the following paths in order for a Vagrantfile, until it +finds one: + +``` +/home/mitchellh/projects/foo/Vagrantfile +/home/mitchellh/projects/Vagrantfile +/home/mitchellh/Vagrantfile +/home/Vagrantfile +/Vagrantfile +``` + +This feature lets you run `vagrant` from any directory in your project. + +You can change the starting directory where Vagrant looks for a Vagrantfile +by setting the `VAGRANT_CWD` environmental variable to some other path. + + + +## Load Order and Merging + +An important concept to understand is how Vagrant loads Vagrantfiles. Vagrant +actually loads a series of Vagrantfiles, merging the settings as it goes. This +allows Vagrantfiles of varying level of specificity to override prior settings. +Vagrantfiles are loaded in the order shown below. Note that if a Vagrantfile +is not found at any step, Vagrant continues with the next step. + +1. Vagrantfile packaged with the [box](/docs/boxes.html) that is to be used + for a given machine. +2. Vagrantfile in your Vagrant home directory (defaults to `~/.vagrant.d`). + This lets you specify some defaults for your system user. +3. Vagrantfile from the project directory. This is the Vagrantfile that you will + be modifying most of the time. +4. [Multi-machine overrides](/docs/multi-machine/) if any. +5. [Provider-specific overrides](/docs/providers/configuration.html), + if any. + +At each level, settings set will be merged with previous values. What this +exactly means depends on the setting. For most settings, this means that +the newer setting overrides the older one. However, for things such as defining +networks, the networks are actually appended to each other. By default, you +should assume that settings will override each other. If the behavior is +different, it will be noted in the relevant documentation section. + +Within each Vagrantfile, you may specify multiple `Vagrant.configure` blocks. +All configurations will be merged within a single Vagrantfile in the order +they're defined. + +## Available Configuration Options + +You can learn more about the available configuration options by clicking +the relevant section in the left navigational area. diff --git a/website/pages/docs/vagrantfile/machine_settings.html.md b/website/pages/docs/vagrantfile/machine_settings.html.md new file mode 100644 index 000000000..b39b02f89 --- /dev/null +++ b/website/pages/docs/vagrantfile/machine_settings.html.md @@ -0,0 +1,143 @@ +--- +layout: 'docs' +page_title: 'config.vm - Vagrantfile' +sidebar_current: 'vagrantfile-machine' +description: |- + The settings within "config.vm" modify the configuration of the + machine that Vagrant manages. +--- + +# Machine Settings + +**Config namespace: `config.vm`** + +The settings within `config.vm` modify the configuration of the +machine that Vagrant manages. + +## Available Settings + +- `config.vm.base_mac` (string) - The MAC address to be assigned to the default + NAT interface on the guest. _Support for this option is provider dependent._ + +- `config.vm.base_address` (string) - The IP address to be assigned to the default + NAT interface on the guest. _Support for this option is provider dependent._ + +- `config.vm.boot_timeout` (integer) - The time in seconds that Vagrant will wait + for the machine to boot and be accessible. By default this is 300 seconds. + +- `config.vm.box` (string) - This configures what [box](/docs/boxes.html) the + machine will be brought up against. The value here should be the name + of an installed box or a shorthand name of a box in + [HashiCorp's Vagrant Cloud](/docs/vagrant-cloud). + +- `config.vm.box_check_update` (boolean) - If true, Vagrant will check for updates to + the configured box on every `vagrant up`. If an update is found, Vagrant + will tell the user. By default this is true. Updates will only be checked + for boxes that properly support updates (boxes from + [HashiCorp's Vagrant Cloud](/docs/vagrant-cloud) + or some other versioned box). + +- `config.vm.box_download_checksum` (string) - The checksum of the box specified by + `config.vm.box_url`. If not specified, no checksum comparison will be done. + If specified, Vagrant will compare the checksum of the downloaded box to + this value and error if they do not match. Checksum checking is only done + when Vagrant must download the box. If this is specified, then + `config.vm.box_download_checksum_type` must also be specified. + +- `config.vm.box_download_checksum_type` (string) - The type of checksum specified + by `config.vm.box_download_checksum` (if any). Supported values are + currently "md5", "sha1", "sha256", "sha384", and "sha512". + +- `config.vm.box_download_client_cert` (string) - Path to a client certificate to + use when downloading the box, if it is necessary. By default, no client + certificate is used to download the box. + +- `config.vm.box_download_ca_cert` (string) - Path to a CA cert bundle to use when + downloading a box directly. By default, Vagrant will use the Mozilla CA cert + bundle. + +- `config.vm.box_download_ca_path` (string) - Path to a directory containing + CA certificates for downloading a box directly. By default, Vagrant will + use the Mozilla CA cert bundle. + +- `config.vm.box_download_options` (map) - A map of extra download options + to pass to the downloader. For example, a path to a key that the downloader + should use could be specified as `{key: ""}`. The keys should + be options supported by `curl` using the unshortened form of the flag. For + example, use `append` instead of `a`. + +- `config.vm.box_download_insecure` (boolean) - If true, then SSL certificates + from the server will not be verified. By default, if the URL is an HTTPS + URL, then SSL certs will be verified. + +- `config.vm.box_download_location_trusted` (boolean) - If true, then all HTTP redirects will be + treated as trusted. That means credentials used for initial URL will be used for + all subsequent redirects. By default, redirect locations are untrusted so credentials + (if specified) used only for initial HTTP request. + +- `config.vm.box_url` (string, array of strings) - The URL that the configured box can be found at. + If `config.vm.box` is a shorthand to a box in [HashiCorp's Vagrant Cloud](/docs/vagrant-cloud) + then this value does not need to be specified. Otherwise, it should + point to the proper place where the box can be found if it is not + installed. This can also be an array of multiple URLs. The URLs will be tried in + order. + + Note that any client certificates, insecure download settings, and + so on will apply to all URLs in this list. The URLs can also be local files + by using the `file://` scheme. For example: "file:///tmp/test.box". + +- `config.vm.box_version` (string) - The version of the box to use. This defaults to + ">= 0" (the latest version available). This can contain an arbitrary list + of constraints, separated by commas, such as: `>= 1.0, < 1.5`. When constraints + are given, Vagrant will use the latest available box satisfying these + constraints. + +- `config.vm.communicator` (string) - The communicator type to use to connect to the + guest box. By default this is `"ssh"`, but should be changed to `"winrm"` for + Windows guests. + +- `config.vm.graceful_halt_timeout` (integer) - The time in seconds that Vagrant will + wait for the machine to gracefully halt when `vagrant halt` is called. + Defaults to 60 seconds. + +- `config.vm.guest` (string, symbol) - The guest OS that will be running within this + machine. This defaults to `:linux`, and Vagrant will auto-detect the + proper distro. However, this should be changed to `:windows` for Windows guests. + Vagrant needs to know this information to perform some guest OS-specific things + such as mounting folders and configuring networks. + +- `config.vm.hostname` (string) - The hostname the machine should have. Defaults + to nil. If nil, Vagrant will not manage the hostname. If set to a string, + the hostname will be set on boot. If set, Vagrant will update `/etc/hosts` + on the guest with the configured hostname. + +- `config.vm.ignore_box_vagrantfile` (boolean) - If true, Vagrant will not load the the + settings found inside a boxes Vagrantfile, if present. Defaults to `false`. + +- `config.vm.network` - Configures [networks](/docs/networking/) on + the machine. Please see the networking page for more information. + +- `config.vm.post_up_message` (string) - A message to show after `vagrant up`. This + will be shown to the user and is useful for containing instructions + such as how to access various components of the development environment. + +- `config.vm.provider` - Configures [provider-specific configuration](/docs/providers/configuration.html), + which is used to modify settings which are specific to a certain + [provider](/docs/providers/). If the provider you are configuring + does not exist or is not setup on the system of the person who runs + `vagrant up`, Vagrant will ignore this configuration block. This allows + a Vagrantfile that is configured for many providers to be shared among + a group of people who may not have all the same providers installed. + +- `config.vm.provision` - Configures [provisioners](/docs/provisioning/) + on the machine, so that software can be automatically installed and configured + when the machine is created. Please see the page on provisioners for more + information on how this setting works. + +- `config.vm.synced_folder` - Configures [synced folders](/docs/synced-folders/) + on the machine, so that folders on your host machine can be synced to + and from the guest machine. Please see the page on synced folders for + more information on how this setting works. + +- `config.vm.usable_port_range` (range) - A range of ports Vagrant can use for + handling port collisions and such. Defaults to `2200..2250`. diff --git a/website/pages/docs/vagrantfile/ssh_settings.html.md b/website/pages/docs/vagrantfile/ssh_settings.html.md new file mode 100644 index 000000000..331f79e61 --- /dev/null +++ b/website/pages/docs/vagrantfile/ssh_settings.html.md @@ -0,0 +1,146 @@ +--- +layout: 'docs' +page_title: 'config.ssh - Vagrantfile' +sidebar_current: 'vagrantfile-ssh' +description: |- + The settings within "config.ssh" relate to configuring how Vagrant + will access your machine over SSH. As with most Vagrant settings, the + defaults are typically fine, but you can fine tune whatever you would like. +--- + +# SSH Settings + +**Config namespace: `config.ssh`** + +The settings within `config.ssh` relate to configuring how Vagrant +will access your machine over SSH. As with most Vagrant settings, the +defaults are typically fine, but you can fine tune whatever you would like. + +## Available Settings + +- `config.ssh.compression` (boolean) - If `false`, this setting will not include the + compression setting when ssh'ing into a machine. If this is not set, it will + default to `true` and `Compression=yes` will be enabled with ssh. + +- `config.ssh.connect_timeout` (integer) - Number of seconds to wait for establishing + an SSH connection to the guest. Defaults to `15`. + +- `config.ssh.config` (string) - Path to a custom ssh_config file to use for configuring + the SSH connections. + +- `config.ssh.dsa_authentication` (boolean) - If `false`, this setting will not include + `DSAAuthentication` when ssh'ing into a machine. If this is not set, it will + default to `true` and `DSAAuthentication=yes` will be used with ssh. + +- `config.ssh.export_command_template` (string) - The template used to generate + exported environment variables in the active session. This can be useful + when using a Bourne incompatible shell like C shell. The template supports + two variables which are replaced with the desired environment variable key and + environment variable value: `%ENV_KEY%` and `%ENV_VALUE%`. The default template + is: + + ```ruby + config.ssh.export_command_template = 'export %ENV_KEY%="%ENV_VALUE%"' + ``` + +- `config.ssh.extra_args` (array of strings) - This settings value is passed directly + into the ssh executable. This allows you to pass any arbitrary commands to do things such + as reverse tunneling down into the ssh program. These options can either be + single flags set as strings such as `"-6"` for IPV6 or an array of arguments + such as `["-L", "8008:localhost:80"]` for enabling a tunnel from host port 8008 + to port 80 on guest. + +- `config.ssh.forward_agent` (boolean) - If `true`, agent forwarding over SSH + connections is enabled. Defaults to false. + +- `config.ssh.forward_env` (array of strings) - An array of host environment variables to + forward to the guest. If you are familiar with OpenSSH, this corresponds to the `SendEnv` + parameter. + + ```ruby + config.ssh.forward_env = ["CUSTOM_VAR"] + ``` + +- `config.ssh.forward_x11` (boolean) - If `true`, X11 forwarding over SSH connections + is enabled. Defaults to false. + +- `config.ssh.guest_port` (integer) - The port on the guest that SSH is running on. This + is used by some providers to detect forwarded ports for SSH. For example, if + this is set to 22 (the default), and Vagrant detects a forwarded port to + port 22 on the guest from port 4567 on the host, Vagrant will attempt + to use port 4567 to talk to the guest if there is no other option. + +- `config.ssh.host` (string) - The hostname or IP to SSH into. By default this is + empty, because the provider usually figures this out for you. + +- `config.ssh.insert_key` (boolean) - By default or if set to `true`, Vagrant will automatically insert + a keypair to use for SSH, replacing Vagrant's default insecure key inside the machine + if detected. If you already use private keys for authentication to your guest, or are relying + on the default insecure key, this option will not be used. If set to `false`, + Vagrant will not automatically add a keypair to the guest. + +- `config.ssh.keep_alive` (boolean) - If `true`, this setting SSH will send keep-alive packets + every 5 seconds by default to keep connections alive. + +- `config.ssh.keys_only` (boolean) - Only use Vagrant-provided SSH private keys (do not use + any keys stored in ssh-agent). The default value is `true`. + +- `config.ssh.paranoid` (boolean) - Perform strict host-key verification. The default value is + `false`. + + __Deprecation:__ The `config.ssh.paranoid` option is deprecated and will be removed + in a future release. Please use the `config.ssh.verify_host_key` option instead. + +- `config.ssh.password` (string) - This sets a password that Vagrant will use to + authenticate the SSH user. Note that Vagrant recommends you use key-based + authentication rather than a password (see `private_key_path`) below. If + you use a password, Vagrant will automatically insert a keypair if + `insert_key` is true. + +- `config.ssh.port` (integer) - The port to SSH into. By default this is port 22. + +- `config.ssh.private_key_path` (string, array of strings) - The path to the private + key to use to SSH into the guest machine. By default this is the insecure private key + that ships with Vagrant, since that is what public boxes use. If you make + your own custom box with a custom SSH key, this should point to that + private key. You can also specify multiple private keys by setting this to be an array. + This is useful, for example, if you use the default private key to bootstrap + the machine, but replace it with perhaps a more secure key later. + +- `config.ssh.proxy_command` (string) - A command-line command to execute that receives + the data to send to SSH on stdin. This can be used to proxy the SSH connection. + `%h` in the command is replaced with the host and `%p` is replaced with + the port. + +- `config.ssh.pty` (boolean) - If `true`, pty will be used for provisioning. Defaults to false. + + This setting is an _advanced feature_ that should not be enabled unless + absolutely necessary. It breaks some other features of Vagrant, and is + really only exposed for cases where it is absolutely necessary. If you can find + a way to not use a pty, that is recommended instead. + + When pty is enabled, it is important to note that command output will _not_ be + streamed to the UI. Instead, the output will be delivered in full to the UI + once the command has completed. + +- `config.ssh.remote_user` (string) - The "remote user" value used to replace the `%r` + character(s) used within a configured `ProxyCommand`. This value is only used by the + net-ssh library (ignored by the `ssh` executable) and should not be used in general. + This defaults to the value of `config.ssh.username`. + +- `config.ssh.shell` (string) - The shell to use when executing SSH commands from + Vagrant. By default this is `bash -l`. + +- `config.ssh.sudo_command` (string) - The command to use when executing a command + with `sudo`. This defaults to `sudo -E -H %c`. The `%c` will be replaced by + the command that is being executed. + +- `config.ssh.username` (string) - This sets the username that Vagrant will SSH + as by default. Providers are free to override this if they detect a more + appropriate user. By default this is "vagrant", since that is what most + public boxes are made as. + +- `config.ssh.verify_host_key` (string, symbol) - Perform strict host-key verification. The + default value is `:never`. The other options are `:accept_new_or_local_tunnel`, + `:accept_new`, or `:always`, which each refer to one of + [net-ssh](https://net-ssh.github.io/net-ssh/)'s `Net::SSH::Verifiers` subclasses. diff --git a/website/pages/docs/vagrantfile/tips.html.md b/website/pages/docs/vagrantfile/tips.html.md new file mode 100644 index 000000000..fb39b9012 --- /dev/null +++ b/website/pages/docs/vagrantfile/tips.html.md @@ -0,0 +1,72 @@ +--- +layout: 'docs' +page_title: 'Tips & Tricks - Vagrantfile' +sidebar_current: 'vagrantfile-tips' +description: |- + The Vagrantfile is a very flexible configuration format. Since it is just + Ruby, there is a lot you can do with it. However, in that same vein, since + it is Ruby, there are a lot of ways you can shoot yourself in the foot. When + using some of the tips and tricks on this page, please take care to use them + correctly. +--- + +# Tips & Tricks + +The Vagrantfile is a very flexible configuration format. Since it is just +Ruby, there is a lot you can do with it. However, in that same vein, since +it is Ruby, there are a lot of ways you can shoot yourself in the foot. When +using some of the tips and tricks on this page, please take care to use them +correctly. + +## Loop Over VM Definitions + +If you want to apply a slightly different configuration to many +multi-machine machines, you can use a loop to do this. For example, if +you wanted to create three machines: + +```ruby +(1..3).each do |i| + config.vm.define "node-#{i}" do |node| + node.vm.provision "shell", + inline: "echo hello from node #{i}" + end +end +``` + +~> **Warning:** The inner portion of multi-machine definitions +and provider overrides are lazy-loaded. This can cause issues if you change +the value of a variable used within the configs. For example, the loop below +does not work: + +```ruby +# THIS DOES NOT WORK! +for i in 1..3 do + config.vm.define "node-#{i}" do |node| + node.vm.provision "shell", + inline: "echo hello from node #{i}" + end +end +``` + +The `for i in ...` construct in Ruby actually modifies the value of `i` +for each iteration, rather than making a copy. Therefore, when you run this, +every node will actually provision with the same text. + +This is an easy mistake to make, and Vagrant cannot really protect against it, +so the best we can do is mention it here. + +## Overwrite host locale in ssh session + +Usually, host locale environment variables are passed to guest. It may cause +failures if the guest software do not support host locale. One possible solution +is override locale in the `Vagrantfile`: + +```ruby +ENV["LC_ALL"] = "en_US.UTF-8" + +Vagrant.configure("2") do |config| + # ... +end +``` + +The change is only visible within the `Vagrantfile`. diff --git a/website/pages/docs/vagrantfile/vagrant_settings.html.md b/website/pages/docs/vagrantfile/vagrant_settings.html.md new file mode 100644 index 000000000..58d0412be --- /dev/null +++ b/website/pages/docs/vagrantfile/vagrant_settings.html.md @@ -0,0 +1,63 @@ +--- +layout: 'docs' +page_title: 'config.vagrant - Vagrantfile' +sidebar_current: 'vagrantfile-vagrant' +description: |- + The settings within "config.vagrant" modify the behavior of Vagrant + itself. +--- + +# Vagrant Settings + +**Config namespace: `config.vagrant`** + +The settings within `config.vagrant` modify the behavior of Vagrant +itself. + +## Available Settings + +- `config.vagrant.host` (string, symbol) - This sets the type of host machine + that is running Vagrant. By default this is `:detect`, which causes Vagrant to + auto-detect the host. Vagrant needs to know this information in order to perform + some host-specific things, such as preparing NFS folders if they're enabled. + You should only manually set this if auto-detection fails. + +- `config.vagrant.plugins` - (string, array, hash) - Define plugin, list of + plugins, or definition of plugins to install for the local project. Vagrant + will require these plugins be installed and available for the project. If + the plugins are not available, it will attempt to automatically install + them into the local project. When requiring a single plugin, a string can + be provided: + + ```ruby + config.vagrant.plugins = "vagrant-plugin" + ``` + + If multiple plugins are required, they can be provided as an array: + + ```ruby + config.vagrant.plugins = ["vagrant-plugin", "vagrant-other-plugin"] + ``` + + Plugins can also be defined as a Hash, which supports setting extra options + for the plugins. When a Hash is used, the key is the name of the plugin, and + the value is a Hash of options for the plugin. For example, to set an explicit + version of a plugin to install: + + ```ruby + config.vagrant.plugins = {"vagrant-scp" => {"version" => "1.0.0"}} + ``` + + Supported options are: + + * `entry_point` - Path for Vagrant to load plugin + * `sources` - Custom sources for downloading plugin + * `version` - Version constraint for plugin + +- `config.vagrant.sensitive` - (string, array) - Value or list of values that + should not be displayed in Vagrant's output. Value(s) will be removed from + Vagrant's normal UI output as well as logger output. + + ```ruby + config.vagrant.sensitive = ["MySecretPassword", ENV["MY_TOKEN"]] + ``` diff --git a/website/pages/docs/vagrantfile/vagrant_version.html.md b/website/pages/docs/vagrantfile/vagrant_version.html.md new file mode 100644 index 000000000..9e5874783 --- /dev/null +++ b/website/pages/docs/vagrantfile/vagrant_version.html.md @@ -0,0 +1,33 @@ +--- +layout: 'docs' +page_title: 'Minimum Vagrant Version - Vagrantfile' +sidebar_current: 'vagrantfile-minversion' +description: |- + A set of Vagrant version requirements can be specified in the Vagrantfile + to enforce that people use a specific version of Vagrant with a Vagrantfile. + This can help with compatibility issues that may otherwise arise from using + a too old or too new Vagrant version with a Vagrantfile. +--- + +# Minimum Vagrant Version + +A set of Vagrant version requirements can be specified in the Vagrantfile +to enforce that people use a specific version of Vagrant with a Vagrantfile. +This can help with compatibility issues that may otherwise arise from using +a too old or too new Vagrant version with a Vagrantfile. + +Vagrant version requirements should be specified at the top of a Vagrantfile +with the `Vagrant.require_version` helper: + +```ruby +Vagrant.require_version ">= 1.3.5" +``` + +In the case above, the Vagrantfile will only load if the version loading it +is Vagrant 1.3.5 or greater. + +Multiple requirements can be specified as well: + +```ruby +Vagrant.require_version ">= 1.3.5", "< 1.4.0" +``` diff --git a/website/pages/docs/vagrantfile/version.html.md b/website/pages/docs/vagrantfile/version.html.md new file mode 100644 index 000000000..1b18bb913 --- /dev/null +++ b/website/pages/docs/vagrantfile/version.html.md @@ -0,0 +1,64 @@ +--- +layout: 'docs' +page_title: 'Configuration Version - Vagrantfile' +sidebar_current: 'vagrantfile-version' +description: |- + Configuration versions are the mechanism by which Vagrant 1.1+ is able to + remain backwards compatible with Vagrant 1.0.x Vagrantfiles, while introducing + dramatically new features and configuration options. +--- + +# Configuration Version + +Configuration versions are the mechanism by which Vagrant 1.1+ is able +to remain [backwards compatible](/docs/installation/backwards-compatibility.html) +with Vagrant 1.0.x Vagrantfiles, while introducing dramatically new features +and configuration options. + +If you run `vagrant init` today, the Vagrantfile will be in roughly the +following format: + +```ruby +Vagrant.configure("2") do |config| + # ... +end +``` + +The `"2"` in the first line above represents the version of the configuration +object `config` that will be used for configuration for that block (the +section between the `do` and the `end`). This object can be very +different from version to version. + +Currently, there are only two supported versions: "1" and "2". Version 1 +represents the configuration from Vagrant 1.0.x. "2" represents the configuration +for 1.1+ leading up to 2.0.x. + +When loading Vagrantfiles, Vagrant uses the proper configuration object +for each version, and properly merges them, just like any other configuration. + +The important thing to understand as a general user of Vagrant is that +_within a single configuration section_, only a single version can be used. +You cannot use the new `config.vm.provider` configurations in a version 1 +configuration section. Likewise, `config.vm.forward_port` will not work +in a version 2 configuration section (it was renamed). + +If you want, you can mix and match multiple configuration versions in the +same Vagrantfile. This is useful if you found some useful configuration +snippet or something that you want to use. Example: + +```ruby +Vagrant.configure("1") do |config| + # v1 configs... +end + +Vagrant.configure("2") do |config| + # v2 configs... +end +``` + +
+ What is Vagrant::Config.run? + You may see this in Vagrantfiles. This was actually how Vagrant 1.0.x + did configuration. In Vagrant 1.1+, this is synonymous with + Vagrant.configure("1"). +
diff --git a/website/pages/docs/vagrantfile/winrm_settings.html.md b/website/pages/docs/vagrantfile/winrm_settings.html.md new file mode 100644 index 000000000..948739f3b --- /dev/null +++ b/website/pages/docs/vagrantfile/winrm_settings.html.md @@ -0,0 +1,79 @@ +--- +layout: 'docs' +page_title: 'config.winrm - Vagrantfile' +sidebar_current: 'vagrantfile-winrm' +description: |- + The settings within "config.winrm" relate to configuring how Vagrant + will access your Windows guest over WinRM. As with most Vagrant settings, the + defaults are typically fine, but you can fine tune whatever you would like. +--- + +# WinRM Settings + +**Config namespace: `config.winrm`** + +The settings within `config.winrm` relate to configuring how Vagrant +will access your Windows guest over WinRM. As with most Vagrant settings, the +defaults are typically fine, but you can fine tune whatever you would like. + +These settings are only used if you've set your communicator type to `:winrm`. + +## Available Settings + +- `config.winrm.username` (string) - This sets the username that Vagrant will use + to login to the WinRM web service by default. Providers are free to override + this if they detect a more appropriate user. By default this is "vagrant," + since that is what most public boxes are made as. + +- `config.winrm.password` (string) - This sets a password that Vagrant will use to + authenticate the WinRM user. By default this is "vagrant," since that is + what most public boxes are made as. + +- `config.winrm.host` (string) - The hostname or IP to connect to the WinRM service. + By default this is empty, because the provider usually figures this out for + you. + +- `config.winrm.port` (integer) - The WinRM port to connect to, by default 5985. If ssl + is enabled, the default port is 5986. + +- `config.winrm.guest_port` (integer) - The port on the guest that WinRM is running on. + This is used by some providers to detect forwarded ports for WinRM. For + example, if this is set to 5985 (the default), and Vagrant detects a forwarded + port to port 5985 on the guest from port 4567 on the host, Vagrant will attempt + to use port 4567 to talk to the guest if there is no other option. + +- `config.winrm.transport` (symbol)- The transport used for WinRM communication. + Valid settings include: `:negotiate`, `:ssl`, and `:plaintext`. The default is `:negotiate`. + +- `config.winrm.basic_auth_only` (boolean) - Whether to use Basic Authentication. Defaults + to `false`. If set to `true` you should also use the `:plaintext` transport setting and + the Windows machine must be configured appropriately. + + **Note:** It is strongly recommended that you only use basic authentication for + debugging purposes. Credentials will be transferred in plain text. + +- `config.winrm.execution_time_limit` (string) - The amount of time that is allowed to + complete task. This defaults to "PT2H", that is 2 hours. + +- `config.winrm.ssl_peer_verification` (boolean) - When set to `false` ssl certificate + validation is not performed. By default this is true. + +- `config.winrm.timeout` (integer) - The maximum amount of time to wait for a response + from the endpoint. This defaults to 1800 seconds. Note that this will not "timeout" + commands that exceed this amount of time to process, it just requires the endpoint to + report the status of the command before the given amount of time passes. + +- `config.winrm.max_tries` (integer) - The maximum number of times to retry opening + a shell after failure. This defaults to 20. + +- `config.winrm.retry_delay` (integer) - The amount of time to wait between retries and + defaults to 2 seconds. + +- `config.winrm.codepage` (string) - The WINRS_CODEPAGE which is the client's console + output code page. By default this is not set by Vagrant. + + **Note:** Versions of Windows older than Windows 7/Server 2008 R2 may exhibit + undesirable behavior using the default UTF-8 codepage. When using these older + versions of Windows, its best to use the native code page of the server's locale. + For example, en-US servers will have a codepage of 437. The Windows `chcp` command + can be used to determine the value of the native codepage. diff --git a/website/pages/docs/vagrantfile/winssh_settings.html.md b/website/pages/docs/vagrantfile/winssh_settings.html.md new file mode 100644 index 000000000..48ee12f58 --- /dev/null +++ b/website/pages/docs/vagrantfile/winssh_settings.html.md @@ -0,0 +1,78 @@ +--- +layout: 'docs' +page_title: 'config.winssh - Vagrantfile' +sidebar_current: 'vagrantfile-winssh' +description: |- + The settings within "config.winssh" relate to configuring how Vagrant + will access your machine over Windows OpenSSH. As with most Vagrant settings, the + defaults are typically fine, but you can fine tune whatever you would like. +--- + +# WinSSH + +The WinSSH communicator is built specifically for the Windows native +port of OpenSSH. It does not rely on a POSIX-like environment which +removes the requirement of extra software installation (like cygwin) +for proper functionality. + +For more information, see the [Win32-OpenSSH project page](https://github.com/PowerShell/Win32-OpenSSH/). + +# WinSSH Settings + +The WinSSH communicator uses the same connection configuration options +as the SSH communicator. These settings provide the information for the +communicator to establish a connection to the VM. + +The configuration options below are specific to the WinSSH communicator. + +**Config namespace: `config.winssh`** + +## Available Settings + +- `config.winssh.forward_agent` (boolean) - If `true`, agent forwarding over SSH + connections is enabled. Defaults to false. + +- `config.winssh.forward_env` (array of strings) - An array of host environment + variables to forward to the guest. If you are familiar with OpenSSH, this corresponds + to the `SendEnv` parameter. + + ```ruby + config.winssh.forward_env = ["CUSTOM_VAR"] + ``` + +- `config.winssh.proxy_command` (string) - A command-line command to execute that + receives the data to send to SSH on stdin. This can be used to proxy the SSH connection. + `%h` in the command is replaced with the host and `%p` is replaced with the port. + +- `config.winssh.keep_alive` (boolean) - If `true`, this setting SSH will send keep-alive + packets every 5 seconds by default to keep connections alive. + +- `config.winssh.shell` (string) - The shell to use when executing SSH commands from + Vagrant. By default this is `powershell`. Valid values are `"cmd"` or `"powershell"`. + When the WinSSH provider is enabled, this shell will only be used internally. When + running `vagrant ssh` you will be provided the shell configured by the guest. + +- `config.winssh.export_command_template` (string) - The template used to generate + exported environment variables in the active session. This can be useful + when using a Bourne incompatible shell like C shell. The template supports + two variables which are replaced with the desired environment variable key and + environment variable value: `%ENV_KEY%` and `%ENV_VALUE%`. The default template + for a `cmd` configured shell is: + + ```ruby + config.winssh.export_command_template = 'set %ENV_KEY%="%ENV_VALUE%"' + ``` + + The default template for a `powershell` configured shell is: + + ```ruby + config.winssh.export_command_template = '$env:%ENV_KEY%="%ENV_VALUE%"' + ``` + +- `config.winssh.sudo_command` (string) - The command to use when executing a command + with `sudo`. This defaults to `%c` (assumes vagrant user is an administrator + and needs no escalation). The `%c` will be replaced by the command that is + being executed. + +- `config.winssh.upload_directory` (string) - The upload directory used on the guest + to store scripts for execute. This is set to `C:\Windows\Temp` by default. diff --git a/website/pages/docs/virtualbox/boxes.html.md b/website/pages/docs/virtualbox/boxes.html.md new file mode 100644 index 000000000..5a50ac831 --- /dev/null +++ b/website/pages/docs/virtualbox/boxes.html.md @@ -0,0 +1,165 @@ +--- +layout: 'docs' +page_title: 'Creating a Base Box - VirtualBox Provider' +sidebar_current: 'providers-virtualbox-boxes' +description: |- + As with every Vagrant provider, the Vagrant VirtualBox provider has a custom + box format that affects how base boxes are made. +--- + +# Creating a Base Box + +As with [every Vagrant provider](/docs/providers/basic_usage.html), the +Vagrant VirtualBox provider has a custom box format that affects how base +boxes are made. + +Prior to reading this, you should read the +[general guide to creating base boxes](/docs/boxes/base.html). Actually, +it would probably be most useful to keep this open in a separate tab +as you may be referencing it frequently while creating a base box. That +page contains important information about common software to install +on the box. + +Additionally, it is helpful to understand the +[basics of the box file format](/docs/boxes/format.html). + +
+ Advanced topic! This is a reasonably advanced topic that + a beginning user of Vagrant does not need to understand. If you are + just getting started with Vagrant, skip this and use an available + box. If you are an experienced user of Vagrant and want to create + your own custom boxes, this is for you. +
+ +## Virtual Machine + +The virtual machine created in VirtualBox can use any configuration you would +like, but Vagrant has some hard requirements: + +- The first network interface (adapter 1) _must_ be a NAT adapter. + Vagrant uses this to connect the first time. + +- The MAC address of the first network interface (the NAT adapter) + should be noted, since you will need to put it in a Vagrantfile + later as the value for `config.vm.base_mac`. To get this value, use + the VirtualBox GUI. + +Other than the above, you are free to customize the base virtual machine +as you see fit. + +## Additional Software + +In addition to the software that should be installed based on the +[general guide to creating base boxes](/docs/boxes/base.html), +VirtualBox base boxes require some additional software. + +### VirtualBox Guest Additions + +[VirtualBox Guest Additions](https://www.virtualbox.org/manual/ch04.html) +must be installed so that things such as shared folders can function. +Installing guest additions also usually improves performance since the guest +OS can make some optimizations by knowing it is running within VirtualBox. + +Before installing the guest additions, you will need the linux kernel headers +and the basic developer tools. On Ubuntu, you can easily install these like +so: + +``` +$ sudo apt-get install linux-headers-$(uname -r) build-essential dkms +``` + +#### To install via the GUI: + +Next, make sure that the guest additions image is available by using the +GUI and clicking on "Devices" followed by "Install Guest Additions". +Then mount the CD-ROM to some location. On Ubuntu, this usually looks like +this: + +``` +$ sudo mount /dev/cdrom /media/cdrom +``` + +Finally, run the shell script that matches your system to install the +guest additions. For example, for Linux on x86, it is the following: + +``` +$ sudo sh /media/cdrom/VBoxLinuxAdditions.run +``` + +If the command succeeds, then the guest additions are now installed! + +#### To install via the command line: + +You can find the appropriate guest additions version to match your VirtualBox +version by selecting the appropriate version +[here](http://download.virtualbox.org/virtualbox/). The examples below use +4.3.8, which was the latest VirtualBox version at the time of writing. + +``` +wget http://download.virtualbox.org/virtualbox/4.3.8/VBoxGuestAdditions_4.3.8.iso +sudo mkdir /media/VBoxGuestAdditions +sudo mount -o loop,ro VBoxGuestAdditions_4.3.8.iso /media/VBoxGuestAdditions +sudo sh /media/VBoxGuestAdditions/VBoxLinuxAdditions.run +rm VBoxGuestAdditions_4.3.8.iso +sudo umount /media/VBoxGuestAdditions +sudo rmdir /media/VBoxGuestAdditions +``` + +If you did not install a Desktop environment when you installed the operating +system, as recommended to reduce size, the install of the VirtualBox additions +should warn you about the lack of OpenGL or Window System Drivers, but you can +safely ignore this. + +If the commands succeed, then the guest additions are now installed! + +## Packaging the Box + +Vagrant includes a simple way to package VirtualBox base boxes. Once you've +installed all the software you want to install, you can run this command: + +``` +$ vagrant package --base my-virtual-machine +``` + +Where "my-virtual-machine" is replaced by the name of the virtual machine +in VirtualBox to package as a base box. + +It will take a few minutes, but after it is complete, a file "package.box" +should be in your working directory which is the new base box. At this +point, you've successfully created a base box! + +## Raw Contents + +This section documents the actual raw contents of the box file. This is not +as useful when creating a base box but can be useful in debugging issues +if necessary. + +A VirtualBox base box is an archive of the resulting files of +[exporting](https://www.virtualbox.org/manual/ch08.html#vboxmanage-export) +a VirtualBox virtual machine. Here is an example of what is contained +in such a box: + +``` +$ tree +. +|-- Vagrantfile +|-- box-disk1.vmdk +|-- box.ovf +|-- metadata.json + +0 directories, 4 files +``` + +In addition to the files from exporting a VirtualBox VM, there is +the "metadata.json" file used by Vagrant itself. + +Also, there is a "Vagrantfile." This contains some configuration to +properly set the MAC address of the NAT network device, since VirtualBox +requires this to be correct in order to function properly. If you are +not using `vagrant package --base` above, you will have to set the +`config.vm.base_mac` setting in this Vagrantfile to the MAC address +of the NAT device without colons. + +When bringing up a VirtualBox backed machine, Vagrant +[imports](https://www.virtualbox.org/manual/ch08.html#vboxmanage-import) +the "box.ovf" file found in the box contents. diff --git a/website/pages/docs/virtualbox/common-issues.html.md b/website/pages/docs/virtualbox/common-issues.html.md new file mode 100644 index 000000000..3dcee0c27 --- /dev/null +++ b/website/pages/docs/virtualbox/common-issues.html.md @@ -0,0 +1,33 @@ +--- +layout: 'docs' +page_title: 'Common Issues - VirtualBox Provider' +sidebar_current: 'providers-virtualbox-issues' +description: |- + This page lists some common issues people run into with Vagrant and VirtualBox + as well as solutions for those issues. +--- + +# Common Issues + +This page lists some common issues people run into with Vagrant and VirtualBox +as well as solutions for those issues. + +## Hanging on Windows + +If Vagrant commands are hanging on Windows because they're communicating +to VirtualBox, this may be caused by a permissions issue with VirtualBox. +This is easy to fix. Starting VirtualBox as a normal user or as an +administrator will prevent you from using it in the opposite way. Please keep +in mind that when Vagrant interacts with VirtualBox, it will interact with +it with the same access level as the console running Vagrant. + +To fix this issue, completely shut down all VirtualBox machines and GUIs. +Wait a few seconds. Then, launch VirtualBox only with the access level you +wish to use. + +## DNS Not Working + +If DNS is not working within your VM, then you may need to enable +a DNS proxy (built-in to VirtualBox). Please [see the StackOverflow answers +here](https://serverfault.com/questions/453185/vagrant-virtualbox-dns-10-0-2-3-not-working) +for a guide on how to do that. diff --git a/website/pages/docs/virtualbox/configuration.html.md b/website/pages/docs/virtualbox/configuration.html.md new file mode 100644 index 000000000..7a3b0121e --- /dev/null +++ b/website/pages/docs/virtualbox/configuration.html.md @@ -0,0 +1,125 @@ +--- +layout: 'docs' +page_title: 'Configuration - VirtualBox Provider' +sidebar_current: 'providers-virtualbox-configuration' +description: |- + The VirtualBox provider exposes some additional configuration options + that allow you to more finely control your VirtualBox-powered Vagrant + environments. +--- + +# Configuration + +The VirtualBox provider exposes some additional configuration options +that allow you to more finely control your VirtualBox-powered Vagrant +environments. + +## GUI vs. Headless + +By default, VirtualBox machines are started in headless mode, meaning +there is no UI for the machines visible on the host machine. Sometimes, +you want to have a UI. Common use cases include wanting to see a browser +that may be running in the machine, or debugging a strange boot issue. +You can easily tell the VirtualBox provider to boot with a GUI: + +```ruby +config.vm.provider "virtualbox" do |v| + v.gui = true +end +``` + +## Virtual Machine Name + +You can customize the name that appears in the VirtualBox GUI by +setting the `name` property. By default, Vagrant sets it to the containing +folder of the Vagrantfile plus a timestamp of when the machine was created. +By setting another name, your VM can be more easily identified. + +```ruby +config.vm.provider "virtualbox" do |v| + v.name = "my_vm" +end +``` + +## Default NIC Type + +By default Vagrant will not set the NIC type for network interfaces. This +allows VirtualBox to apply the default NIC type for the guest. If you would +like to use a specific NIC type by default for guests, set the `default_nic_type` +option: + +```ruby +config.vm.provider "virtualbox" do |v| + v.default_nic_type = "82543GC" +end +``` + +## Linked Clones + +By default new machines are created by importing the base box. For large +boxes this produces a large overhead in terms of time (the import operation) +and space (the new machine contains a copy of the base box's image). +Using linked clones can drastically reduce this overhead. + +Linked clones are based on a master VM, which is generated by importing the +base box only once the first time it is required. For the linked clones only +differencing disk images are created where the parent disk image belongs to +the master VM. + +```ruby +config.vm.provider "virtualbox" do |v| + v.linked_clone = true +end +``` + +To have backward compatibility: + +```ruby +config.vm.provider 'virtualbox' do |v| + v.linked_clone = true if Gem::Version.new(Vagrant::VERSION) >= Gem::Version.new('1.8.0') +end +``` + +If you do not want backward compatibility and want to force users to +support linked cloning, you can use `Vagrant.require_version` with 1.8. + +
+ Note: the generated master VMs are currently not removed + automatically by Vagrant. This has to be done manually. However, a master + VM can only be removed when there are no linked clones connected to it. +
+ +## VBoxManage Customizations + +[VBoxManage](https://www.virtualbox.org/manual/ch08.html) is a utility that can +be used to make modifications to VirtualBox virtual machines from the command +line. + +Vagrant exposes a way to call any command against VBoxManage just prior +to booting the machine: + +```ruby +config.vm.provider "virtualbox" do |v| + v.customize ["modifyvm", :id, "--cpuexecutioncap", "50"] +end +``` + +In the example above, the VM is modified to have a host CPU execution +cap of 50%, meaning that no matter how much CPU is used in the VM, no +more than 50% would be used on your own host machine. Some details: + +- The `:id` special parameter is replaced with the ID of the virtual + machine being created, so when a VBoxManage command requires an ID, you + can pass this special parameter. + +- Multiple `customize` directives can be used. They will be executed in the + order given. + +There are some convenience shortcuts for memory and CPU settings: + +```ruby +config.vm.provider "virtualbox" do |v| + v.memory = 1024 + v.cpus = 2 +end +``` diff --git a/website/pages/docs/virtualbox/index.html.md b/website/pages/docs/virtualbox/index.html.md new file mode 100644 index 000000000..241c7da51 --- /dev/null +++ b/website/pages/docs/virtualbox/index.html.md @@ -0,0 +1,26 @@ +--- +layout: 'docs' +page_title: 'VirtualBox Provider' +sidebar_current: 'providers-virtualbox' +description: |- + Vagrant comes with support out of the box for VirtualBox, a free, + cross-platform consumer virtualization product. +--- + +# VirtualBox + +Vagrant comes with support out of the box for [VirtualBox](https://www.virtualbox.org), +a free, cross-platform consumer virtualization product. + +The VirtualBox provider is compatible with VirtualBox versions 4.0.x, 4.1.x, +4.2.x, 4.3.x, 5.0.x, 5.1.x, 5.2.x, 6.0.x, and 6.1.x. Other versions are unsupported and the provider +will display an error message. Please note that beta and pre-release versions +of VirtualBox are not supported and may not be well-behaved. + +VirtualBox must be installed on its own prior to using the provider, or +the provider will display an error message asking you to install it. +VirtualBox can be installed by [downloading](https://www.virtualbox.org/wiki/Downloads) +a package or installer for your operating system and using standard procedures +to install that package. + +Use the navigation to the left to find a specific VirtualBox topic to read more about. diff --git a/website/pages/docs/virtualbox/networking.html.md b/website/pages/docs/virtualbox/networking.html.md new file mode 100644 index 000000000..457918859 --- /dev/null +++ b/website/pages/docs/virtualbox/networking.html.md @@ -0,0 +1,74 @@ +--- +layout: 'docs' +page_title: 'Networking - VirtualBox Provider' +sidebar_current: 'providers-virtualbox-networking' +description: |- + The Vagrant VirtualBox provider supports using the private network as a + VirtualBox internal network. By default, private networks are host-only + networks, because those are the easiest to work with. +--- + +# Networking + +## VirtualBox Host-Only Networks + +By default, private networks are [host-only networks](https://www.virtualbox.org/manual/ch06.html#network_hostonly), +because those are the easiest to work with. In VirtualBox, since you can +create multiple host-only networks, it is also possible to specify which +host-only network you want the Vagrant VirtualBox provider to use for +a given interface. To do this, use the `name` argument with the name of +the host-only interface to use. + +```ruby +Vagrant.configure("2") do |config| + config.vm.network "private_network", type: "dhcp", + name: "vboxnet3" +end +``` + +## VirtualBox Internal Network + +The Vagrant VirtualBox provider supports using the private network as a +VirtualBox [internal network](https://www.virtualbox.org/manual/ch06.html#network_internal). +By default, private networks are host-only networks, because those are the +easiest to work with. However, internal networks can be enabled as well. + +To specify a private network as an internal network for VirtualBox +use the `virtualbox__intnet` option with the network. The `virtualbox__` +(double underscore) prefix tells Vagrant that this option is only for the +VirtualBox provider. + +```ruby +Vagrant.configure("2") do |config| + config.vm.network "private_network", ip: "192.168.50.4", + virtualbox__intnet: true +end +``` + +Additionally, if you want to specify that the VirtualBox provider join +a specific internal network, specify the name of the internal network: + +```ruby +Vagrant.configure("2") do |config| + config.vm.network "private_network", ip: "192.168.50.4", + virtualbox__intnet: "mynetwork" +end +``` + +## VirtualBox NIC Type + +You can specify a specific NIC type for the created network interface +by using the `nic_type` parameter. This is not prefixed by `virtualbox__` +for legacy reasons, but is VirtualBox-specific. + +This is an advanced option and should only be used if you know what +you are using, since it can cause the network device to not work at all. + +Example: + +```ruby +Vagrant.configure("2") do |config| + config.vm.network "private_network", ip: "192.168.50.4", + nic_type: "virtio" +end +``` diff --git a/website/pages/docs/virtualbox/usage.html.md b/website/pages/docs/virtualbox/usage.html.md new file mode 100644 index 000000000..01e80cacb --- /dev/null +++ b/website/pages/docs/virtualbox/usage.html.md @@ -0,0 +1,19 @@ +--- +layout: 'docs' +page_title: 'Usage - VirtualBox Provider' +sidebar_current: 'providers-virtualbox-usage' +description: |- + The Vagrant VirtualBox provider is used just like any other provider. Please + read the general basic usage page for providers. +--- + +# Usage + +The Vagrant VirtualBox 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 `virtualbox`. + +The Vagrant VirtualBox provider does not support parallel execution at this +time. Specifying the `--parallel` option will have no effect. diff --git a/website/pages/docs/vmware/boxes.html.md b/website/pages/docs/vmware/boxes.html.md new file mode 100644 index 000000000..2118c5021 --- /dev/null +++ b/website/pages/docs/vmware/boxes.html.md @@ -0,0 +1,146 @@ +--- +layout: 'docs' +page_title: 'Box Format - VMware Provider' +sidebar_current: 'providers-vmware-boxes' +description: |- + As with every Vagrant provider, the Vagrant VMware providers have a custom box + format. +--- + +# Boxes + +As with [every Vagrant provider](/docs/providers/basic_usage.html), the +Vagrant VMware providers have a custom box format. + +This page documents the format so that you can create your own base boxes. +Note that currently you must make these base boxes by hand. A future release +of Vagrant will provide additional mechanisms for automatically creating such +images. + +
+ Note: This is a reasonably advanced topic that + a beginning user of Vagrant does not need to understand. If you are + just getting started with Vagrant, skip this and use an available + box. If you are an experienced user of Vagrant and want to create + your own custom boxes, this is for you. +
+ +Prior to reading this page, please understand the +[basics of the box file format](/docs/boxes/format.html). + +## Contents + +A VMware base box is a compressed archive of the necessary contents +of a VMware "vmwarevm" file. Here is an example of what is contained +in such a box: + +``` +$ tree +. +|-- disk-s001.vmdk +|-- disk-s002.vmdk +|-- ... +|-- disk.vmdk +|-- metadata.json +|-- bionic64.nvram +|-- bionic64.vmsd +|-- bionic64.vmx +|-- bionic64.vmxf + +0 directories, 17 files +``` + +The files that are strictly required for a VMware machine to function are: +nvram, vmsd, vmx, vmxf, and vmdk files. + +There is also the "metadata.json" file used by Vagrant itself. This file +contains nothing but the defaults which are documented on the +[box format](/docs/boxes/format.html) page. + +When bringing up a VMware backed machine, Vagrant copies all of the contents +in the box into a privately managed "vmwarevm" folder, and uses the first +"vmx" file found to control the machine. + +
+ Vagrant 1.8 and higher support linked clones. Prior versions + of Vagrant do not support linked clones. For more information on + linked clones, please see the documentation. +
+ +## VMX Whitelisting + +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 +device when creating a new instance and inserted a new configuration. With +the introduction of ["predictable network interface names"][iface-names] this +approach can cause unexpected behaviors or errors with VMware Vagrant boxes. +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 +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: + +- `ethernet*.pcislotnumber` + +If the newly created box does not depend on Vagrant's existing behavior of +modifying this setting, it can disable Vagrant from applying the modification +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 + end +end +``` + +This will prevent Vagrant from displaying a warning to the user as well as +disable the VMX settings modifications. + +## Installed Software + +Base boxes for VMware should have the following software installed, as +a bare minimum: + +- SSH server with key-based authentication setup. If you want the box to + work with default Vagrant settings, the SSH user must be set to accept + the [insecure keypair](https://github.com/hashicorp/vagrant/blob/master/keys/vagrant.pub) + that ships with Vagrant. + +- [VMware Tools](https://kb.vmware.com/kb/340) so that things such as shared + folders can function. There are many other benefits to installing the tools, + such as improved networking performance. + +## Optimizing Box Size + +Prior to packaging up a box, you should shrink the hard drives as much as +possible. This can be done with `vmware-vdiskmanager` which is usually +found in `/Applications/VMware Fusion.app/Contents/Library` for VMware Fusion. You first +want to defragment then shrink the drive. Usage shown below: + +``` +$ vmware-vdiskmanager -d /path/to/main.vmdk +... +$ vmware-vdiskmanager -k /path/to/main.vmdk +... +``` + +## Packaging + +Remove any extraneous files from the "vmwarevm" folder +and package it. Be sure to compress the tar with gzip (done below in a +single command) since VMware hard disks are not compressed by default. + +``` +$ cd /path/to/my/vm.vmwarevm +$ tar cvzf custom.box ./* +``` + +[iface-names]: https://www.freedesktop.org/wiki/Software/systemd/PredictableNetworkInterfaceNames/ diff --git a/website/pages/docs/vmware/configuration.html.md b/website/pages/docs/vmware/configuration.html.md new file mode 100644 index 000000000..a6a406a4b --- /dev/null +++ b/website/pages/docs/vmware/configuration.html.md @@ -0,0 +1,124 @@ +--- +layout: 'docs' +page_title: 'Configuration- VMware Provider' +sidebar_current: 'providers-vmware-configuration' +description: |- + While Vagrant VMware providers are 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. +--- + +# Configuration + +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. + +Configuration settings for the provider are set in the Vagrantfile: + +```ruby +Vagrant.configure("2") do |config| + config.vm.box = "my-box" + config.vm.provider "vmware_desktop" do |v| + v.gui = true + end +end +``` + +## 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. +Usually, this is fine. For some people, for example those who use a +differential backup software such as Time Machine, this is very annoying +because you cannot regularly ignore giant virtual machines as part of backups. + +The directory where the provider clones the virtual machine can be +customized by setting the `VAGRANT_VMWARE_CLONE_DIRECTORY` environmental +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 + +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 +importing the base box. + +Linked clones are based on a master VM, which is generated by importing the +base box only once the first time it is required. For the linked clones only +differencing disk images are created where the parent disk image belongs to +the master VM. To disable linked clones: + +```ruby +config.vm.provider "vmware_desktop" do |v| + v.linked_clone = false +end +``` + +### VMX Customization + +If you want to add or remove specific keys from the VMX file, you can do +that: + +```ruby +config.vm.provider "vmware_desktop" do |v| + v.vmx["custom-key"] = "value" + v.vmx["another-key"] = nil +end +``` + +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. + +VMX customization is done as the final step before the VMware machine is +booted, so you have the ability to possibly undo or misconfigure things +that Vagrant has set up itself. + +VMX is an undocumented format and there is no official reference for +the available keys and values. This customization option is exposed for +people who have knowledge of exactly what they want. + +The most common keys people look for are setting memory and CPUs. +The example below sets both: + +```ruby +config.vm.provider "vmware_desktop" do |v| + v.vmx["memsize"] = "1024" + v.vmx["numvcpus"] = "2" +end +``` diff --git a/website/pages/docs/vmware/index.html.md b/website/pages/docs/vmware/index.html.md new file mode 100644 index 000000000..c8bdbe294 --- /dev/null +++ b/website/pages/docs/vmware/index.html.md @@ -0,0 +1,37 @@ +--- +layout: 'docs' +page_title: 'VMware Provider' +sidebar_current: 'providers-vmware' +description: |- + HashiCorp develops an official VMware Fusion and VMware Workstation provider + for Vagrant. This provider allows Vagrant to power VMware based machines and + take advantage of the improved stability and performance that VMware software + offers. +--- + +# VMware + +[HashiCorp](https://www.hashicorp.com) develops an official +[VMware Fusion](https://www.vmware.com/products/fusion/overview.html) +and [VMware Workstation](https://www.vmware.com/products/workstation/)  +[provider](/docs/providers/) for Vagrant. This provider allows +Vagrant to power VMware based machines and take advantage of the +improved stability and performance that VMware software offers. + +Learn more about the VMware providers on the +[VMware provider](/vmware) page on +the Vagrant website. + +This provider is a drop-in replacement for VirtualBox, meaning that every +VirtualBox feature that Vagrant supports is fully functional in VMware as +well. However, there are some VMware-specific things such as box formats, +configurations, etc. that are documented here. + +For the most up-to-date information on compatibility and supported versions of +VMware Fusion and VMware Workstation, please visit the +[Vagrant VMware product page](/vmware). Please note +that VMware Fusion and VMware Workstation are third-party products that must be +purchased and installed separately prior to using the provider. + +Use the navigation to the left to find a specific VMware topic to read +more about. diff --git a/website/pages/docs/vmware/installation.html.md b/website/pages/docs/vmware/installation.html.md new file mode 100644 index 000000000..475ad1c2a --- /dev/null +++ b/website/pages/docs/vmware/installation.html.md @@ -0,0 +1,156 @@ +--- +layout: 'docs' +page_title: 'Installation - VMware Provider' +sidebar_current: 'providers-vmware-installation' +description: |- + The Vagrant VMware provider can be installed using the standard plugin + installation procedure. +--- + +# Installation + +If you are upgrading from the Vagrant VMware Workstation or Vagrant +VMware Fusion plugins, please halt or destroy all VMware VMs currently +being managed by Vagrant. Then continue with the instructions below. + +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). + +Next, install the Vagrant VMware provider plugin using the standard plugin +installation procedure: + +```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 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 +purchasing a license, you will receive a license file in your inbox. Download +this file and save it to a temporary location on your computer. + +
+ Warning! You cannot use your VMware product license as a + Vagrant VMware plugin license. They are separate commercial products, each + requiring their own license. +
+ +After installing the Vagrant VMware Desktop plugin for your system, you +will need to install the license: + +```shell +$ vagrant plugin license vagrant-vmware-desktop ~/license.lic +``` + +The first parameter is the name of the plugin, and the second parameter is the +path to the license file on disk. Please be sure to replace `~/license.lic` +with the path where you temporarily saved the downloaded license file to disk. +After you have installed the plugin license, you may remove the temporary file. + +To verify the license installation, run: + +```shell +$ vagrant +``` + +If the license is not installed correctly, you will see an error message. + +## Upgrading to v1.x + +It is **extremely important** that the VMware plugin is upgraded to 1.0.0 or +above. This release resolved critical security vulnerabilities. To learn more, +please [read our release announcement](https://www.hashicorp.com/blog/introducing-the-vagrant-vmware-desktop-plugin). + +After upgrading, please verify that the following paths are empty. The upgrade +process should remove these for you, but for security reasons it is important +to double check. If you're a new user or installing the VMware provider on a +new machine, you may skip this step. If you're a Windows user, you may skip this +step as well. + +The path `~/.vagrant.d/gems/*/vagrant-vmware-{fusion,workstation}` +should no longer exist. The gem `vagrant-vmware-desktop` may exist since this +is the name of the new plugin. If the old directories exist, remove them. An +example for a Unix-like shell is shown below: + +```shell +# Check if they exist and verify that they're the correct paths as shown below. +$ ls ~/.vagrant.d/gems/*/vagrant-vmware-{fusion,workstation} +... + +# Remove them +$ rm -rf ~/.vagrant.d/gems/*/vagrant-vmware-{fusion,workstation} +``` + +## Updating the Vagrant VMware Desktop plugin + +The Vagrant VMware Desktop plugin can be updated directly from Vagrant. Run the +following command to update Vagrant to the latest version of the Vagrant VMware +Desktop plugin: + +```shell +$ 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 +$ vagrant plugin install vagrant-vmware-desktop +``` + +## Support + +If you have any issues purchasing, installing, or using the Vagrant VMware +plugins, please [contact support](mailto:support@hashicorp.com). To +expedite the support process, please include the +[Vagrant debug output](/docs/other/debugging.html) as a Gist if +applicable. This will help us more quickly diagnose your issue. diff --git a/website/pages/docs/vmware/kernel-upgrade.html.md b/website/pages/docs/vmware/kernel-upgrade.html.md new file mode 100644 index 000000000..daf77497c --- /dev/null +++ b/website/pages/docs/vmware/kernel-upgrade.html.md @@ -0,0 +1,61 @@ +--- +layout: 'docs' +page_title: 'Kernel Upgrade - VMware Provider' +sidebar_current: 'providers-vmware-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 = <